StaticDataFlow

Fully qualified name: cupva::StaticDataFlow

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

class StaticDataFlow : public cupva::BaseDataFlow

The StaticDataFlow is used to describe a regular tiling pattern.

Deprecated:

This class is deprecated. Use cupva::RasterDataFlow or cupva::SequenceDataFlow instead.

The StaticDataFlow is the most-common-used dataflow in a PVA application. It is used to describe a pre-defined memory-access-pattern. The user sets up the pattern with Host CPU code using the below APIs. Once the program is submitted to the hardware, the memory-accesss-pattern can’t be changed. This provides an advantage of saving VPU address-calculation-instructions, allowing higher compute-instruction density for better performance and power efficiency.

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

template<typename T, typename std::enable_if<T::isPrimitive, bool>::type = true>
inline StaticDataFlow &link(

T &next,

)

Link a level0 dataflow.

Link a level0 dataflow (StaticDataFlow or ConfigDataFlow) to the tail of the dataflow-list holding by current dataflow. For example:

StaticDataFlow s0, s1, s2;
s0.link(s1);
// Above creates a dataflow-list holding by s0:
// +----+    +----+
// | s0 | -> | s1 |
// +----+    +----+
s2.link(s0);
// Above concatenates the dataflow-list to the tail of s2 and
// create a new dataflow-list holding by s2:
// +----+    +----+    +----+
// + s2 + -> | s0 | -> | s1 |
// +----+    +----+    +----+

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Template Parameters:

• T – The dataflow type of the node to be linked.

• std::enable_if<T::isPrimitive, bool>::type – Check if the node type is primitive.

Parameters:

next – The dataflow/dataflow-list to be linked.

Throws:

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

Returns:

StaticDataFlow& The reference of head dataflow which holding the list.

template<typename T, typename std::enable_if<T::isPrimitive, bool>::type = true>
inline StaticDataFlow &append(

T &next,

)

Append a level0 dataflow.

append() has the almost same effect with link(), except it removes the boundary of the dataflows. The appended dataflow will be executable once the previous dataflow is done, without the need of a VPU-DMA-handshake in between.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Template Parameters:

• T – The dataflow type of the node to be appended.

• std::enable_if<T::isPrimitive, bool>::type – Check if the node type is primitive.

Parameters:

next – The dataflow/dataflow-list to be appended.

Throws:

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

Returns:

StaticDataFlow& The reference of head dataflow which holding the list.

StaticDataFlow &handler(const Parameter &handler)

Set the StaticDataFlow 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:

StaticDataFlow& The reference to current object

StaticDataFlow &bpp(int32_t const bpp)

Set StaticDataFlow’s byte-per-pixel.

The pixel of a StaticDataFlow can be standard data type or user-defined-struct (class object is not acceptable)

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

bpp – The number of byte per pixel

Throws:

• cupva::Exception(InvalidArgument) – The bpp is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &tile(int32_t const width, int32_t const height = 1)

Set StaticDataFlow’s tile size.

A tile is the transfer unit atom supported by StaticDataFlow. Each tile transfer will result in height rows of width contiguous pixels being transferred. The rows do not need to be contiguous, and the pitch between rows is defined by the srcLinePitch() and dstLinePitch().

The tile is the amount of data transferred for a single iteration in the first dimension of the StaticDataFlow. See srcDim1/dstDim1 for more information.

A “dummy” transfer can be initiated by simply not calling the tile() API or setting both width and height arguments to 0. User may find “dummy” transfers useful when linking or appending multiple DataFlows.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• width – The width of the tile (in pixel)

• height – The height of the tile (in pixel). By default, set to 1 when it is not specified by the caller, means it’s 1D tile

Throws:

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

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &padDim(PadDirType const dir, int32_t const dim)

Set StaticDataFlow’s padding direction and number of pixels to a tile.

StaticDataFlow supports padding one side of the tile in x dimension and one side of the tile in y dimension. So for example, top and right padding may be combined, but not top and bottom.

StaticDataFlow padding does not affect the size of the tile written to VMEM. Rather than adding extra data writes to VMEM, the padding instead reduces the amount of data read from DRAM and makes up the remainder of the tile with the specified padding.

StaticDataFlow s0;
s0.padDim(PAD_TOP, 1);    // Okay
s0.padDim(PAD_BOTTOM, 2); // Conflict with first call
s0.padDim(PAD_LEFT, 1);   // Okay

// if the pad dimensions are the same in different directions,
// the directions can be bitwise-or as 1 argument.
s0.padDim(PAD_TOP | PAD_LEFT, 1);   // Okay
s0.padDim(PAD_LEFT | PAD_RIGHT, 1); // Conflict in current call

As StaticDataFlow can’t pad in both top and bottom, the DMA compiler reports error when there are conflicts.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• dir – Padding direction (check PadDirType for details)

• dim – Padding count in pixel

Throws:

• cupva::Exception(InvalidArgument) – The pad direction is self-conflict

