4. Memory Management APIs#
4.1. cuMemObjGetDescriptor#
Acquires an RDMA memory descriptor for user memory.
cuObjErr_t cuMemObjGetDescriptor(void* ptr, size_t size);
Parameters:
ptr: Start address of user memory.size: Size of memory to register. The maximum size is4 GiB - 64 KiB.
Returns:
CU_OBJ_SUCCESSon successful registration.CU_OBJ_FAILon failure.
CU_OBJ_FAIL is returned for ptr == nullptr, size == 0, sizes greater
than CUOBJ_MAX_MEMORY_REG_SIZE, unsupported memory types, unsupported memory
configuration, or registration failure.
Notes:
Memory sizes greater than
CUOBJ_MAX_MEMORY_REG_SIZEare not supported.System memory and CUDA device memory are supported.
CUDA managed memory cannot be registered with this API. Use CUDA managed memory only with unregistered
cuObjGet()orcuObjPut()operations.Memory must remain valid until
cuMemObjPutDescriptor()is called.
4.2. cuMemObjPutDescriptor#
Releases the RDMA memory descriptor for user memory.
cuObjErr_t cuMemObjPutDescriptor(void* ptr);
Parameters:
ptr: Start address of memory. This address must match thecuMemObjGetDescriptor()call.
Returns:
CU_OBJ_SUCCESS.
Notes:
Call this API after all I/O operations on this memory have completed.
ptrmust match the address used incuMemObjGetDescriptor().Passing
nullptrreturnsCU_OBJ_SUCCESS.Current behavior does not report deregistration failures through the return value.
4.3. Registered and Unregistered Memory#
Applications may call cuMemObjGetDescriptor() before cuObjGet() or
cuObjPut() to register system memory or CUDA device memory explicitly.
Explicit registration is required before calling cuMemObjGetRDMAToken().
When cuMemObjGetDescriptor() is not called, cuObjGet() and
cuObjPut() may be used with CUDA device memory and CUDA managed memory.
In this mode, the request size is limited by the configured GPU bounce-buffer
capacity.
For unregistered CUDA device memory, call
cuMemObjGetMaxRequestCallbackSize() before issuing the operation to get the
maximum callback size for the pointer.
System memory must be registered with cuMemObjGetDescriptor() before
cuObjGet() or cuObjPut(). Unregistered system memory is not supported.
CUDA managed memory cannot be registered with cuMemObjGetDescriptor(). Use
CUDA managed memory only with unregistered cuObjGet() or cuObjPut()
operations. Its request size is bounded by the configured GPU bounce-buffer
capacity. Because cuMemObjGetRDMAToken() requires registered memory, it is
not supported for CUDA managed memory.
If cuMemObjGetMaxRequestCallbackSize() returns -1, the pointer does not
have an advertised callback size. For system memory, register the memory
explicitly before cuObjGet() or cuObjPut().
4.4. cuMemObjGetMaxRequestCallbackSize#
Gets the maximum callback size for a memory pointer.
ssize_t cuMemObjGetMaxRequestCallbackSize(void* ptr);
Parameters:
ptr: Start address of user memory.
Returns:
Maximum callback size in bytes for this memory pointer.
-1if the callback size cannot be determined for this pointer.-1forptr == nullptr.
Notes:
The callback may be invoked multiple times if the requested I/O size exceeds this limit.
The returned value is the chunk size that is used in each callback invocation.
The returned size may be smaller than the allocated memory size.
For unregistered CUDA device memory, this API returns the configured GPU bounce-buffer capacity.
For unregistered CUDA managed memory, current behavior returns
-1.Positive values greater than
CUOBJ_MAX_MEMORY_REG_SIZEare capped atCUOBJ_MAX_MEMORY_REG_SIZE.
4.5. cuMemObjGetRDMAToken#
Generates an RDMA descriptor string for a registered memory buffer.
cuObjErr_t cuMemObjGetRDMAToken(void* ptr, size_t size, size_t buffer_offset,
cuObjOpType_t operation, char** desc_str_out);
Parameters:
ptr: Start address of registered memory. The memory must have been registered previously.size: Size of the memory region for the descriptor.buffer_offset: Offset from the base address to start the descriptor region.operation: Operation type. UseCUOBJ_GETorCUOBJ_PUT.desc_str_out: Output pointer that stores the allocated descriptor string.
Returns:
CU_OBJ_SUCCESSon success.CU_OBJ_FAILon failure.
CU_OBJ_FAIL is returned when operation is not CUOBJ_GET or
CUOBJ_PUT, or when the descriptor string cannot be generated.
Notes:
Memory must be registered with
cuMemObjGetDescriptor()before calling this function.The descriptor string is allocated on success.
The caller must release the descriptor string using
cuMemObjPutRDMAToken().operationmust beCUOBJ_GETorCUOBJ_PUT.buffer_offset + sizemust not exceed the originally registered buffer size.The buffer must be RDMA capable for this function to succeed.
desc_str_outmust be non-null.Applications should pass the descriptor string as returned.
4.6. cuMemObjPutRDMAToken#
Frees an RDMA descriptor string allocated by cuMemObjGetRDMAToken().
cuObjErr_t cuMemObjPutRDMAToken(char* desc_str);
Parameters:
desc_str: Descriptor string to free. It must have been allocated bycuMemObjGetRDMAToken().
Returns:
CU_OBJ_SUCCESSon success.CU_OBJ_FAILon failure.
CU_OBJ_FAIL is returned if the descriptor string cannot be released.
Notes:
Call this API to free memory allocated by
cuMemObjGetRDMAToken().