/*

 * Copyright (C) 2014 - 2019 Intel Corporation.

 * All rights reserved.

 *

 * Redistribution and use in source and binary forms, with or without

 * modification, are permitted provided that the following conditions are met:

 * 1. Redistributions of source code must retain the above copyright notice(s),

 *    this list of conditions and the following disclaimer.

 * 2. Redistributions in binary form must reproduce the above copyright notice(s),

 *    this list of conditions and the following disclaimer in the documentation

 *    and/or other materials provided with the distribution.

 *

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY EXPRESS

 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO

 * EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY DIRECT, INDIRECT,

 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE

 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF

 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 */

#pragma once

#ifdef __cplusplus

extern "C" {

#endif

#include <sys/types.h>

/**

 * Header file for the memkind heap manager.

 * More details in memkind(3) man page.

 *

 * API standards are described in memkind(3) man page.

 */

/// \warning EXPERIMENTAL API

#define _MEMKIND_BIT(N) (1ull << N)

/// \brief Memkind memory types

/// \warning EXPERIMENTAL API

typedef enum memkind_memtype_t {

    /**

     * Select standard memory, the same as process use.

     */

    MEMKIND_MEMTYPE_DEFAULT = _MEMKIND_BIT(0),

    /**

     * Select high bandwidth memory (HBM).

     * There must be at least two memories with different bandwidth to

     * determine the HBM.

     */

    MEMKIND_MEMTYPE_HIGH_BANDWIDTH = _MEMKIND_BIT(1)

} memkind_memtype_t;

#undef _MEMKIND_BIT

/// \brief Memkind policy

/// \warning EXPERIMENTAL API

typedef enum memkind_policy_t {

    /**

     * Allocate local memory.

     * If there is not enough memory to satisfy the request errno is set to

     * ENOMEM and the allocated pointer is set to NULL.

     */

    MEMKIND_POLICY_BIND_LOCAL = 0,

    /**

     * Memory locality is ignored.

     * If there is not enough memory to satisfy the request errno is set to

     * ENOMEM and the allocated pointer is set to NULL.

     */

    MEMKIND_POLICY_BIND_ALL,

    /**

     * Allocate preferred memory that is local.

     * If there is not enough preferred memory to satisfy the request or

     * preferred memory is not available, the allocation will fall back on any

     * other memory.

     */

    MEMKIND_POLICY_PREFERRED_LOCAL,

    /**

     * Interleave allocation across local memory.

     * For n memory types the allocation will be interleaved across all of

     * them.

     */

    MEMKIND_POLICY_INTERLEAVE_LOCAL,

    /**

     * Interleave allocation. Locality is ignored.

     * For n memory types the allocation will be interleaved across all of

     * them.

     */

    MEMKIND_POLICY_INTERLEAVE_ALL,

    /**

     * Max policy value.

     */

    MEMKIND_POLICY_MAX_VALUE

} memkind_policy_t;

/// \brief Memkind bits definition

/// \warning EXPERIMENTAL API

/// \note The bits specify flags and masks. Bits <0,1,2,...,7> are reserved for page size, where page sizes are encoded

///       by base-2 logarithm. If the page size bits are set to zero value, than default page size will be used.

typedef enum memkind_bits_t {

    MEMKIND_MASK_PAGE_SIZE_2MB = 21ull,  /**<  Allocations backed by 2 MB page size (2^21 = 2MB) */

} memkind_bits_t;

/// \brief Memkind type definition

/// \warning EXPERIMENTAL API

typedef struct memkind *memkind_t;

/// \brief Memkind constant values

/// \warning EXPERIMENTAL API

enum memkind_const {

    MEMKIND_MAX_KIND = 512,                     /**<  Maximum number of kinds */

    MEMKIND_ERROR_MESSAGE_SIZE = 128,           /**<  Error message size */

    MEMKIND_PMEM_MIN_SIZE = (1024 * 1024 * 16)  /**<  The minimum size which allows to limit the file-backed memory partition */

};

/// \brief Memkind operation statuses

/// \warning EXPERIMENTAL API

enum {

    MEMKIND_SUCCESS = 0,                        /**<  Operation success */

    MEMKIND_ERROR_UNAVAILABLE = -1,             /**<  Error: Memory kind is not available */

    MEMKIND_ERROR_MBIND = -2,                   /**<  Error: Call to mbind() failed */

    MEMKIND_ERROR_MMAP  = -3,                   /**<  Error: Call to mmap() failed */

    MEMKIND_ERROR_MALLOC = -6,                  /**<  Error: Call to malloc() failed */

    MEMKIND_ERROR_ENVIRON = -12,                /**<  Error: Unable to parse environment variable */

    MEMKIND_ERROR_INVALID = -13,                /**<  Error: Invalid argument */

    MEMKIND_ERROR_TOOMANY = -15,                /**<  Error: Attempt to initialize more than MEMKIND_MAX_KIND number of kinds */

    MEMKIND_ERROR_BADOPS = -17,                 /**<  Error: Invalid memkind_ops structure */

    MEMKIND_ERROR_HUGETLB = -18,                /**<  Error: Unable to allocate huge pages */

    MEMKIND_ERROR_MEMTYPE_NOT_AVAILABLE = -20,  /**<  Error: Requested memory type is not available */

    MEMKIND_ERROR_OPERATION_FAILED = -21,       /**<  Error: Operation failed */

    MEMKIND_ERROR_ARENAS_CREATE = -22,          /**<  Error: Call to jemalloc's arenas.create failed */

    MEMKIND_ERROR_RUNTIME = -255                /**<  Error: Unspecified run-time error */

};

/* KIND CONFIGURATION MANAGEMENT INTERFACE */

/// \brief Memkind memory usage policy

typedef enum memkind_mem_usage_policy {

    MEMKIND_MEM_USAGE_POLICY_DEFAULT      = 0,        /**<  Default memory usage */

    MEMKIND_MEM_USAGE_POLICY_CONSERVATIVE = 1,        /**<  Minimize memory usage at all costs, */

    MEMKIND_MEM_USAGE_POLICY_MAX_VALUE

} memkind_mem_usage_policy;

/// \brief Memkind memory statistics type

typedef enum memkind_stat_type {

    MEMKIND_STAT_TYPE_RESIDENT      = 0,        /**<  Maximum number of bytes in physically resident data pages mapped */

    MEMKIND_STAT_TYPE_ACTIVE        = 1,        /**<  Total number of bytes in active pages */

    MEMKIND_STAT_TYPE_ALLOCATED     = 2,        /**<  Total number of allocated bytes */

    MEMKIND_STAT_TYPE_MAX_VALUE

} memkind_stat_type;

/// \brief Forward declaration of memkind configuration

struct memkind_config;

///

/// \brief Create a memkind configuration

/// \note STANDARD API

/// \return Memkind configuration, NULL on failure

///

struct memkind_config *memkind_config_new(void);

///

/// \brief Delete memkind configuration

/// \note STANDARD API

/// \param cfg memkind configuration

///

void memkind_config_delete(struct memkind_config *cfg);

///

/// \brief Update memkind configuration with path to specified directory parameter

/// \note STANDARD API

/// \param cfg memkind configuration

/// \param pmem_dir path to specified directory for PMEM kind

///

void memkind_config_set_path(struct memkind_config *cfg, const char *pmem_dir);

///

/// \brief Update memkind configuration with PMEM kind size

/// \note STANDARD API

/// \param cfg memkind configuration

/// \param pmem_size size limit for PMEM kind

///

void memkind_config_set_size(struct memkind_config *cfg, size_t pmem_size);

///

/// \brief Update memkind configuration with memory usage policy parameter

/// \note STANDARD API

/// \param cfg memkind configuration

/// \param policy memkind memory usage policy

///

void memkind_config_set_memory_usage_policy(struct memkind_config *cfg,

                                            memkind_mem_usage_policy policy);

///

/// \brief Create kind that allocates memory with specific memory type, memory binding policy and flags.

/// \warning EXPERIMENTAL API

/// \note Currently implemented memory type and policy configurations:

///.      {MEMKIND_MEMTYPE_DEFAULT, MEMKIND_POLICY_PREFERRED_LOCAL},

///.      {MEMKIND_MEMTYPE_HIGH_BANDWIDTH, MEMKIND_POLICY_BIND_LOCAL},

///       {MEMKIND_MEMTYPE_HIGH_BANDWIDTH, MEMKIND_POLICY_PREFERRED_LOCAL},

///       {MEMKIND_MEMTYPE_HIGH_BANDWIDTH, MEMKIND_POLICY_INTERLEAVE_ALL},

///       {MEMKIND_MEMTYPE_DEFAULT | MEMKIND_MEMTYPE_HIGH_BANDWIDTH, MEMKIND_POLICY_INTERLEAVE_ALL}.

/// \param memtype_flags determine the memory types to allocate from by combination of memkind_memtype_t values.

///        This field cannot have zero value.

/// \param policy specify policy for page binding to memory types selected by  memtype_flags.

///        This field must be set to memkind_policy_t value. If policy is set to MEMKIND_POLICY_PREFERRED_LOCAL then only one memory

///        type must be selected. Note: the value cannot be set to MEMKIND_POLICY_MAX_VALUE.

/// \param flags the field must be set to a combination of memkind_bits_t values.

/// \param kind pointer to kind which will be created

/// \return Memkind operation status, MEMKIND_SUCCESS on success, MEMKIND_ERROR_MEMTYPE_NOT_AVAILABLE or MEMKIND_ERROR_INVALID on failure

///

int memkind_create_kind(memkind_memtype_t memtype_flags,

                        memkind_policy_t policy,

                        memkind_bits_t flags,

                        memkind_t *kind);

///

/// \brief Destroy previously created kind object, which must have been returned

///        by a call to memkind_create_kind() or memkind_create_pmem().

///        The function has undefined behavior when the handle is invalid or

///        memkind_destroy_kind(kind) was already called before

/// \warning EXPERIMENTAL API

/// \note if the kind was returned by memkind_create_kind() all allocated memory must be freed

///       before kind is destroyed, otherwise this will cause memory leak.

/// \param kind specified memory kind

/// \return Memkind operation status, MEMKIND_SUCCESS on success, MEMKIND_ERROR_OPERATION_FAILED on failure

///

int memkind_destroy_kind(memkind_t kind);

///

/// \brief Get kind associated with allocated memory referenced by ptr

/// \note STANDARD API

/// \note This function has non-trivial performance overhead

/// \param ptr pointer to the allocated memory

/// \return Kind associated with allocated memory, NULL on failure

///

memkind_t memkind_detect_kind(void *ptr);

#include "memkind_deprecated.h"

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_REGULAR;

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_DEFAULT;

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_HUGETLB;

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_HBW;

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_HBW_ALL;

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_HBW_PREFERRED;

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_HBW_HUGETLB;

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_HBW_ALL_HUGETLB;

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_HBW_PREFERRED_HUGETLB;

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_HBW_INTERLEAVE;

/// \warning EXPERIMENTAL API

extern memkind_t MEMKIND_INTERLEAVE;

/// \note STANDARD API

extern memkind_t MEMKIND_DAX_KMEM;

/// \note STANDARD API

extern memkind_t MEMKIND_DAX_KMEM_ALL;

/// \note STANDARD API

extern memkind_t MEMKIND_DAX_KMEM_PREFERRED;

///

/// \brief Get Memkind API version

/// \note STANDARD API

/// \return Version number represented by a single integer number(major * 1000000 + minor * 1000 + patch)

///

int memkind_get_version();

///

/// \brief Convert error number into an error message

/// \note STANDARD API

/// \param err error number

/// \param msg error message

/// \param size size of message

///

void memkind_error_message(int err, char *msg, size_t size);

///

/// \brief Create a new PMEM (file-backed) kind of given size on top of a temporary file

///        in the given directory dir

/// \note STANDARD API

/// \param dir path to specified directory to temporary file

/// \param max_size size limit for kind

/// \param kind pointer to kind which will be created

/// \return Memkind operation status, MEMKIND_SUCCESS on success, other values on failure

///

int memkind_create_pmem(const char *dir, size_t max_size, memkind_t *kind);

///

/// \brief Create a new PMEM kind with given memkind configuration

/// \note STANDARD API

/// \param cfg memkind configuration for specifying PMEM parameters

/// \param kind pointer to kind which will be created

/// \return Memkind operation status, MEMKIND_SUCCESS on success, other values on failure

///

int memkind_create_pmem_with_config(struct memkind_config *cfg,

                                    memkind_t *kind);

///

/// \brief Check if kind is available

/// \note STANDARD API

/// \param kind specified memory kind

/// \return Memkind operation status, MEMKIND_SUCCESS on success, other values on failure

///

int memkind_check_available(memkind_t kind);

///

/// \brief Update memkind cached statistics

/// \note STANDARD API

/// \return Memkind operation status, MEMKIND_SUCCESS on success, other values on failure

///

int memkind_update_cached_stats(void);

///

/// \brief Get memkind statistic

/// \note STANDARD API

/// \param kind specified memory kind

/// \param stat specified type of memory statistic

/// \param value reference to value of memory statistic

/// \return Memkind operation status, MEMKIND_SUCCESS on success, other values on failure

///

int memkind_get_stat(memkind_t kind, memkind_stat_type stat, size_t *value);

/* HEAP MANAGEMENT INTERFACE */

///

/// \brief Allocates size bytes of uninitialized storage of the specified kind

/// \note STANDARD API

/// \param kind specified memory kind

/// \param size number of bytes to allocate

/// \return Pointer to the allocated memory

///

void *memkind_malloc(memkind_t kind, size_t size);

///

/// \brief Obtain size of block of memory allocated with the memkind API

/// \note STANDARD API

/// \param kind specified memory kind

/// \param ptr pointer to the allocated memory

/// \return Number of usable bytes

///

size_t memkind_malloc_usable_size(memkind_t kind, void *ptr);

///

/// \brief Allocates memory of the specified kind for an array of num elements

///        of size bytes each and initializes all bytes in the allocated storage to zero

/// \note STANDARD API

/// \param kind specified memory kind

/// \param num number of objects

/// \param size specified size of each element

/// \return Pointer to the allocated memory

///

void *memkind_calloc(memkind_t kind, size_t num, size_t size);

///

/// \brief Allocates size bytes of the specified kind and places the address of the allocated memory

///        in *memptr. The address of the allocated memory will be a multiple of alignment,

///        which must be a power of two and a multiple of sizeof(void *)

/// \note EXPERIMENTAL API

/// \param kind specified memory kind

/// \param memptr address of the allocated memory

/// \param alignment specified alignment of bytes

/// \param size specified size of bytes

/// \return Memkind operation status, MEMKIND_SUCCESS on success, EINVAL or ENOMEM on failure

///

int memkind_posix_memalign(memkind_t kind, void **memptr, size_t alignment,

                           size_t size);

///

/// \brief Reallocates memory of the specified kind

/// \note STANDARD API

/// \param kind specified memory kind

/// \param ptr pointer to the memory block to be reallocated

/// \param size new size for the memory block in bytes

/// \return Pointer to the allocated memory

///

void *memkind_realloc(memkind_t kind, void *ptr, size_t size);

///

/// \brief Free the memory space of the specified kind pointed by ptr

/// \note STANDARD API

/// \param kind specified memory kind

/// \param ptr pointer to the allocated memory

///

void memkind_free(memkind_t kind, void *ptr);

///

/// \brief Try to reallocate allocation to reduce fragmentation

/// \note STANDARD API

/// \param kind specified memory kind

/// \param ptr pointer to the allocated memory

/// \return Pointer to newly transferred allocated memory

///

void *memkind_defrag_reallocate(memkind_t kind, void *ptr);

#ifdef __cplusplus

}

#endif