Function: mem_export_to_shareable_handle

Applicability

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

Function Usage

Export the handle of the physical memory obtained by the current process through the acl.rt.malloc_physical API so that the physical memory can be shared with other processes.

This API must be used together with the following 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 acl.rt.malloc_physical to allocate physical memory.
  Call acl.rt.mem_get_allocation_granularity to obtain the memory granularity, and then call acl.rt.malloc_physical 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 addresses, you can call the acl.rt.reserve_mem_address and acl.rt.map_mem APIs to allocate virtual memory and establish the mapping between the virtual memory and physical memory. For details, see the description of the corresponding APIs.
2. Call acl.rt.mem_export_to_shareable_handle to export the handle of the physical memory and output shareable_handle.
  Call acl.rt.mem_export_to_shareable_handle to specify whether to enable process trustlist verification. If the verification is enabled, call acl.rt.mem_set_pid_to_shareable_handle separately to add the ID of process B to the trustlist. If the verification is disabled, there is no need to call acl.rt.mem_set_pid_to_shareable_handle.
3. Call acl.rt.free_physical to free the physical memory.
  After the memory is used, call the acl.rt.free_physical API to free the physical memory and destroy the shareable handle. If a process is still using the shareable handle, execute the destroy task after the shareable handle 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 acl.rt.device_get_bare_tgid to obtain the ID of process B.
  This API has been adapted to the physical machine and VM scenarios when obtaining the process ID. You only need to call it to obtain the process ID and then configure other APIs to share the physical memory. If you obtain the process ID without calling this API, an exception may occur when you use the process ID.
2. Call acl.rt.mem_import_from_shareable_handle to obtain the information in shareable_handle and return the handle of the process. (Before calling acl.rt.mem_import_from_shareable_handle, ensure that the physical memory to be shared exists and cannot be released in advance.)
  To allocate virtual memory with consecutive addresses and maximize the use of physical memory addresses, you can call the acl.rt.reserve_mem_address and acl.rt.map_mem APIs to allocate virtual memory and establish the mapping between the virtual memory and physical memory. For details, see the description of the corresponding APIs.
3. Call acl.rt.free_physical to free the physical memory.

Prototype

C Prototype

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

Python Function

shareable_handle, ret = acl.rt.mem_export_to_shareable_handle(handle, handle_type, flags)

Parameter Description

Parameter	Description
handle	Int, handle for storing physical memory information. You need to call acl.rt.malloc_physical 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 shareable handles. 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.
handle_type	Int, reserved parameter. The value is fixed at 0 (ACL_MEM_HANDLE_TYPE_NONE).
flags	Int, whether to enable process trustlist verification. The value can be either of the following macros: ACL_RT_VMM_EXPORT_FLAG_DEFAULT: default, indicating that process trustlist verification is enabled. If this macro is used, call the aclrtMemSetPidToShareableHandle API separately to add the ID of the process that uses the shareable handle to the trustlist. ACL_RT_IPC_MEM_EXPORT_FLAG_DISABLE_PID_VALIDATION: disables process trustlist verification. If this macro is used, you do not need to call the acl.rt.mem_set_pid_to_shareable_handle 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

Parameter

Description

handle

Int, handle for storing physical memory information.

You need to call acl.rt.malloc_physical 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 shareable handles. 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.

handle_type

Int, reserved parameter. The value is fixed at 0 (ACL_MEM_HANDLE_TYPE_NONE).

flags

Int, whether to enable process trustlist verification.

The value can be either of the following macros:

ACL_RT_VMM_EXPORT_FLAG_DEFAULT: default, indicating that process trustlist verification is enabled.
If this macro is used, call the aclrtMemSetPidToShareableHandle API separately to add the ID of the process that uses the shareable handle to the trustlist.
ACL_RT_IPC_MEM_EXPORT_FLAG_DISABLE_PID_VALIDATION: disables process trustlist verification.
If this macro is used, you do not need to call the acl.rt.mem_set_pid_to_shareable_handle 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

Return Value Description

Return Value	Description
shareable_handle	Int, shareable handle shared with other processes.
ret	Int, error code: 0 on success; else, failure.

Restrictions

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

The following product models support inter-process physical memory sharing within an AI server. If inter-device sharing is required, call the acl.rt.device_enable_peer_access 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.

Parent topic: Memory Management