Dataflow configuration#

APIs to configure DataFlows which have been requested from a CmdProgram.

Each VPU task launch consists of a cupva::Executable associated with a number of Dataflows via the cupva::CmdProgram object. The Dataflows are used to describe the required DMA configuration; these APIs therefore allow programming the PVA’s DMA engine.

The DataFlow APIs accept cuPVA device pointers, which have been allocated by the client. These allocations must be appropriate for the intended use by the PVA’s DMA engine. Buffers must be allocated with correct access permissions. Output buffers must have write permissions and input buffers must have read permissions. The buffers must be large enough such that the DMA accesses are within the allocated buffer range. Allocating a buffer with cupva::mem:Alloc will result in a buffer which may be read/written by the PVA’s DMA engine.

Specifying DataFlows which require VPU triggering creates a contract between the host DataFlow setup code and the device DataFlow triggering code. The user must ensure that any cupva::CmdProgram containing DataFlows which require VPU triggering are submitted with a cupva::Executable. This cupva::Executable must ensure that all DataFlows are triggered to completion. The CmdProgram will not be considered completed by the system until all DataFlows have been completely triggered.

Enumerations#

cupvaDataFlowType_t: The type of DataFlow object.
cupvaGranType_t: Enumeration of dataflow trigger granularity.
cupvaPadDirType_t: Define PadDirType as uint8_t using one-hot encoding.
cupvaPadModeType_t: Enumeration of dataflow-padding types.
cupvaTransModeType_t: Transposition load mode.
cupvaTransferModeType_t: SequenceDataFlowTransfer sequencing mode.

Functions#

cupvaError_t CupvaDataFlowAppend(cupvaDataFlow_t const df1, cupvaDataFlow_t const df2): Append one dataflow to another.
cupvaError_t CupvaDataFlowLink(cupvaDataFlow_t const df1, cupvaDataFlow_t const df2): Link two dataflows.
cupvaError_t CupvaGatherScatterDataFlowSetParams(cupvaDataFlow_t const df, cupvaGatherScatterDataFlowParams_t *const gsdfParams): Set the parameters for a GatherScatterDataFlow.
cupvaError_t CupvaRasterDataFlowSetParams(cupvaDataFlow_t const df, cupvaRasterDataFlowParams_t *const rdfParams): Set the parameters for a RasterDataFlow.
cupvaError_t CupvaSequenceDataFlowAddTransfer(cupvaDataFlow_t const df, cupvaSequenceDataFlowTransferParams_t *const transferParams): Add a transfer to the SequenceDataFlow.
cupvaError_t CupvaSequenceDataFlowSetParams(cupvaDataFlow_t const df, cupvaSequenceDataFlowParams_t *const sqdfParams): Set the parameters for a SequenceDataFlow.
cupvaError_t CupvaTensorDataFlowSetParams(cupvaDataFlow_t const df, cupvaTensorDataFlowParams_t *const tdfParams): Set the parameters for a TensorDataFlow.

Data Structures#

cupvaGatherScatterDataFlowParams_t: Parameters structure for CupvaGatherScatterDataFlowSetParams.
cupvaRasterDataFlowParams_t: Parameters structure for CupvaRasterDataFlowSetParams.
cupvaSequenceDataFlowParams_t: Parameters structure for CupvaSequenceDataFlowSetParams.
cupvaSequenceDataFlowTransferParams_t: Parameters structure for CupvaSequenceDataFlowAddTransfer.
cupvaTensorDataFlowParams_t: Parameters structure for CupvaTensorDataFlowSetParams.

Typedefs#

cupvaDataFlow_t: An abstract handle to a DataFlow, used to configure the DMA engine for a workload.

Enumerations#

enum cupvaDataFlowType_t#

The type of DataFlow object.

See Dataflow configuration.

Values:

enumerator CUPVA_DATAFLOW_TYPE_INVALID#: Sentinel value

enumerator CUPVA_STATIC_DATAFLOW#

A cupva::StaticDataFlow.

Deprecated:: This dataflow is deprecated. Use CUPVA_RASTER_DATAFLOW or CUPVA_SEQUENCE_DATAFLOW instead.

