Applicable Products

Product	Supported (√/x)
Ascend 950PR/Ascend 950DT	√
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	x

Description

Sets the specified device memory to IPC shared memory in the current process and returns the shared memory key, so that the 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 memory sharing API between two processes.

In process A:
a. If the memory is shared between two processes on different devices, call acl.rt.device_enable_peer_access to enable P2P.

b. Call acl.rt.malloc to allocate P2P memory (configured by the policy parameter of the API).

c. Call acl.rt.ipc_mem_get_export_key to export the shared memory key.

d. Obtain the ID of process B and call acl.rt.ipc_mem_set_import_pid to add the ID of process B to the trustlist.

e. Call acl.rt.ipc_mem_close to disable IPC-based memory sharing. Only after process B calls acl.rt.ipc_mem_close to disable IPC-based memory sharing can process A do so. Otherwise, exceptions may occur.

f. Call acl.rt.free to free the memory.
In process B:
a. If the memory is shared between two processes on different devices, call acl.rt.device_enable_peer_access to enable P2P.

b. Call acl.rt.device_get_bare_tgid to obtain the ID of process B.

This API adapts to both PMs 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 memory. If you obtain the process ID without calling this API, an exception may occur when you use the process ID.

c. Call aclrtIpcMemImportByKey to obtain the key information and return the device memory address pointer that can be used by the current process.

Before calling acl.rt.ipc_mem_import_by_key, ensure that the memory to be shared exists and is not freed.

d. Call acl.rt.ipc_mem_close to disable IPC-based memory sharing.

Prototype

C Prototype

aclError aclrtIpcMemGetExportKey(void *devPtr, size_t size, char *key, size_t len, uint64_t flag)

Python Function

key, ret = acl.rt.ipc_mem_get_export_key(dev_ptr, size, len, flags)

Parameters

Parameter	Description
dev_ptr	Int, device memory address.
size	Int, memory size, in bytes.
len	Int, length of the key. The value is fixed at 65.
flags	Int, whether to enable process trustlist verification. The value can be either of the following macros: ACL_RT_IPC_MEM_EXPORT_FLAG_DEFAULT: Default value. It means enabling process trustlist verification. If you set the parameter to this value, call the acl.rt.ipc_mem_set_import_pid API separately to add the ID of the process that uses the shared memory key to the trustlist. ACL_RT_IPC_MEM_EXPORT_FLAG_DISABLE_PID_VALIDATION: Disables the process trustlist verification. If this macro is used, you do not need to call the acl.rt.ipc_mem_set_import_pid API. The macros are defined as follows: #define ACL_RT_IPC_MEM_EXPORT_FLAG_DEFAULT 0x0UL #define ACL_RT_IPC_MEM_EXPORT_FLAG_DISABLE_PID_VALIDATION 0x1UL

Return Values

Return Value	Description
key	Str, shared memory key.
ret	Int, 0 on success; else failure.

Restrictions

When two processes on different devices share memory through IPC, as shown in the figure below, process A on device 0 shares the memory with process B on device 1 through IPC. When the shared memory address is used in process B:

The acl.rt.device_enable_peer_access API must be call to enable communication between two devices.
On the Atlas inference products, when aclrtMalloc is called to allocate device memory, the policy must be set to the P2P type, for example, ACL_MEM_MALLOC_HUGE_FIRST_P2P.
During memory copy, the copy direction cannot be automatically determined based on the source and destination memory address pointers. Memory copy in the host -> device or device -> host direction is not supported, either synchronously or asynchronously. On the same device, asynchronous memory copy is supported, but synchronous memory copy is not.
Cross-chip access of Cube and Vector units is supported.