CmdMemcpy

Fully qualified name: cupva::CmdMemcpy

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

class CmdMemcpy : public cupva::BaseCmd

A convenience command to copy data from source memory area to destination memory area.

CmdMemcpy command copies source memory area to the destination memory area using the PVA DMA engines. CmdMemcpy can be submitted to a cupva::Stream similar to the cupva::CmdProgram. Memory areas in DRAM and L2SRAM are supported by CmdMemcpy. CmdMemcpy cannot be used to copy data from VMEM or to VMEM.

For the purposes of L2 persistence, if CmdMemcpy targets L2SRAM as a source or destination, it will behave the same as a CmdProgram with a non-zero L2 allocation. Otherwise, it will not be considered to have an L2 allocation. Refer cupva::CmdProgram::setL2Size for more details on L2 persistence.

Public Functions

CmdMemcpy() noexcept

Construct a default object of CmdMemcpy.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

CmdMemcpy(CmdMemcpy &&obj) noexcept

Move constructor.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: Yes

  • De-Init: No

CmdMemcpy &operator=(CmdMemcpy &&obj) & noexcept

Move assignment.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: Yes

  • De-Init: No

CmdMemcpy(CmdMemcpy const&) = delete

CmdMemcpy &operator=(CmdMemcpy const&) & = delete

~CmdMemcpy() noexcept

Destroy the CmdMemcpy object.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: No

  • De-Init: Yes

void finalize()

Destroy the resources created by a BaseCmd object.

This method is exposed to allow fine-grained control over error handling.

During destruction of the object, this method will be called but the destructor must not propagate exceptions. To handle exceptions, manually invoke this method prior to object destruction.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: No

  • De-Init: Yes

Throws:

• cupva::Exception(DriverAPIError) – if driver returns error during de-initialization of mapped/pinned memory

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

Public Static Functions

static CmdMemcpy Create(

const OffsetPointer<void> &dst,

const OffsetPointer<void const> &src,

size_t const count,

)

Construct a CmdMemcpy to copy 1D data using OffsetPointers.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• dst – Reference to the destination offset pointer.

• src – Reference to the source offset pointer.

• count – The number of bytes to be copied.

Throws:

• cupva::Exception(DriverAPIError) – if driver API layer returns an error due to:

  • Memory allocation failure

  • Pinning or mapping memory failure

  • Unable to detect chip information

• Refer – cupva::Context for possible exceptions if creation of default context is required.

• cupva::Exception(InvalidArgument) – if dst or src is not registered as a device pointer in DRAM, L2SRAM (Orin only)

• cupva::Exception(InvalidArgument) – if dst or src is a L2SRAM pointer and memory access outside the L2SRAM boundaries is requested.

• cupva::Exception(InvalidArgument) – if dst or src is a VMEM pointer.

• cupva::Exception(InvalidArgument) – if count exceeds maximum allowable limit.

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

Returns:

Allocated command object.

static CmdMemcpy Create(

void *const dst,

const void *const src,

size_t const count,

)

Construct a CmdMemcpy to copy 1D data using raw pointers.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• dst – Destination memory address.

• src – Source memory address.

• count – The number of bytes to be copied.

Throws:

• cupva::Exception(DriverAPIError) – if driver API layer returns an error due to:

  • Memory allocation failure

  • Pinning or mapping memory failure

  • Unable to detect chip information

• Refer – cupva::Context for possible exceptions if creation of default context is required.

• cupva::Exception(InvalidArgument) – if dst or src is not registered as a device pointer in DRAM, L2SRAM (Orin only)

• cupva::Exception(InvalidArgument) – if dst or src is a L2SRAM pointer and memory access outside the L2SRAM boundaries is requested.

• cupva::Exception(InvalidArgument) – if dst or src is a VMEM pointer.

• cupva::Exception(InvalidArgument) – if count exceeds maximum allowable limit.

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

Returns:

Allocated command object.