• cupva::Exception(InvalidArgument) – The pad size is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &padVal(PadModeType const type, int32_t const val = 0)

Set StaticDataFlow’s padding value.

Two types of padding are supported (check PadModeType for details): constant-padding and BPE-padding. Note that the padding feature is only for standard-typed pixel (exclude double-precision-floating-point). The result is unpredictable when the pixel is unsupported type.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• type – The padding mode

• val – The padding value (0 by default) in constant-padding mode. It is ignored when the padding mode is BPE

Throws:

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &granularity(GranType const type)

Set StaticDataFlow’s transfer granularity.

Check GranType for details.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

type – The granularity type

Throws:

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &src(const void *const ptr)

Set StaticDataFlow’s source pointer.

A CUPVA device pointer (DRAM, SRAM or VMEM-typed) is accepted.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

ptr – The device pointer to the source buffer

Throws:

• cupva::Exception(InvalidArgument) – If the pointer is invalid

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &src(OffsetPointer<void const> const op)

Set StaticDataFlow’s source with a OffsetPointer.

The OffsetPointer is taking into the DMA compilation but the real pointer value can be changed in the frame-loop.

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 type

Parameters:

op – The reference to the OffsetPointer

Throws:

• cupva::Exception(InvalidArgument) – If the pointer is invalid

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

Returns:

StaticDataFlow& The reference to current object

int32_t id() const

Get StaticDataFlow’s id.

Deprecated:

This function is deprecated.

The id is only valid after the StaticDataFlow is compiled.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Throws:

• cupva::Exception(InvalidState) – Can’t get a valid id before it is compiled

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

Returns:

StaticDataFlow id

StaticDataFlow &srcLinePitch(int32_t const linePitch)

Set StaticDataFlow’s source line pitch.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

linePitch – The line pitch in pixel

Throws:

• cupva::Exception(InvalidArgument) – The line pitch is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &srcDim1(int32_t const niter, int32_t const adv)

Set StaticDataFlow’s source 1st dimension traversal.

The StaticDataFlow supports up to three-dimensional-traversal of the target address. The tile address advance 1 stride per iteration.

The 1st dimension is the inner-most dimension of the StaticDataFlow. It contains “niter” count of tiles, the tile stride is “adv” count of pixels.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• niter – The number of source iterations in the first dimension. An iteration in the first dimension is a single tile. Must be greater than zero and less than or equal to 256.

• adv – The stride (in pixels) of each iteration

Throws:

• cupva::Exception(InvalidArgument) – The niter is out-of-range

• cupva::Exception(InvalidArgument) – The adv is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &srcDim2(int32_t const niter, int32_t const adv)

Set StaticDataFlow’s source 2nd dimension traversal.

The 2nd dimension advance by 1 after going over all tiles in the 1st dimension. The 1st dimension starts a new round with an address offset provided by the 2nd dimension.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• niter – The number of source iterations in the second dimension. An iteration in the second dimension happens when niter1 tiles have been transferred, where niter1 is the argument passed as niter to srcDim1. Must be greater than zero and less than or equal to 256.

• adv – The stride (in pixels) of each iteration

Throws:

• cupva::Exception(InvalidArgument) – The niter is out-of-range

• cupva::Exception(InvalidArgument) – The adv is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &srcDim3(int32_t const niter, int32_t const adv)

Set StaticDataFlow’s source 3rd dimension traversal.

The 3rd dimension advance by 1 after going over all iterations in the 2nd dimension. The 2nd dimension starts a new round with an address offset provided by the 3rd dimension.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• niter – The number of source iterations in the third dimension. An iteration in the third dimension happens when niter2 iterations in the second dimension have been transferred, where niter2 is the argument passed as niter to srcDim2. Must be greater than zero and less than or equal to 256.

• adv – The stride (in pixels) of each iteration

Throws:

• cupva::Exception(InvalidArgument) – The niter is out-of-range

• cupva::Exception(InvalidArgument) – The adv is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &srcCircularBuffer(

int32_t const cbStart,

int32_t const cbLen,

)

Set StaticDataFlow’s source circular buffer.

The StaticDataFlow supports circular buffering mode. Once the byte address exceeds the size of the circular buffer, it is wrapped back to the base of the circular buffer. The equation below shows the address calculation:

circular_address = (byte_address - base_address)
                 % circular_buffer_size
                 + base_address;

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• cbStart – The start offset to the source pointer(in pixel)

• cbLen – The circular buffer size in pixel

Throws:

• cupva::Exception(InvalidArgument) – The cbStart is out-of-range

• cupva::Exception(InvalidArgument) – The cbLen is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &dst(void *const ptr, void *const ptr2 = nullptr)

Set StaticDataFlow’s destination pointer.

A CUPVA device pointer (DRAM, SRAM or VMEM-typed) is accepted.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• ptr – The device pointer to the destination buffer

