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 is 4 GiB - 64 KiB.

Returns:

  • CU_OBJ_SUCCESS on successful registration.

  • CU_OBJ_FAIL on 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_SIZE are 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() or cuObjPut() 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 the cuMemObjGetDescriptor() call.

Returns:

  • CU_OBJ_SUCCESS.

Notes:

  • Call this API after all I/O operations on this memory have completed.

  • ptr must match the address used in cuMemObjGetDescriptor().

  • Passing nullptr returns CU_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.

  • -1 if the callback size cannot be determined for this pointer.

  • -1 for ptr == 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_SIZE are capped at CUOBJ_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. Use CUOBJ_GET or CUOBJ_PUT.

  • desc_str_out: Output pointer that stores the allocated descriptor string.

Returns:

  • CU_OBJ_SUCCESS on success.

  • CU_OBJ_FAIL on 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().

  • operation must be CUOBJ_GET or CUOBJ_PUT.

  • buffer_offset + size must not exceed the originally registered buffer size.

  • The buffer must be RDMA capable for this function to succeed.

  • desc_str_out must 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 by cuMemObjGetRDMAToken().

Returns:

  • CU_OBJ_SUCCESS on success.

  • CU_OBJ_FAIL on failure.

CU_OBJ_FAIL is returned if the descriptor string cannot be released.

Notes:

  • Call this API to free memory allocated by cuMemObjGetRDMAToken().