mstxMemHeapRegister

Function Description

Registers a memory pool. Before calling this API to register a memory pool, ensure that the memory has been allocated in advance.

Function Prototype

mstxMemHeapHandle_t mstxMemHeapRegister(mstxDomainHandle_t domain, mstxMemHeapDesc_t const *desc)

Parameters

**Table 1** Parameters
Parameter	Input/Output	Description
domain	Input	globalDomain or the handle returned by mstxDomainCreateA. Data type: const char *
desc	Input	typedef enum mstxMemHeapUsageType { /* @brief: The heap memory is used as a memory pool. * The heap memory registered in this mode can be accessed only after secondary allocation registration. / MSTX_MEM_HEAP_USAGE_TYPE_SUB_ALLOCATOR = 0, } mstxMemHeapUsageType; /* @brief: heap memory type * The type indicates the method used to describe the heap memory pointer. Currently, only linear memory is supported. * The capability of supporting more memory types is reserved. For example, some APIs return * multiple handles to describe the memory scope, or some high-dimensional memory requires description using stride, tiling, or * interface. / typedef enum mstxMemType { /* @brief: virtual memory of the standard linear layout * mstxMemHeapRegister receives the description of the mstxMemVirtualRangeDesc_t type. / MSTX_MEM_TYPE_VIRTUAL_ADDRESS = 0, } mstxMemType; typedef struct mstxMemVirtualRangeDesc_t { uint32_t deviceId; // ID of the device corresponding to the memory area void const ptr; // Start address of the memory area uint64_t size; // Memory area size } mstxMemVirtualRangeDesc_t; typedef struct mstxMemHeapDesc_t { mstxMemHeapUsageType usage; // Heap memory usage mstxMemType type; // Heap memory type void const *typeSpecificDesc; // Description of the heap memory of the specific type } mstxMemHeapDesc_t;

Table 1 Parameters

Parameter

Input/Output

Description

domain

Input

globalDomain or the handle returned by mstxDomainCreateA.

Data type: const char *

desc

Input

typedef enum mstxMemHeapUsageType {
    /* @brief: The heap memory is used as a memory pool.
     * The heap memory registered in this mode can be accessed only after secondary allocation registration.
     */
    MSTX_MEM_HEAP_USAGE_TYPE_SUB_ALLOCATOR = 0,
} mstxMemHeapUsageType;

/** @brief: heap memory type
 * The type indicates the method used to describe the heap memory pointer. Currently, only linear memory is supported.
 * The capability of supporting more memory types is reserved. For example, some APIs return
 * multiple handles to describe the memory scope, or some high-dimensional memory requires description using stride, tiling, or
* interface.
 */
typedef enum mstxMemType {
    /** @brief: virtual memory of the standard linear layout
      * mstxMemHeapRegister receives the description of the mstxMemVirtualRangeDesc_t type.
      */
    MSTX_MEM_TYPE_VIRTUAL_ADDRESS = 0,
} mstxMemType;

typedef struct mstxMemVirtualRangeDesc_t {
    uint32_t deviceId;  // ID of the device corresponding to the memory area
    void const *ptr;  // Start address of the memory area
    uint64_t size;  // Memory area size
} mstxMemVirtualRangeDesc_t;

typedef struct mstxMemHeapDesc_t {
    mstxMemHeapUsageType usage;  // Heap memory usage
    mstxMemType type;  // Heap memory type
    void const *typeSpecificDesc;  // Description of the heap memory of the specific type
} mstxMemHeapDesc_t;

Returns

Handle to the memory pool.

Calling Example

mstxMemVirtualRangeDesc_t rangeDesc = {};
    rangeDesc.deviceId = deviceId;       // Device ID
    rangeDesc.ptr = gm;                  // Start address of the registered memory pool GM
    rangeDesc.size = 1024;               // Memory pool size
    heapDesc.typeSpecificDesc = &rangeDesc;
    mstxMemHeapDesc_t heapDesc{};
    mstxMemHeapHandle_t memPool = mstxMemHeapRegister(globalDomain, &heapDesc); // Register the memory pool.