GatherScatterDataFlow#

Fully qualified name: cupva::GatherScatterDataFlow

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

class GatherScatterDataFlow : public cupva::BaseDataFlow #

The GatherScatterDataFlow provides the ability to load data from arbitrary addresses or store data to disparate locations in external memory.

The VPU hardware lacks the ability to access external memory (DRAM/SRAM) directly and relies on DataFlows configured by the user. GatherScatterDataFlow allows device code to configure the dynamic accesses for gather/scatter use cases. Refer to device side API documentation for details on configuring gather/scatter operations in device code.

All DataFlows should be created by invoking methods on cupva::CmdProgram. DataFlows are owned by CmdProgram objects. User should only operate on DataFlows via non-owning references returned by CmdProgram objects.

Public Functions

GatherScatterDataFlow &handler(Parameter const &handler)#

Set GatherScatterDataFlow’s handler.

Usage considerations

Allowed context for the API call
- Thread-safe: No
API group
- Init: Yes
- Runtime: No
- De-Init: No

Parameters:

handler – The handler defined in vmem and represented by the host parameter.

Throws:

cupva::Exception(InvalidArgument) – The handler is not from VMEM.
cupva::Exception(InvalidState) – The object is not instantiated correctly.

Returns:

GatherScatterDataFlow& The reference of current object.

GatherScatterDataFlow &numTilesPerTrigger(int32_t const numTiles)#

Specify GatherScatterDataFlow’s number of tiles per trigger.

Usage considerations

Allowed context for the API call
- Thread-safe: No
API group
- Init: Yes
- Runtime: No
- De-Init: No

Parameters:: numTiles – The number of tiles per DMA trigger.
Returns:: GatherScatterDataFlow& The reference of current object.

GatherScatterDataFlow &bufferType( mem::BufferType const type, bool const allowNonUniformLinePitch = false, )#

Set the buffer type.

This API is used to specify the bufferType if OffsetPointer is used as an argument to src() or dst(). If not specified in such cases, it defaults to mem::BufferType::RAW.

If the buffer specified to src() or dst() does not match that specified here, an exception will be thrown during CmdProgram::updateDataFlows().

This API is optional if src()/dst() is not called with an OffsetPointer. If specified in such cases, the buffer type of the external memory pointer is checked during DMA compilation.

Usage considerations

Allowed context for the API call
- Thread-safe: No
API group
- Init: Yes
- Runtime: No
- De-Init: No

Parameters:

type – The type of the external buffer specified with src() or dst()
allowNonUniformLinePitch – The flag to allow line pitch of each plane to be different in multi-planar case. Default is false. This flag only needs to be set for RAW type buffer and setting it to true may have negative impact on performance.

Returns:

GatherScatterDataFlow& reference to current object.

template<typename T> inline GatherScatterDataFlow &src( T &&op, int32_t const width = 0, int32_t const height = 1, int32_t const linePitch = 0, )#

Initialize the source via device pointer or OffsetPointer.

GatherScatterDataFlow supports reads to VMEM and writes from VMEM. If this API is used, the GatherScatterDataFlow will be configured in read to VMEM direction. Only one of src() or dst() may be specified. The direction of a GatherScatterDataFlow cannot be changed in device code.

GatherScatterDataFlow supports surfaces imported from NvSci or allocated via cupva_utils::AllocSurface. There are limitations on dynamically updating the external base for surfaces in device code. Refer to cupvaGSDFResetExtBase() for more information.

If op will resolve to a surface, bufferType() must be called with cupva::mem::BufferType::SURFACE passed to bufferType argument. If op is an uninitialized OffsetPointer, cupvaGSDFResetExtBase() must be called on the device side to configure the correct geometry info for the external buffer. If op will resolve to a RAW multi-planar buffer and the line pitch for each plane is not the same, user has to call bufferType() with allowNonUniformLinePitch argument set to true.

Usage considerations

Allowed context for the API call
- Thread-safe: No
API group
- Init: Yes
- Runtime: No
- De-Init: No

Template Parameters:

T – The source buffer type. Can be either U* (raw pointer), or OffsetPointer<U>, where sizeof(U) is 1, 2 or 4 bytes. The sizeof(U) defines the pixel size for GSDF dimensions and padding.

Parameters:

op – The initial pointer to the source or OffsetPointer of the source. Must be in DRAM or L2SRAM.
width – The width of source buffer in pixels. Ignored for surface types.
height – The height of source buffer in pixels. Ignored for surface types or optional for 1D buffers.
linePitch – The source line pitch in pixels. Ignored for surface types. If omitted or set to zero, the value passed for width will be used.

Throws:

cupva::Exception(InvalidArgument) – If the pointer is invalid.
cupva::Exception(InvalidState) – dst() was already called for this object.
cupva::Exception(InvalidState) – The object is not instantiated correctly.

Returns:

GatherScatterDataFlow& The reference to current object.

template<typename T> inline GatherScatterDataFlow &src( T &&op, PlanarGeometry const &geom, )#

Initialize the source via device pointer or OffsetPointer and geometry info.

GatherScatterDataFlow supports reads to VMEM and writes from VMEM. If this API is used, the GatherScatterDataFlow will be configured in read to VMEM direction. Only one of src() or dst() may be specified. The direction of a GatherScatterDataFlow cannot be changed in device code.

This API only accepts a RAW type of op. For SURFACE type, user must call the other src() API to initialize a GSDF transfer source.

Usage considerations

Allowed context for the API call
- Thread-safe: No
API group
- Init: Yes
- Runtime: No
- De-Init: No

Template Parameters:

T – The source buffer type. Can be either U* (raw pointer), or OffsetPointer<U>, where sizeof(U) is 1, 2 or 4 bytes. The sizeof(U) defines the pixel size for GSDF dimensions and padding.

