Register#

Fully qualified name: cupva::mem::Register

Defined in src/host/cpp_api/include/cupva_host.hpp

void cupva::mem::Register(
const void *const ptr,
int64_t const size,
cupva::mem::ExternalAllocType const externalAllocType,
)#

Register an external pointer to CUPVA space.

Registering a CUDA or HOST device pointer maps the pointer in CUPVA space which must be unregistered by calling Unregister() when the application has finished using the buffer.

User should never register an address range overlapping an address range which has already been registered explicitly. Doing so is undefined behavior.

User should call Unregister() for each explicitly registered address range before calling free (e.g. cudaMemFree or OS free()) on the underlying buffer. It is undefined what happens if user does not follow this.

When using driver versions >=2006, except for QNX Safety :

  • CUDA device pointers will automatically be registered/unregistered with CUPVA if CUDA interop is enabled.

  • Calling Register/Unregister on CUDA device pointers is not necessary. These APIs will have no effect in this case and will not generate an error in order to preserve compatibility of user code.

HOST register is not currently supported.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

  • ptr – [in] The pointer to import, allocated according to externalAllocType.

  • size – [in] The size of the allocation in bytes.

  • externalAllocType – [in] Type of memory being registered.

Throws:

  • cupva::Exception(InvalidArgument) – CUDA device pointer is nullptr.

  • cupva::Exception(DriverAPIError) – Getting a device pointer failed due to driver API error. This error does not apply to CUDA device pointers with driver version >=2006, except for QNX Safety.

  • cupva::Exception(InvalidArgument) – The size is invalid.

  • cupva::Exception(NotAllowedInOperationalState) – if called when NVIDIA DRIVE OS VM state is “Operational”

  • cupva::Exception(CUDADisabled) – If called after disabling CUDA interop for this process

  • cupva::Exception(InvalidArgument) – If user attempts to register ptr memory region overlapping with an existing registered memory region. This error does not apply to CUDA device pointers with driver version >=2006, except for QNX Safety. In such cases, allocations made via CUDA will automatically be registered and unregistered with CUPVA - it is not necessary to call this API or Unregister explicitly before using the CUDA device pointer with CUPVA. In order to preserve compatibility, this API will return success even if the registered CUDA device pointer aliases with a CUDA device pointer region already registered, either via this API or automatically by the driver.

  • cupva::Exception(InternalError) – If storing CUDA pointer mapping failed.

  • cupva::Exception(UnsupportedFeature) – If memory being registered if of type HOST.

On this page