Function: mem_export_to_shareable_handle

aclError aclrtMemExportToShareableHandle(aclrtDrvMemHandle handle, aclrtMemHandleType handleType, uint64_t flags, uint64_t *shareableHandle)

shareable_handle, ret = acl.rt.mem_export_to_shareable_handle(handle, handle_type, flags)

Export the handle of the physical memory obtained by the current process through the acl.rt.malloc_physical API so that the physical 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.

1. 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.
   3. Obtain the ID of process B and call acl.rt.mem_set_pid_to_shareable_handle to add the ID of process B to the whitelist.
   4. Call acl.rt.free_physical to free the physical memory.

      All processes involving shared memory need to free the physical memory. The physical memory is released only after all processes involving memory sharing complete the release operation. After the physical memory is released, the referenced allocated memory is released back to the operating system. If the handle is used later, undefined behavior occurs.

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

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.

handle_type: int, reserved parameter. The value is fixed to ACL_MEM_HANDLE_TYPE_NONE = 0.

flags: int, reserved parameter. The value is fixed to 0.

shareable_handle: int, shareable_handle shared with other processes.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

• This API is not supported in Ascend RC form.
• Only the physical memory on the device side can be shared.
• Release the physical memory through the acl.rt.free_physical interface to destroy the shareable_handle. If a process is still using shareable_handle, execute the destruction task after shareable_handle is used.
• There is a one-to-one mapping between handles and shareable_handle. 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.
• Computing power allocation and grouping are not supported.