Parameters:

op – The initial pointer to the source or OffsetPointer of the source. Must be in DRAM or L2SRAM.
geom – The reference to a PlanarGeometry object.

Throws:

cupva::Exception(InvalidArgument) – If the pointer is invalid.
cupva::Exception(InvalidState) – dst() was already called for this object.
cupva::Exception(InvalidState) – The object is not instantiated correctly.

Returns:

GatherScatterDataFlow& The reference to current object.

template<typename T> inline GatherScatterDataFlow &dst( T &&op, int32_t const width = 0, int32_t const height = 1, int32_t const linePitch = 0, )#

Initialize the destination via device pointer or OffsetPointer.

GatherScatterDataFlow supports reads to VMEM and writes from VMEM. If this API is used, the GatherScatterDataFlow will be configured in write from VMEM direction. Only one of src() or dst() may be specified. The direction of a GatherScatterDataFlow cannot be changed in device code.

GatherScatterDataFlow supports surfaces imported from NvSci or allocated via cupva_utils::AllocSurface. There are limitations on dynamically updating the external base for surfaces in device code. Refer to cupvaGSDFResetExtBase() for more information.

If op will resolve to a surface, bufferType() must be called with cupva::mem::BufferType::SURFACE passed to bufferType argument. If op is an uninitialized OffsetPointer, cupvaGSDFResetExtBase() must be called on the device side to configure the correct geometry info for the external buffer. If op will resolve to a RAW multi-planar buffer and the line pitch for each plane is not the same, user has to call bufferType() with allowNonUniformLinePitch argument set to true.

Usage considerations

Allowed context for the API call
- Thread-safe: No
API group
- Init: Yes
- Runtime: No
- De-Init: No

Template Parameters:

T – The destination buffer type. Can be either U* (raw pointer), or OffsetPointer<U>, where sizeof(U) is 1, 2 or 4 bytes. The sizeof(U) defines the pixel size for GSDF dimensions and padding.

Parameters:

op – The initial pointer to the destination or OffsetPointer of the destination. Must be in DRAM or L2SRAM.
width – The width of destination buffer in pixels. Ignored for surface types.
height – The height of destination buffer in pixels. Ignored for surface types or optional for 1D buffers.
linePitch – The destination line pitch in pixels. Ignored for surface types. If omitted or set to zero, the value passed for width will be used.

Throws:

cupva::Exception(InvalidArgument) – If the pointer is invalid.
cupva::Exception(InvalidState) – src() was already called for this object.
cupva::Exception(InvalidState) – The object is not instantiated correctly.

Returns:

GatherScatterDataFlow& The reference to current object.

template<typename T> inline GatherScatterDataFlow &dst( T &&op, const PlanarGeometry &geom, )#

Initialize the destination via device pointer or OffsetPointer and geometry info.

GatherScatterDataFlow supports reads to VMEM and writes from VMEM. If this API is used, the GatherScatterDataFlow will be configured in write from VMEM direction. Only one of src() or dst() may be specified. The direction of a GatherScatterDataFlow cannot be changed in device code.

This API only accepts a RAW type of op. For SURFACE type, user must call the other dst() API to initialize a GSDF transfer destination.

Usage considerations

Allowed context for the API call
- Thread-safe: No
API group
- Init: Yes
- Runtime: No
- De-Init: No

Template Parameters:

T – The destination buffer type. Can be either U* (raw pointer), or OffsetPointer<U>, where sizeof(U) is 1, 2 or 4 bytes. The sizeof(U) defines the pixel size for GSDF dimensions and padding.

Parameters:

op – The initial pointer to the destination or OffsetPointer of the destination. Must be in DRAM or L2SRAM.
geom – The reference to a PlanarGeometry object.

Throws:

cupva::Exception(InvalidArgument) – If the pointer is invalid.
cupva::Exception(InvalidState) – src() was already called for this object.
cupva::Exception(InvalidState) – The object is not instantiated correctly.

Returns:

GatherScatterDataFlow& The reference to current object.

GatherScatterDataFlow &tile( int32_t const width, int32_t const height = 1, )#

Set the GatherScatterDataFlow tile size.

This API must be called to initialize tile size for all tiles. The tile size specified here is used for a heuristic to determine maximum transfer size for internal bandwidth allocation between DataFlows on the same phase. The tile size can be changed by calling device APIs later, but this will not change the bandwidth allocation.

The surface dimensions passed to src() or dst() or inferred from the external surface metadata must be sufficient to hold at least a single tile.

Usage considerations

Allowed context for the API call
- Thread-safe: No
API group
- Init: Yes
- Runtime: No
- De-Init: No

Parameters:

width – The tile width in pixels
height – The tile height in pixels

Throws:

cupva::Exception(InvalidArgument) – The tile size is out-of-range
cupva::Exception(InvalidState) – The object is not instantiated correctly.

Returns:

GatherScatterDataFlow& The reference of current object.

GatherScatterDataFlow &padVal( PadModeType const mode, int32_t const val = 0, )#

Initialize pad mode and value.

When using cupvaGSDFUpdateTiles() on GatherScatterDataFlows which are reading to VMEM, padding will be automatically applied. This API is used to set the policy for padding. Supported policies are either boundary pixel extension or constant value. The default policy if this API is not called is padding with constant zeros.

Usage considerations

Allowed context for the API call
- Thread-safe: No
API group
- Init: Yes
- Runtime: No
- De-Init: No

Parameters:

mode – The pad mode, can be either PAD_BPE or PAD_CONST
val – The pad value, this field is only used when the mode is PAD_CONST.

Throws:

cupva::Exception(InvalidState) – The object is not instantiated correctly.

Returns:

GatherScatterDataFlow& The reference to current object.