enumerator CUPVA_RASTER_DATAFLOW#: A cupva::RasterDataFlow

enumerator CUPVA_CONFIG_DATAFLOW#

A cupva::ConfigDataFlow.

Deprecated:: This dataflow is deprecated. Use CUPVA_GATHER_SCATTER_DATAFLOW or CUPVA_SEQUENCE_DATAFLOW instead.

enumerator CUPVA_DYNAMIC_DATAFLOW#

A cupva::DynamicDataFlow.

Deprecated:: This dataflow is deprecated. Use CUPVA_GATHER_SCATTER_DATAFLOW or CUPVA_SEQUENCE_DATAFLOW instead.

enumerator CUPVA_SEQUENCE_DATAFLOW#: A cupva::SequenceDataFlow

enumerator CUPVA_GATHER_SCATTER_DATAFLOW#: A cupva::GatherScatterDataFlow

enumerator CUPVA_TENSOR_DATAFLOW#: A cupva::TensorDataFlow. TensorDataFlow requires driver version >= 2006.

enumerator CUPVA_DATAFLOW_TYPE_MAX#: Sentinel value

enum cupvaGranType_t#

Enumeration of dataflow trigger granularity.

Values:

enumerator CUPVA_GRAN_TYPE_INVALID#: Sentinel value

enumerator CUPVA_GRAN_TILE#

enumerator CUPVA_GRAN_DIM1#

enumerator CUPVA_GRAN_DIM2#

enumerator CUPVA_GRAN_ALL#

enumerator CUPVA_GRAN_TYPE_MAX#: One greater than max valid value

enum cupvaPadDirType_t#

Define PadDirType as uint8_t using one-hot encoding.

Values:

enumerator CUPVA_PAD_DIR_TYPE_INVALID#: Sentinel value

enumerator CUPVA_PAD_DIR_NONE#: no padding

enumerator CUPVA_PAD_DIR_TOP#: padding to top edge

enumerator CUPVA_PAD_DIR_BOTTOM#: padding to bottom edge

enumerator CUPVA_PAD_DIR_INVALID_TOP_BOTTOM#: invalid padding to top and bottom at the same time

enumerator CUPVA_PAD_DIR_LEFT#: padding to left edge

enumerator CUPVA_PAD_DIR_TOP_LEFT#: padding to top and left edges

enumerator CUPVA_PAD_DIR_BOTTOM_LEFT#: padding to bottom and left edges

enumerator CUPVA_PAD_DIR_INVALID_TOP_BOTTOM_LEFT#: invalid padding to top, bottom and left a the same time

enumerator CUPVA_PAD_DIR_RIGHT#: padding to right edge

enumerator CUPVA_PAD_DIR_TOP_RIGHT#: padding to top and right edges

enumerator CUPVA_PAD_DIR_BOTTOM_RIGHT#: padding to bottom and right edges

enumerator CUPVA_PAD_DIR_INVALID_PAD#: invalid padding combination for this value and any larger integer

enumerator CUPVA_PAD_DIR_TYPE_MAX#: One greater than max valid value

enum cupvaPadModeType_t#

Enumeration of dataflow-padding types.

Values:

enumerator CUPVA_PAD_MODE_TYPE_INVALID#: Sentinel value

enumerator CUPVA_PAD_MODE_CONST#: Padding with a constant value

enumerator CUPVA_PAD_MODE_BPE#: Padding with boundary-pixel-extension

enumerator CUPVA_PAD_MODE_TYPE_MAX#: One greater than max valid value

enum cupvaTransModeType_t#

Transposition load mode.

There are a few constraints regarding the usage of transpose intrinsics: On Orin, in total six transposition modes (T1/T2/T4/T8/T16/T32) are supported. However, due to HW alignment constraints, only T1 mode supports all PVA data types (Byte/Halfword/Word). Please refer to section [6.3.7] in Orin PVA VPU Programmers Guide for the line pitch and data type constraints of each mode.

Values:

enumerator CUPVA_TRANS_MODE_NONE#: No transposition

