aclrtIpcMemGetExportKey

Applicability

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.

1. In process A:
   1. Call aclrtMalloc to allocate memory.
   2. Call aclrtIpcMemGetExportKey to export the shared memory key.

      Call aclrtIpcMemGetExportKey to specify whether to enable process trustlist verification. If the verification is enabled, call aclrtIpcMemSetImportPid separately to add the ID of process B to the trustlist. If the verification is disabled, there is no need to call aclrtIpcMemSetImportPid.

   3. Call aclrtIpcMemClose to disable IPC-based memory sharing.

      Only after process B calls aclrtIpcMemClose to disable IPC-based memory sharing can process A disable IPC-based memory sharing. Otherwise, exceptions may occur.

   4. Call aclrtFree to free the memory.
2. In process B:
   1. Call aclrtDeviceGetBareTgid 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 obtain the process ID without calling this API, an exception may occur when you use the process ID.

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

      Before calling aclrtIpcMemImportByKey, ensure that the memory to be shared exists and cannot be freed in advance.

   3. Call aclrtIpcMemClose to disable IPC-based memory sharing.

Prototype

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

Parameters

#define ACL_RT_IPC_MEM_EXPORT_FLAG_DEFAULT                0x0UL
#define ACL_RT_IPC_MEM_EXPORT_FLAG_DISABLE_PID_VALIDATION 0x1UL

Returns

0 on success; else, failure. For details, see aclError.

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:

• 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.

The preceding restrictions do not apply when two processes on the same device share memory through IPC.