RasterDataFlow API#

RasterDataFlow Device APIs.

Macros#

RDF_CIRCULAR: Calculate the minimum buffer length (in pixels) required to support a circular layout for RasterDataFlow.
RDF_CIRCULAR_COLUMNMAJOR: Calculate the minimum buffer length (in pixels) required to support a circular layout for RasterDataFlow in column-major traversal.
RDF_CIRCULAR_ROWMAJOR: Calculate the minimum buffer length (in pixels) required to support a circular layout for RasterDataFlow in row-major traversal.
RDF_DOUBLE: Calculate the minimum buffer length (in pixels) required to support double layout for RasterDataFlow.
RDF_SINGLE: Calculate the minimum buffer length (in pixels) required to support single layout for RasterDataFlow.
VMEM_RDF_UNIFIED: Declare a UnifiedRDFHandler.

Functions#

void * cupvaRasterDataFlowAcquire(UnifiedRDFHandler &handler): Acquire a tile for reading/writing.
void cupvaRasterDataFlowClose(UnifiedRDFHandler &handler): Close a RasterDataFlow when using acquire/release semantics.
int32_t cupvaRasterDataFlowGetAdvance(RasterDataFlowHandler &handler): Get the tile advance amount from the RasterDataFlowHandler.
uint32_t cupvaRasterDataFlowGetBppLog2(RasterDataFlowHandler &handler): Returns log2(bytes per pixel) for the RDF.
uint32_t cupvaRasterDataFlowGetBppLog2(UnifiedRDFHandler &handler): Returns log2(bytes per pixel) for the RDF.
int32_t cupvaRasterDataFlowGetCbLen(RasterDataFlowHandler &handler): Get the circular buffer length from the RasterDataFlowHandler.
int32_t cupvaRasterDataFlowGetCbLen(UnifiedRDFHandler &handler): Get the circular buffer length from the UnifiedRDFHandler.
uint8_t cupvaRasterDataFlowGetLayout(RasterDataFlowHandler &handler): Get the buffer layout from the RasterDataFlowHandler.
int32_t cupvaRasterDataFlowGetLinePitch(RasterDataFlowHandler &handler): Get the buffer line-pitch from the RasterDataFlowHandler.
int32_t cupvaRasterDataFlowGetLinePitch(UnifiedRDFHandler &handler): Get the buffer line-pitch from the UnifiedRDFHandler.
int32_t cupvaRasterDataFlowGetOffset(RasterDataFlowHandler &handler, int32_t offset): Calculate the offset of next tile.
bool cupvaRasterDataFlowIsRead(RasterDataFlowHandler &handler): Returns true if an RDF is reading to VMEM, false otherwise.
bool cupvaRasterDataFlowIsRead(UnifiedRDFHandler &handler): Returns true if an RDF is reading to VMEM, false otherwise.
void cupvaRasterDataFlowOpen(UnifiedRDFHandler &handler, void *vmemBuffer): Open a RDF when using acquire/release semantics.
void cupvaRasterDataFlowRelease(UnifiedRDFHandler &handler): Release a tile, indicating reading/writing has completed for the current tile.
void cupvaRasterDataFlowSync(RasterDataFlowHandler &handler): Synchronize and wait for a RasterDataFlow trigger event.
void cupvaRasterDataFlowTrig(RasterDataFlowHandler &handler): Trigger a RasterDataflow.
int32_t cupvaTransposeLaneOfst(UnifiedRDFHandler &handler, TranspositionMode mode, int32_t bpp): Calculate the lane offset for transposition load.
int32_t cupvaTransposeLaneOfst(RasterDataFlowHandler &handler, TranspositionMode mode, int32_t bpp): Calculate the lane offset for transposition load.

Functions#

inline void *cupvaRasterDataFlowAcquire(UnifiedRDFHandler &handler)#

Acquire a tile for reading/writing.

Call this API when you are ready to read/write to/from a tile. For a given handler, each cupvaRasterDataFlowAcquire must be followed by cupvaRasterDataFlowRelease() before the next cupvaRasterDataFlowAcquire. No diagnostic is given for failure to ensure the correct alternating call pattern.

