Function: ipc_mem_get_export_key
Applicability
Product |
Supported |
|---|---|
Atlas 350 Accelerator Card |
√ |
√ |
|
√ |
|
√ |
|
√ |
|
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 two processes on different devices share memory, call the acl.rt.device_enable_peer_access API to enable P2P.
b. Call the acl.rt.malloc API to apply for the P2P memory (configured by the policy parameter of this 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 the acl.rt.ipc_mem_set_import_pid API to add the ID of process B to the whitelist.
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 two processes on different devices share memory, call the acl.rt.device_enable_peer_access API to enable P2P.
b. Call acl.rt.device_get_bare_tgid 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 memory. If you do not call this API to obtain the process ID, 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)
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 options 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
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:
- This API must be used together with the acl.rt.device_enable_peer_access API to enable communication between two devices.
- On the
Atlas inference product , when the aclrtMalloc API is called to allocate device memory, policy must be set to a 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.
The preceding restrictions do not apply when two processes on the same device share memory through IPC.