enumerator CUPVA_TRANS_MODE_1#: Transpose every 1 data element

enumerator CUPVA_TRANS_MODE_2#: Transpose every 2 data elements

enumerator CUPVA_TRANS_MODE_4#: Transpose every 4 data elements

enumerator CUPVA_TRANS_MODE_8#: Transpose every 8 data elements

enumerator CUPVA_TRANS_MODE_16#: Transpose every 16 data elements

enumerator CUPVA_TRANS_MODE_32#: Transpose every 32 data elements

enum cupvaTransferModeType_t#

SequenceDataFlowTransfer sequencing mode.

Values:

enumerator CUPVA_TRANSFER_MODE_INVALID#: Sentinel value

enumerator CUPVA_TRANSFER_MODE_TILE#: Trigger is required at the start of each tile, Sync is required to check that a tile has completed.

enumerator CUPVA_TRANSFER_MODE_DIM1#: Trigger is required to start a batch of niter1 tiles, Sync is required to check that the batch has completed (see srcDim1/dstDim1).

enumerator CUPVA_TRANSFER_MODE_DIM2#: Trigger is required to start a batch of niter2 tiles, Sync is required to check that the batch has completed (see srcDim2/dstDim2).

enumerator CUPVA_TRANSFER_MODE_TRANSFER#: Trigger is required at the start of the transfer, Sync is required to check that the transfer has completed.

enumerator CUPVA_TRANSFER_MODE_CONTINUOUS#: Trigger is required at the start of a block of CONTINUOUS transfers, Sync is used to check that the block has completed.

enumerator CUPVA_TRANSFER_MODE_MAX#: Sentinel value

Functions#

cupvaError_t CupvaDataFlowAppend( cupvaDataFlow_t const df1, cupvaDataFlow_t const df2, )#

Append one dataflow to another.

Usage considerations

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

Parameters:

df1 – [in] The pointer to the 1st DataFlow object.
df2 – [in] The pointer to the 2nd DataFlow object.

Returns:

cupvaError_t The completion status of the operation. Possible values are:

CUPVA_ERROR_NONE if the operation was successful.
CUPVA_INVALID_ARGUMENT if df1 was a null pointer.
CUPVA_INVALID_STATE if the object was not instantiated correctly.

cupvaError_t CupvaDataFlowLink( cupvaDataFlow_t const df1, cupvaDataFlow_t const df2, )#

Link two dataflows.

Usage considerations

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

Parameters:

df1 – [in] The pointer to the 1st DataFlow object.
df2 – [in] The pointer to the 2nd DataFlow object.

Returns:

cupvaError_t The completion status of the operation. Possible values are:

CUPVA_ERROR_NONE if the operation was successful.
CUPVA_INVALID_ARGUMENT if df1 was a null pointer.
CUPVA_INVALID_STATE if the object was not instantiated correctly.

cupvaError_t CupvaGatherScatterDataFlowSetParams( cupvaDataFlow_t const df, cupvaGatherScatterDataFlowParams_t *const gsdfParams, )#

Set the parameters for a GatherScatterDataFlow.

Usage considerations

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

Parameters:

df – [in] The pointer to a DataFlow object.
gsdfParams – [in] The pointer to cupvaGatherScatterDataFlowParams_t struct.

Returns:

cupvaError_t The completion status of the operation. Possible values are:

CUPVA_ERROR_NONE if the operation was successful.
CUPVA_INVALID_ARGUMENT indicates one of the following:
- df was a null pointer.
- gsdfParams was a null pointer.
- gsdfParams contains invalid settings, refer cupva::GatherScatterDataFlow for more information.
CUPVA_INVALID_STATE if the object was not instantiated correctly.

cupvaError_t CupvaRasterDataFlowSetParams( cupvaDataFlow_t const df, cupvaRasterDataFlowParams_t *const rdfParams, )#

Set the parameters for a RasterDataFlow.

Usage considerations

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

Parameters:

df – [in] The pointer to a DataFlow object.
rdfParams – [in] The pointer to cupvaRasterDataFlowParams_t struct.