The pointer returned is an address in the range of the buffer provided to cupvaRasterDataFlowOpen() (the same buffer as the first argument to the RasterDataFlow::tileBuffer() host API). If two tile buffers are provided to the host API, enabling full replication, the address in VMEM for the replicated tile must be computed manually using pointer math. For example, given VMEM buffers vmemBuffer and vmemBuffer2, corresponding to the arguments ptr and ptr2 provided on host side, the following device code demonstrates how to derive the pointer to the replicated tile:

uint8_t *tilePtr  = (uint8_t*)cupvaRasterDataFlowAcquire(handler);
ptrdiff_t offset  = (tilePtr - vmemBuffer);
uint8_t *tilePtr2 = vmemBuffer2 + offset;

If user loads a vector spanning the end of a circular buffer, this API will ensure that the part of the vector that exceeds the buffer size is loaded from the beginning of the buffer, but only for the tile returned as a pointer by this API. If using pointer arithmetic to share a handler with another buffer, user must manually handle the circular buffer wrap-around using cupvaCircularBufferMemcpy.

Note

A tile is not necessarily contiguous in VMEM, as a circular buffer may be in use.

Parameters:: handler – The reference to the UnifiedRDFHandler object
Returns:: Pointer to top-left of the tile.

inline void cupvaRasterDataFlowClose(UnifiedRDFHandler &handler)#

Close a RasterDataFlow when using acquire/release semantics.

Call this API when all tiles in the RDF have been acquired and released. After this call (assuming all tiles were properly sequenced) the RDF will no longer be active and a Dataflow on a different DataFlowPhase may be triggered.

Parameters:: handler – The reference to the UnifiedRDFHandler object

inline int32_t cupvaRasterDataFlowGetAdvance( RasterDataFlowHandler &handler, )#

Get the tile advance amount from the RasterDataFlowHandler.

Get the jump amount (in pixel) for the next tile. The user can use below equation to get the offset of the next tile inside the circular buffer: next_offset = (current_offset + advance) % cb_length

Parameters:: handler – The reference to the RasterDataFlowHandler object defined in the VMEM
Returns:: The advance amount in pixel

inline uint32_t cupvaRasterDataFlowGetBppLog2( RasterDataFlowHandler &handler, )#

Returns log2(bytes per pixel) for the RDF.

The DMA engine may be configured to transfer 1, 2 or 4 bytes per pixel. This is configured on the host side and may be queried here.

Parameters:: handler – The reference to the RasterDataFlowHandler object defined in the VMEM
Returns:: log2(bpp) configured for this RDF

inline uint32_t cupvaRasterDataFlowGetBppLog2( UnifiedRDFHandler &handler, )#

Returns log2(bytes per pixel) for the RDF.

The DMA engine may be configured to transfer 1, 2 or 4 bytes per pixel. This is configured on the host side and may be queried here.

Parameters:: handler – The reference to the RasterDataFlowHandler object defined in the VMEM
Returns:: log2(bpp) configured for this RDF

inline int32_t cupvaRasterDataFlowGetCbLen( RasterDataFlowHandler &handler, )#

Get the circular buffer length from the RasterDataFlowHandler.

The RasterDataFlowHandler maintains a circular buffer for RasterDataFlow. The user must modulo the tile offset by the length of this buffer to access the correct tile in VMEM. Note that the length is given in pixels, not bytes.

Parameters:: handler – The reference to the RasterDataFlowHandler object defined in the VMEM
Returns:: The circular buffer length in pixel

inline int32_t cupvaRasterDataFlowGetCbLen( UnifiedRDFHandler &handler, )#

Get the circular buffer length from the UnifiedRDFHandler.

Some RDF layouts will use a circular buffer, which must be known when configuring AGEN. Use this API to access the value of the circular buffer.

Parameters:: handler – The reference to the UnifiedRDFHandler object defined in the VMEM
Returns:: The circular buffer length in pixel

inline uint8_t cupvaRasterDataFlowGetLayout( RasterDataFlowHandler &handler, )#

Get the buffer layout from the RasterDataFlowHandler.

Parameters:: handler – The reference to the RasterDataFlowHandler object defined in the VMEM
Returns:: The buffer layout (see BufferLayoutTypes)

inline int32_t cupvaRasterDataFlowGetLinePitch( RasterDataFlowHandler &handler, )#

Get the buffer line-pitch from the RasterDataFlowHandler.

Parameters:: handler – The reference to the RasterDataFlowHandler object defined in the VMEM
Returns:: The buffer length in pixels

