RegisterMem
Applicable Products
|
Product |
Supported (√/x) |
|---|---|
|
|
√ |
|
|
√ |
|
|
√ |
|
|
x |
|
|
x |
|
|
x |
Note: For
Function Description
Registers a memory address for use by TransferSync in subsequent calls. The local and remote memory addresses specified in TransferSync can be a subset of the registered addresses. Local memory addresses must be registered with the local HIXL instance, and remote memory addresses must be registered with the remote HIXL instance.
Prototype
1
|
Status RegisterMem(const MemDesc &mem, MemType type, MemHandle &mem_handle) |
Parameters
|
Parameter |
Input/Output |
Description |
|---|---|---|
|
mem |
Input |
Description of the memory to be registered. The type is MemDesc. |
|
type |
Input |
Type of the memory to be registered. The type is MemType. |
|
mem_handle |
Output |
Memory handle returned after successful registration, which can be used for memory deregistration. The type is MemHandle. |
Example
Click GitCode, select the matching version, and obtain the sample from the examples/cpp directory.
Returns
- SUCCESS: Success.
- PARAM_INVALID: Incorrect parameter.
- Other values: Failure.
Exception Handling
None
Constraints
- Before calling Connect to establish a link with the peer end, register all local memories.
- A maximum of 4,000 memory objects can be registered for a single HIXL instance. Registering too many memory objects may cause device OOM risks. In addition, it takes a longer time to establish a link if too many memory objects are registered, causing link establishment timeout. Therefore, you need to control the number and size of registered memory objects based on your service scenario.
- If the HDK version is earlier than 25.5.0, a maximum of 20 GB host memory can be registered. If the HDK version is 25.5.0 or later, a maximum of 1 TB host memory can be registered. Larger registered memory results in higher OS memory usage. This restriction applies to the following products:
Atlas A2 training products /Atlas A2 inference products Atlas A3 training products /Atlas A3 inference products
- To register the host memory, call aclrtMallocHost. The memory address allocated by this API is automatically aligned. This restriction applies to the following products:
Atlas A2 training products /Atlas A2 inference products Atlas A3 training products /Atlas A3 inference products
- To register the device memory, call aclrtMalloc. If HCCS is used for transmission, set the memory allocation rule to ACL_MEM_MALLOC_HUGE_ONLY.
- This API and Initialize must run in the same thread. If you need to switch threads to call this API, first call aclrtGetCurrentContext in the thread where Initialize is running to obtain the context. Then, in the new thread, call aclrtSetCurrentContext to set the context.
- In the
Ascend 950PR /Ascend 950DT scenario, if you use the host RoCE NIC, the memory allocated by aclrtMallocHost cannot be registered. Use the malloc method instead.