Function: mem_export_to_shareable_handle

Applicability

Product	Supported
Atlas 350 Accelerator Card	√
Atlas A3 training product/Atlas A3 inference product	√
Atlas A2 training product/Atlas A2 inference product	√
Atlas training product	√
Atlas inference product	√
Atlas 200I/500 A2 inference product	√

Description

Export the physical device memory handle obtained by the current process through the acl.rt.malloc_physical API so that the physical device 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 release the physical memory in a timely manner to destroy the 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 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 do not call this API to obtain the process ID, 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)

Parameters

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 options can be either of the following macros: ACL_RT_VMM_EXPORT_FLAG_DEFAULT: Default value. It means enabling the process trustlist verification. If this macro is used, call the acl.rt.mem_set_pid_to_shareable_handle 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 options can be either of the following macros:

ACL_RT_VMM_EXPORT_FLAG_DEFAULT: Default value. It means enabling the process trustlist verification.
If this macro is used, call the acl.rt.mem_set_pid_to_shareable_handle 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

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

Restrictions

The Atlas 200I/500 A2 inference product in Ascend RC form does not support this API.

The following models support cross-process sharing of physical memory in the AI Server. If cross-device sharing is required, the acl.rt.device_enable_peer_access API needs to be used. AI server is an umbrella term for servers consisting of multiple NPUs.
Atlas 350 Accelerator Card

Atlas A3 training product/Atlas A3 inference product

Atlas A2 training product/Atlas A2 inference product

Atlas training product

Atlas inference product
The Ascend virtual instance scenario is not supported.

Parent topic: Memory Management