aclrtMemExportToShareableHandle

Applicability

Product	Supported
Atlas A3 training products/Atlas A3 inference products	√
Atlas A2 training products/Atlas A2 inference products	√
Atlas 200I/500 A2 inference products	√
Atlas inference products	√
Atlas training products	√

Description

Export the physical device memory handle obtained by the current process through the aclrtMallocPhysical API so that the physical device memory can be shared with other processes.

This API must be used together with the following key APIs to implement memory sharing. The following uses processes A and B as an example to describe the process of calling the physical memory sharing API between two processes.

In process A:
1. Call aclrtMallocPhysical to allocate physical memory.
  Call aclrtMemGetAllocationGranularity to obtain the memory granularity, and then call aclrtMallocPhysical to allocate the physical memory. The size is aligned based on the obtained memory granularity to save memory.
  
  To allocate virtual memory with consecutive addresses and maximize the use of physical memory, you can call the aclrtReserveMemAddress, aclrtMapMem, and aclrtMemSetAccess APIs to allocate virtual memory and establish the mapping between the virtual memory and physical memory and configure virtual memory access.
2. Call aclrtMemExportToShareableHandle to export the physical memory handle and output shareableHandle.
  Call aclrtMemExportToShareableHandle to specify whether to enable process trustlist verification. If the verification is enabled, call aclrtMemSetPidToShareableHandle separately to add the ID of process B to the trustlist. If the verification is disabled, there is no need to call aclrtMemSetPidToShareableHandle.
3. Call aclrtFreePhysical to free the physical memory.
  After the memory is used, call the aclrtFreePhysical API to release the physical memory and destroy shareableHandle. If a process is still using shareableHandle, execute the destroy task after shareableHandle is used.
  
  All processes involving shared memory must free their physical memory. The physical memory is completely freed only after all processes have freed it. After the physical memory is freed, the allocated memory is returned to the OS. Using the handle will cause undefined behavior.
In process B:
1. Call aclrtDeviceGetBareTgid to obtain the ID of process B.
  This API adapts to both physical machines and VMs when obtaining the process ID. You only need to call this API to obtain the process ID and use the API with other APIs to share physical memory. If you do not call this API to obtain the process ID, an exception may occur when you use the process ID.
2. Call aclrtMemImportFromShareableHandle to obtain the information in shareableHandle and return the handle to the process.
  Before calling aclrtMemImportFromShareableHandle, ensure that the physical memory to be shared exists and cannot be freed in advance.
  
  To allocate virtual memory with consecutive addresses and maximize the use of physical memory addresses, you can call the aclrtReserveMemAddress, aclrtMemSetAccess, and aclrtMapMem APIs to allocate virtual memory, configure virtual memory access, and map virtual memory and physical memory. For details, see the description of the corresponding APIs.
3. Call aclrtFreePhysical to free the physical memory.

Prototype

aclError aclrtMemExportToShareableHandle(aclrtDrvMemHandle handle, aclrtMemHandleType handleType, uint64_t flags, uint64_t *shareableHandle)

Parameters

Parameter	Input/Output	Description
handle	Input	Handle for storing physical memory information. You need to call aclrtMallocPhysical in this process to allocate physical memory. If this API is successfully called, a handle is returned. There is a one-to-one mapping between handles and shareableHandles. In the same process, one-to-many or many-to-one mapping is not allowed. Otherwise, an error is reported. For example, if this API is repeatedly called to export data, an error is reported.
handleType	Input	Reserved. The value is fixed to ACL_MEM_HANDLE_TYPE_NONE.
flags	Input	Whether to enable process trustlist verification. The value can be either of the following macros: ACL_RT_VMM_EXPORT_FLAG_DEFAULT: Default value. It means enabling process trustlist verification. If you set the parameter to this value, call the aclrtMemSetPidToShareableHandle API separately to add the ID of the process that uses shareableHandle to the trustlist. ACL_RT_VMM_EXPORT_FLAG_DISABLE_PID_VALIDATION: Disables process trustlist verification. If you set the parameter to this value, you do not need to call the aclrtMemSetPidToShareableHandle API. The macros are defined as follows: #define ACL_RT_VMM_EXPORT_FLAG_DEFAULT 0x0UL #define ACL_RT_VMM_EXPORT_FLAG_DISABLE_PID_VALIDATION 0x1UL
shareableHandle	Output	shareableHandle shared with other processes.

Returns

0 on success; else, failure. For details, see aclError.

Restrictions

This API is not supported in the Ascend RC form of the Atlas 200I/500 A2 inference products.

The following product models support inter-process physical memory sharing within an AI server. If inter-device sharing is required, call the aclrtDeviceEnablePeerAccess API. AI server is an umbrella term for servers consisting of multiple NPUs.
Atlas A3 training products/Atlas A3 inference products

Atlas A2 training products/Atlas A2 inference products

Atlas training products

Atlas inference products
This API does not support the Ascend virtual instance scenario.
This API is not supported for compute capability allocation.
For details about computing power allocation APIs, see Group Management.

Parent topic: Memory Management