mstx Extension Functions

Introduction to mstx APIs

mstx APIs are a set of extension APIs provided by MindStudio to allow you to insert specific tags in your application so that the memory issues of operators can be more accurately identified. For example, for level-2 pointer operators, the address space obtained without the mstx API call may be inaccurate. The accurate address space can be transferred to the anomaly check tool through the and APIs in MindStudio mstx API Reference to implement more accurate memory check.

The kernel launch symbol scenario in Kernel launch does not support the mstx APIs.

mstx API list

Table 1 describes the mstx APIs invoked by the msSanitizer. For details, see MindStudio mstx API Reference.

**Table 1** List of mstx interfaces invoked by msSanitizer
Name	Function Description
mstxDomainCreateA	Creates an mstx domain.
mstxMemHeapRegister	Registers a memory pool. Before calling this API to register a memory pool, you must ensure that the memory has been allocated in advance.
mstxMemRegionsRegister	Registers secondary allocation of a memory pool. Ensure that the memory of RegionsRegister is within the range registered by mstxMemHeapRegister. Otherwise, the tool displays a message indicating that out-of-bounds read/write occurs.
mstxMemRegionsUnregister	Deregisters secondary allocation of a memory pool.
mstxMemHeapUnregister	Deregisters the regions associated with a memory pool when the memory pool is deregistered.

Usage

By default, the msSanitizer tool enables the mstx APIs, allowing you to customize the memory space address and size for operators to identify operator memory issues quickly.
mstx provides two API usage modes: library file and header file. An example is shown in link.
- This example project does not support Atlas A3 Training Series Product.
- Add library file libms_tools_ext.so to the ${git_clone_path}/samples/operator/ascendc/0_introduction/1_add_frameworklaunch/AclNNInvocation/src/CMakeLists.txt directory. The address is ${INSTALL_DIR}/lib64/libms_tools_ext.so.
```
# Header path
include_directories(
     ...
    ${CUST_PKG_PATH}/include
)
...
target_link_libraries( 
    ...
    dl
)
```
- In the ${git_clone_path}/samples/operator/ascendc/0_introduction/1_add_frameworklaunch/AclNNInvocation/src/main.cpp directory, compile and link the user program to the dl library. The corresponding header file ms_tools_ext.h is stored in ${INSTALL_DIR}/include/mstx.
```
...
#include "mstx/ms_tools_ext.h"
...
```
  Replace ${INSTALL_DIR} with the CANN component directory. For example, if the installation is performed by the root user, the default file storage path is /usr/local/Ascend/cann.

Example

mstxMemVirtualRangeDesc_t rangeDesc = {};
    rangeDesc.deviceId = deviceId;       // Device ID
    rangeDesc.ptr = gm;                  // Start address of the registered memory pool CM
    rangeDesc.size = 1024;               // Memory pool size
    heapDesc.typeSpecificDesc = &rangeDesc;
    mstxMemHeapDesc_t heapDesc{};
    mstxMemHeapHandle_t memPool = mstxMemHeapRegister(globalDomain, &heapDesc); // Register the memory pool.
    mstxMemVirtualRangeDesc_t rangesDesc[1] = {};                // Number of regions contained in the secondary allocation.
    mstxMemRegionHandle_t regionHandles[1] = {};
    rangesDesc[0].deviceId = deviceId;                           // Device ID
rangesDesc[0].ptr = gm; // Secondary GM address allocation
    rangesDesc[0].size = 256;                                    // Size of the secondary allocation
    mstxMemRegionsRegisterBatch_t regionsDesc{};
    regionsDesc.heap = memPool;
    regionsDesc.regionType = MSTX_MEM_TYPE_VIRTUAL_ADDRESS;
    regionsDesc.regionCount = 1;
    regionsDesc.regionDescArray = rangesDesc;
    regionsDesc.regionHandleArrayOut = regionHandles;
    mstxMemRegionsRegister(globalDomain, regionsDesc);              // Register secondary allocation.
    Do(blockDim, nullptr, stream, gm);                            // Operator kernel function
    mstxMemRegionRef_t regionRef[1] = {};
    regionRef[0].refType = MSTX_MEM_REGION_REF_TYPE_HANDLE;
    regionRef[0].handle = regionHandles[0];
    mstxMemRegionsUnregisterBatch_t refsDesc = {};
    refsDesc.refCount = 1;
    refsDesc.refArray = regionRef;
    mstxMemRegionsUnregister(globalDomain, &refsDesc);                   // Deregister the secondary allocation.
    mstxMemHeapUnregister(globalDomain, memPool);                        // Deregister the memory pool.

Parent topic: External API Usage Description