• ptr2 – The device pointer to an additional destination buffer. It can be set a non-null value only when ptr points to a valid buffer in VMEM. DMA will replicate the same data in the ptr buffer to the ptr2 buffer during data transfer. The starting address of VMEM replication buffer needs to be 64-byte aligned, and only 1 and 2 bytes per pixel are supported by full replication.

Throws:

• cupva::Exception(InvalidArgument) – If the pointer is invalid

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &dst(

OffsetPointer<void> const op,

OffsetPointer<void> const op2 = {},

)

Set StaticDataFlow’s destination with a OffsetPointer.

The OffsetPointer is taking into the DMA compilation but the real pointer value can be changed in the frame-loop.

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 type

Parameters:

• op – The reference to the OffsetPointer

• op2 – The reference to the OffsetPointer of additional destination buffer. It can be set a valid OffsetPointer only when op points to a valid buffer in VMEM. DMA will replicate the same data in the op buffer to the op2 buffer during data transfer. The starting address of VMEM replication buffer needs to be 64-byte aligned, and only 1 and 2 bytes per pixel are supported by full replication.

Throws:

• cupva::Exception(InvalidArgument) – If the pointer is invalid

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &dstLinePitch(int32_t const linePitch)

Set StaticDataFlow’s destination line pitch.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

linePitch – The line pitch in pixel

Throws:

• cupva::Exception(InvalidArgument) – The line pitch is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &dstDim1(int32_t const niter, int32_t const adv)

Set StaticDataFlow’s destination 1st dimension traversal.

The 1st dimension is the inner-most dimension of the StaticDataFlow. It contains “niter” count of tiles, the tile stride is “adv” count of pixels.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• niter – The number of dst iterations in the first dimension. An iteration in the first dimension is a single tile. Must be greater than zero and less than or equal to 256.

• adv – The stride (in pixels) of each iteration

Throws:

• cupva::Exception(InvalidArgument) – The niter is out-of-range

• cupva::Exception(InvalidArgument) – The adv is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &dstDim2(int32_t const niter, int32_t const adv)

Set StaticDataFlow’s destination 2nd dimension traversal.

The 2nd dimension advance by 1 after going over all tiles in the 1st dimension. The 1st dimension starts a new round with an address offset provided by the 2nd dimension.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• niter – The number of dst iterations in the second dimension. An iteration in the second dimension happens when niter1 tiles have been transferred, where niter1 is the argument passed as niter to dstDim1. Must be greater than zero and less than or equal to 256.

• adv – The stride (in pixels) of each iteration

Throws:

• cupva::Exception(InvalidArgument) – The niter is out-of-range

• cupva::Exception(InvalidArgument) – The adv is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &dstDim3(int32_t const niter, int32_t const adv)

Set StaticDataFlow’s destination 3rd dimension traversal.

The 3rd dimension advance by 1 after going over all iterations in the 2nd dimension. The 2nd dimension starts a new round with an address offset provided by the 3rd dimension.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• niter – The number of dst iterations in the third dimension. An iteration in the third dimension happens when niter2 iterations in the second dimension have been transferred, where niter2 is the argument passed as niter to dstDim2. Must be greater than zero and less than or equal to 256.

• adv – The stride (in pixels) of each iteration

Throws:

• cupva::Exception(InvalidArgument) – The niter is out-of-range

• cupva::Exception(InvalidArgument) – The adv is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

StaticDataFlow &dstCircularBuffer(

int32_t const cbStart,

int32_t const cbLen,

)

Set StaticDataFlow’s destination circular buffer.

The StaticDataFlow supports circular buffering mode. Once the byte address exceeds the size of the circular buffer, it is wrapped back to the base of the circular buffer. The equation below shows the address calculation:

circular_address = (byte_address - base_address)
                 % circular_buffer_size
                 + base_address;

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• cbStart – The start offset to the destination pointer(in pixel)

• cbLen – The circular buffer size in pixel

Throws:

• cupva::Exception(InvalidArgument) – The cbStart is out-of-range

• cupva::Exception(InvalidArgument) – The cbLen is out-of-range

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

Returns:

StaticDataFlow& The reference to current object

void copy(const StaticDataFlow &source)

Copy all fields of a StaticDataFlow into this object.

Both this object and the source object must have been created using Create(), CmdProgram::addDataFlow(), or CmdProgram::addDataFlowHead().

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

source – The source object to copy from

Throws:

cupva::Exception(InvalidState) – This object and/or the source object were not instantiated correctly

Public Static Attributes

static constexpr bool isPrimitive = {true}

Only primitive dataflow can be linked/appended.

static constexpr GranType TILE = {GranType::TILE}

Transfers a tile

static constexpr GranType DIM1 = {GranType::DIM1}

Transfers all tiles in 1st dimension

static constexpr GranType DIM2 = {GranType::DIM2}

Transfers all tiles in 1st and 2nd dimensions

static constexpr GranType ALL = {GranType::ALL}

Transfers all tiles in the dataflow