aclrtMemExportToShareableHandle

Applicable Products

Product	Supported
Ascend 950PR	√
Ascend 950DT	☓
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	√

Function

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

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

In process A:
1. Call aclrtMallocPhysical to allocate physical memory.
  Call aclrtMemGetAllocationGranularity to obtain the memory allocation granularity, and then call aclrtMallocPhysical to allocate physical memory. The size is aligned with the obtained 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, establish a mapping between virtual memory and physical memory, and configure virtual memory access.
2. Call aclrtMemExportToShareableHandle to export the physical memory handle, returning a 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 no longer used, call the aclrtFreePhysical API to free it, thereby destroying the shareableHandle. If any process is still using the shareableHandle, wait until the shareableHandle usage is complete before executing the destruction task.
  
  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. Any subsequent use of 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 obtain the process ID without calling this API, 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, aclrtMapMem, and aclrtMemSetAccess APIs to allocate virtual memory, establish a mapping between virtual memory and physical memory, and configure virtual memory access. 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. For details about the type definition, see aclrtDrvMemHandle. You need to call aclrtMallocPhysical in this process to allocate physical memory. If this API is successfully called, a handle is returned. Each handle must correspond to only one shareableHandle. 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 at ACL_MEM_HANDLE_TYPE_NONE. For details about the type definition, see aclrtMemHandleType.
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 the 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 a shareableHandle to the trustlist. ACL_RT_VMM_EXPORT_FLAG_DISABLE_PID_VALIDATION: It means disabling the 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; otherwise, failure. For details, see aclError.

Restrictions

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

Physical memory sharing across processes in an AI server is supported. For cross-device scenarios, this API must be used together with the aclrtDeviceEnablePeerAccess API. An AI server is an umbrella term for a server consisting of multiple devices.
This API does not support the Ascend virtual instance scenario.
This API does not support the computing power allocation scenario. For details about computing power allocation APIs, see Group Management.

API Call Example

For the API call example, see Inter-Process Communication.

Parent topic: Virtual Memory Management