inline int32_t cupvaRasterDataFlowGetLinePitch( UnifiedRDFHandler &handler, )#

Get the buffer line-pitch from the UnifiedRDFHandler.

Parameters:: handler – The reference to the UnifiedRDFHandler object defined in the VMEM
Returns:: The buffer length in pixels

inline int32_t cupvaRasterDataFlowGetOffset( RasterDataFlowHandler &handler, int32_t offset, )#

Calculate the offset of next tile.

The offset will wrap back to the beginning of the buffer if it is equal to or greater than circular buffer size.

Parameters:

handler – The reference to the RasterDataFlowHandler object defined in the VMEM
offset – The offset of current tile in pixel.

Returns:

The offset of next tile in pixel

inline bool cupvaRasterDataFlowIsRead(RasterDataFlowHandler &handler)#

Returns true if an RDF is reading to VMEM, false otherwise.

RasterDataFlows may be configured to either read to VMEM, or write from VMEM. This API may be used to determine whether a handler is associated with a read or write variant.

Parameters:: handler – The reference to the RasterDataFlowHandler object defined in the VMEM
Returns:: true for a RDF reading from external memory to VMEM, false otherwise

inline bool cupvaRasterDataFlowIsRead(UnifiedRDFHandler &handler)#

Returns true if an RDF is reading to VMEM, false otherwise.

RasterDataFlows may be configured to either read to VMEM, or write from VMEM. This API may be used to determine whether a handler is associated with a read or write variant.

Parameters:: handler – The reference to the UnifiedRDFHandler object
Returns:: true for a RDF reading from external memory to VMEM, false otherwise

void cupvaRasterDataFlowOpen( UnifiedRDFHandler &handler, void *vmemBuffer, )#

Open a RDF when using acquire/release semantics.

Using acquire/release semantics with RDF is a simpler way to access RDF tiles, where the same semantics work regardless of layout. Special consideration for accessing circular buffer with AGEN is also automatically handled.

With the different semantics, user does not have a guarantee for when the underlying DMA engine is active. From DataFlowPhase perspective, an RDF using acquire/release semantics must be assumed to be active immediately after the call to open until the call to close.

Pointers passed to this function must be valid and must not be NULL. Failure to do so will result in undefined behavior.

Parameters:

handler – The reference to the UnifiedRDFHandler object
vmemBuffer – Buffer to bind the handler to. Should match the first argument passed to RasterDataFlow::tileBuffer

inline void cupvaRasterDataFlowRelease(UnifiedRDFHandler &handler)#

Release a tile, indicating reading/writing has completed for the current tile.

Call this API when you are finished reading/writing to a tile.

Parameters:: handler – The reference to the UnifiedRDFHandler object

inline void cupvaRasterDataFlowSync(RasterDataFlowHandler &handler)#

Synchronize and wait for a RasterDataFlow trigger event.

Wait for DMA engine to signal tile completion, descriptor completion, or channel completion (depending on RasterDataFlow configuration). This helper can auto-figure out the correct trigger when there are multiple triggers in the handler.

Parameters:: handler – The reference to the RasterDataFlowHandler object defined in the VMEM

inline void cupvaRasterDataFlowTrig(RasterDataFlowHandler &handler)#

Trigger a RasterDataflow.

Once triggered, the DMA engine will start the RasterDataFlow. It needs to be manually synchronized with the VPU code by using cupvaRasterDataFlowSync, before results can be used. The difference to the cupvaDataFlowTrig is this helper can auto-figure out the correct trigger to use when there are multiple triggers in the handler.

Parameters:: handler – The reference to the RasterDataFlowHandler object used

inline int32_t cupvaTransposeLaneOfst( UnifiedRDFHandler &handler, TranspositionMode mode, int32_t bpp, )#

Calculate the lane offset for transposition load.

Parameters:

handler – Reference to the UnifiedRDFHandler object
mode – The transposition mode.
bpp – The number of bytes per pixel.

Returns:

The lane offset

inline int32_t cupvaTransposeLaneOfst( RasterDataFlowHandler &handler, TranspositionMode mode, int32_t bpp, )#

Calculate the lane offset for transposition load.

Parameters:

handler – The reference to the RasterDataFlowHandler object defined in the VMEM
mode – The transposition mode.
bpp – The number of bytes per pixel.

Returns:

The lane offset