static CmdMemcpy Create(

const OffsetPointer<void> &dst,

const void *const src,

size_t const count,

)

Construct a CmdMemcpy to copy 1D data using destination OffsetPointer and raw source pointer.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• dst – Reference to the destination offset pointer.

• src – Source memory address.

• count – The number of bytes to be copied.

Throws:

• cupva::Exception(DriverAPIError) – if driver API layer returns an error due to:

  • Memory allocation failure

  • Pinning or mapping memory failure

  • Unable to detect chip information

• Refer – cupva::Context for possible exceptions if creation of default context is required.

• cupva::Exception(InvalidArgument) – if dst or src is not registered as a device pointer in DRAM, L2SRAM (Orin only)

• cupva::Exception(InvalidArgument) – if dst or src is a L2SRAM pointer and memory access outside the L2SRAM boundaries is requested.

• cupva::Exception(InvalidArgument) – if dst or src is a VMEM pointer.

• cupva::Exception(InvalidArgument) – if count exceeds maximum allowable limit.

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

Returns:

Allocated command object.

static CmdMemcpy Create(

void *const dst,

const OffsetPointer<void const> &src,

size_t const count,

)

Construct a CmdMemcpy to copy 1D data using raw destination pointer and source OffsetPointer.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• dst – Destination memory address.

• src – Reference to the source offset pointer.

• count – The number of bytes to be copied.

Throws:

• cupva::Exception(DriverAPIError) – if driver API layer returns an error due to:

  • Memory allocation failure

  • Pinning or mapping memory failure

  • Unable to detect chip information

• Refer – cupva::Context for possible exceptions if creation of default context is required.

• cupva::Exception(InvalidArgument) – if dst or src is not registered as a device pointer in DRAM, L2SRAM (Orin only)

• cupva::Exception(InvalidArgument) – if dst or src is a L2SRAM pointer and memory access outside the L2SRAM boundaries is requested.

• cupva::Exception(InvalidArgument) – if dst or src is a VMEM pointer.

• cupva::Exception(InvalidArgument) – if count exceeds maximum allowable limit.

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

Returns:

Allocated command object.

static CmdMemcpy Create2D(

const OffsetPointer<void> &dst,

const OffsetPointer<void const> &src,

size_t const dstLinePitch,

size_t const srcLinePitch,

size_t const width,

size_t const height,

)

Construct a CmdMemcpy to copy 2D data using OffsetPointers.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• dst – Reference to the destination offset pointer.

• src – Reference to the source offset pointer.

• dstLinePitch – Line pitch of the destination memory in bytes.

• srcLinePitch – Line pitch of the source memory in bytes.

• width – The width of the 2D transfer in bytes.

• height – The height of the 2D transfer.

Throws:

• cupva::Exception(DriverAPIError) – if driver API layer returns an error due to:

  • Memory allocation failure

  • Pinning or mapping memory failure

  • Unable to detect chip information

• Refer – cupva::Context for possible exceptions if creation of default context is required.

• cupva::Exception(InvalidArgument) – if dst or src is not registered as a device pointer in DRAM, L2SRAM (Orin only)

• cupva::Exception(InvalidArgument) – if dst or src is a L2SRAM pointer and memory access outside the L2SRAM boundaries is requested.

• cupva::Exception(InvalidArgument) – if dst or src is a VMEM pointer.

• cupva::Exception(InvalidArgument) – if dstLinePitch, srcLinePitch, width or height exceeds maximum allowable limit.

• cupva::Exception(InvalidArgument) – if width is greater than the dstLinePitch or srcLinePitch.

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

Returns:

Allocated command object.

static CmdMemcpy Create2D(

void *const dst,

const void *const src,

size_t const dstLinePitch,

size_t const srcLinePitch,

size_t const width,

size_t const height,

)

Construct a CmdMemcpy to copy 2D data using raw pointers.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• dst – Destination memory address.

• src – Source memory address.

• dstLinePitch – Line pitch of the destination memory in bytes.

• srcLinePitch – Line pitch of the source memory in bytes.