Returns:

cupvaError_t The completion status of the operation. Possible values are:

CUPVA_ERROR_NONE if the operation was successful.
CUPVA_INVALID_ARGUMENT indicates one of the followings:
- df was a null pointer.
- rdfParams was a null pointer.
- rdfParams->bpp was invalid.
- rdfParams->ptrSrc was an invalid pointer.
- rdfParams->linePitchSrc was out-of-range.
- rdfParams->ptrDst was an invalid pointer.
- rdfParams->linePitchDst was out-of-range.
- rdfParams->ptrTileBuffer was not in VMEM.
- rdfParams->ptrTileReplicationBuffer was not in VMEM.
- The roi size was out-of-range.
- The halo size was out-of-range.
- The tile size was out-of-range.
- The destination buffer size was out-of-range.
- The source buffer size was out-of-range.
CUPVA_INVALID_STATE if the object was not instantiated correctly.

cupvaError_t CupvaSequenceDataFlowAddTransfer( cupvaDataFlow_t const df, cupvaSequenceDataFlowTransferParams_t *const transferParams, )#

Add a transfer to the SequenceDataFlow.

Usage considerations

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

Parameters:

df – [in] The pointer to a DataFlow object.
transferParams – [in] The pointer to cupvaSequenceDataFlowTransferParams_t struct.

Returns:

cupvaError_t The completion status of the operation. Possible values are:

CUPVA_ERROR_NONE if the operation was successful.
CUPVA_INVALID_ARGUMENT indicates one of the following:
- df was a null pointer.
- df already has maximum number of transfers added.
- transferParams was a null pointer.
- transferParams contains invalid settings, refer cupva::SequenceDataFlowTransfer for more information.
CUPVA_INVALID_STATE if the object was not instantiated correctly.

cupvaError_t CupvaSequenceDataFlowSetParams( cupvaDataFlow_t const df, cupvaSequenceDataFlowParams_t *const sqdfParams, )#

Set the parameters for a SequenceDataFlow.

Usage considerations

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

Parameters:

df – [in] The pointer to a DataFlow object.
sqdfParams – [in] The pointer to cupvaSequenceDataFlowParams_t struct.

Returns:

cupvaError_t The completion status of the operation. Possible values are:

CUPVA_ERROR_NONE if the operation was successful.
CUPVA_INVALID_ARGUMENT indicates one of the following:
- df was a null pointer.
- sqdfParams was a null pointer.
- sqdfParams->handler was not from VMEM.
CUPVA_INVALID_STATE if the object was not instantiated correctly.

cupvaError_t CupvaTensorDataFlowSetParams( cupvaDataFlow_t const df, cupvaTensorDataFlowParams_t *const tdfParams, )#

Set the parameters for a TensorDataFlow.

Usage considerations

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

Parameters:

df – [in] The pointer to a DataFlow object.
tdfParams – [in] The pointer to cupvaTensorDataFlowParams_t struct.

Returns:

cupvaError_t The completion status of the operation. Possible values are:

CUPVA_ERROR_NONE if the operation was successful.
CUPVA_INVALID_ARGUMENT indicates one of the followings:
- df was a null pointer.
- tdfParams was a null pointer.
- tdfParams->bpp was invalid.
- tdfParams->ptrSrc was an invalid pointer.
- tdfParams->rowStrideSrc was out-of-range.
- tdfParams->depthStrideSrc was out-of-range.
- tdfParams->ptrDst was an invalid pointer.
- tdfParams->rowStrideDst was out-of-range.
- tdfParams->depthStrideDst was out-of-range.
- tdfParams->ptrTileBuffer was not in VMEM.
- The roi size was out-of-range.
- The halo size was out-of-range.
- The tile size was out-of-range.
- The destination buffer size was out-of-range.
- The source buffer size was out-of-range.
CUPVA_INVALID_STATE if the object was not instantiated correctly.

Typedefs#

typedef struct cupvaDataFlowRec *cupvaDataFlow_t#: An abstract handle to a DataFlow, used to configure the DMA engine for a workload.