Function: ipc_mem_get_export_key
Applicability
Product |
Supported (√/x) |
|---|---|
√ |
|
√ |
|
√ |
|
√ |
|
x |
Function Usage
Sets the specified device memory as shared through IPC 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
1key, ret = acl.rt.ipc_mem_get_export_key(dev_ptr, size, len, flags)
Parameter Description
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:
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 Value Description
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 following figure, 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. - The direction of memory copy cannot be automatically determined based on the source and destination memory address pointers. Synchronous and asynchronous memory copies between host and device are not supported. Only asynchronous copies are permitted on the same device.
- Cross-chip access of Cube and Vector units is supported.
The preceding restrictions do not apply when two processes on the same device share memory through IPC.