• width – The width of the 2D transfer in bytes.

• height – The height of the 2D transfer.

Throws:

• cupva::Exception(DriverAPIError) – if driver API layer returns an error due to:

  • Memory allocation failure

  • Pinning or mapping memory failure

  • Unable to detect chip information

• Refer – cupva::Context for possible exceptions if creation of default context is required.

• cupva::Exception(InvalidArgument) – if dst or src is not registered as a device pointer in DRAM, L2SRAM (Orin only)

• cupva::Exception(InvalidArgument) – if dst or src is a L2SRAM pointer and memory access outside the L2SRAM boundaries is requested.

• cupva::Exception(InvalidArgument) – if dst or src is a VMEM pointer.

• cupva::Exception(InvalidArgument) – if dstLinePitch, srcLinePitch, width or height exceeds maximum allowable limit.

• cupva::Exception(InvalidArgument) – if width is greater than the dstLinePitch or srcLinePitch.

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

Returns:

Allocated command object.

static CmdMemcpy Create2D(

const OffsetPointer<void> &dst,

const void *const src,

size_t const dstLinePitch,

size_t const srcLinePitch,

size_t const width,

size_t const height,

)

Construct a CmdMemcpy to copy 2D data using destination OffsetPointer and raw source pointer.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• dst – Reference to the destination offset pointer.

• src – Source memory address.

• dstLinePitch – Line pitch of the destination memory in bytes.

• srcLinePitch – Line pitch of the source memory in bytes.

• width – The width of the 2D transfer in bytes.

• height – The height of the 2D transfer.

Throws:

• cupva::Exception(DriverAPIError) – if driver API layer returns an error due to:

  • Memory allocation failure

  • Pinning or mapping memory failure

  • Unable to detect chip information

• Refer – cupva::Context for possible exceptions if creation of default context is required.

• cupva::Exception(InvalidArgument) – if dst or src is not registered as a device pointer in DRAM, L2SRAM (Orin only)

• cupva::Exception(InvalidArgument) – if dst or src is a L2SRAM pointer and memory access outside the L2SRAM boundaries is requested.

• cupva::Exception(InvalidArgument) – if dst or src is a VMEM pointer.

• cupva::Exception(InvalidArgument) – if dstLinePitch, srcLinePitch, width or height exceeds maximum allowable limit.

• cupva::Exception(InvalidArgument) – if width is greater than the dstLinePitch or srcLinePitch.

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

Returns:

Allocated command object.

static CmdMemcpy Create2D(

void *const dst,

const OffsetPointer<void const> &src,

size_t const dstLinePitch,

size_t const srcLinePitch,

size_t const width,

size_t const height,

)

Construct a CmdMemcpy to copy 2D data using raw destination pointer and source OffsetPointer.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• dst – Destination memory address.

• src – Reference to the source offset pointer.

• dstLinePitch – Line pitch of the destination memory in bytes.

• srcLinePitch – Line pitch of the source memory in bytes.

• width – The width of the 2D transfer in bytes.

• height – The height of the 2D transfer.

Throws:

• cupva::Exception(DriverAPIError) – if driver API layer returns an error due to:

  • Memory allocation failure

  • Pinning or mapping memory failure

  • Unable to detect chip information

• Refer – cupva::Context for possible exceptions if creation of default context is required.

• cupva::Exception(InvalidArgument) – if dst or src is not registered as a device pointer in DRAM, L2SRAM (Orin only)

• cupva::Exception(InvalidArgument) – if dst or src is a L2SRAM pointer and memory access outside the L2SRAM boundaries is requested.

• cupva::Exception(InvalidArgument) – if dst or src is a VMEM pointer.

• cupva::Exception(InvalidArgument) – if dstLinePitch, srcLinePitch, width or height exceeds maximum allowable limit.

• cupva::Exception(InvalidArgument) – if width is greater than the dstLinePitch or srcLinePitch.

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

Returns:

Allocated command object.