GatherScatterDataFlow API#

GatherScatterDataFlow Device APIs.

Macros#

GSDF_SURFACE_MIN_TILEBUFFER_SIZE: Minimum required total tile buffer size (in pixels) required to support reads from surfaces.
GSDF_SURFACE_MIN_TILE_HEIGHT: Minimum height per tile (in pixels) required to support reads from surfaces.
GSDF_SURFACE_MIN_TILE_PITCH: Minimum line pitch per tile (in pixels) required to support reads from surfaces.
GSDF_SURFACE_MIN_TILE_STRIDE: Minimum stride between tiles (in pixels) required to support reads from surfaces.
GSDF_SURFACE_TILE_OFFSET: Starting offset (in pixels) to the top left corner of the first tile.
GSDF_UNIFORM: GSDF uniform mode.
VMEM_GSDF_HANDLER: Declare GSDF handler in VMEM.

Functions#

void cupvaGSDFClose(GSDFHandler *handler): Close GatherScatterDataFlow.
void cupvaGSDFClose(GSDFHandlerUniform *handler): Close GatherScatterDataFlow.
void cupvaGSDFCycleBuffers(GSDFHandler *handler): Cycle active config buffer.
void cupvaGSDFCycleBuffers(GSDFHandlerUniform *handler): Cycle active config buffer.
bool cupvaGSDFOpen(GSDFHandler *handler, void *addr, uint16_t linePitch, uint32_t stride): Initialize GatherScatterDataFlow.
bool cupvaGSDFOpen(GSDFHandlerUniform *handler, void *addr, uint16_t linePitch, uint32_t stride): Initialize GatherScatterDataFlow declared as uniform.
bool cupvaGSDFResetExtBase(GSDFHandlerUniform *handler, ExtMemPointer const *addr, uint16_t width, uint16_t height, uint16_t linePitch): Reset the base address to an external pointer.
bool cupvaGSDFResetExtBase(GSDFHandlerUniform *handler, ExtMemPointer const *addr, PlanarGeometry *geometry): Reset the base address to an external pointer for multi-planar use cases.
bool cupvaGSDFResetExtBase(GSDFHandler *handler, ExtMemPointer const *addr, uint16_t width, uint16_t height, uint16_t linePitch): Reset the base address to an external pointer.
bool cupvaGSDFResetExtBase(GSDFHandler *handler, ExtMemPointer const *addr, PlanarGeometry const *geom): Reset the base address to an external pointer for multi-planar use cases.
bool cupvaGSDFResetExtBase(GSDFHandler *handler, VPUSurfaceData const *surfObj): Reset the base address to an external surface.
bool cupvaGSDFResetExtBase(GSDFHandler *handler, VPUSurfaceData const *surfObj, PlanarGeometry const *geom): Reset the base address to an external surface.
void cupvaGSDFSync(GSDFHandlerUniform *handler): Wait for a GatherScatterDataFlow to complete.
void cupvaGSDFSync(GSDFHandler *handler): Wait for a GatherScatterDataFlow to complete.
void cupvaGSDFTrig(GSDFHandler *handler): Trigger GatherScatterDataFlow.
void cupvaGSDFTrig(GSDFHandlerUniform *handler): Trigger GatherScatterDataFlow.
void cupvaGSDFUpdateOffsets1D(GSDFHandler *handler, int32_t const *offsets): Set the offsets from external base address to tiles.
void cupvaGSDFUpdateOffsets1D(GSDFHandlerUniform *handler, int32_t const *offsets): Update the offsets to tiles.
void cupvaGSDFUpdateOffsets2D(GSDFHandlerUniform *handler, int32_t const *xCoords, int32_t const *yCoords): Set the 2D offsets from external base address to tiles.
void cupvaGSDFUpdateOffsets2D(GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords): Set the 2D offsets from external base address to tiles.
void cupvaGSDFUpdatePlaneIndices(GSDFHandler *handler, uint8_t const *planeIndices, int32_t size): Update the plane indices storing in the handler.
void cupvaGSDFUpdatePlaneIndices(GSDFHandlerUniform *handler, uint8_t const *planeIndices): Update the pointer to an array storing the plane indices, which will be used for the next GSDF transfer.
void cupvaGSDFUpdateSize1D(GSDFHandler *handler, uint16_t const *transferSizes, int32_t size): Update the transfer sizes for single dim transfers.
void cupvaGSDFUpdateSize1D(GSDFHandler *handler, uint16_t transferSize, int32_t size): Broadcast transfer size to all tiles.
void cupvaGSDFUpdateSize1D(GSDFHandlerUniform *handler, uint16_t transferSize): Broadcast transfer size to all tiles.
void cupvaGSDFUpdateSize2D(GSDFHandler *handler, uint16_t tx, uint16_t ty, int32_t size): Broadcast tile dimension update to all tiles.
void cupvaGSDFUpdateSize2D(GSDFHandlerUniform *handler, uint16_t tx, uint16_t ty): Broadcast tile dimension update to all tiles.
void cupvaGSDFUpdateSize2D(GSDFHandler *handler, uint16_t const *tx, uint16_t const *ty, int32_t size): Update the tile dimensions.
void cupvaGSDFUpdateTiles(GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, int32_t size): Update tiles for 2D access with no change to tile size.
void cupvaGSDFUpdateTiles(GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, uint16_t const tx, uint16_t const ty, int32_t size): Update tiles for 2D access with tile size broadcast.
void cupvaGSDFUpdateTiles(GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, uint16_t const *tx, uint16_t const *ty, int32_t size): Update tiles for 2D access.
void cupvaGSDFUpdateTilesWithOffsets(GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, int32_t const *offsets, uint16_t const tx, uint16_t const ty, int32_t size): Update tiles for 2D access with planar offsets and tile size broadcast.
void cupvaGSDFUpdateTilesWithOffsets(GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, int32_t const *offsets, int32_t size): Update tiles for 2D access with planar offsets and no change to tile size.
void cupvaGSDFUpdateTilesWithOffsets(GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, int32_t const *offsets, uint16_t const *tx, uint16_t const *ty, int32_t size): Update tiles for 2D access with planar offsets.
void cupvaGSDFUpdateVmemAddr(GSDFHandler *handler, void *addr, uint16_t linePitch, uint32_t stride): Update the VMEM tile buffer.
void cupvaGSDFUpdateVmemAddr(GSDFHandlerUniform *handler, void *addr, uint16_t linePitch, uint32_t stride): Update the address and layout of the VMEM buffer.

Data Structures#

GSDFHandler: GatherScatterDataFlow handler.
GSDFHandlerUniform: GatherScatterDataFlow uniform handler.
PlanarGeometry: Structure to hold geometry information of a a multi-planar buffer.

Functions#

inline void cupvaGSDFClose(GSDFHandler *handler)#

Close GatherScatterDataFlow.

Must be called once before the kernel exits. No further API calls may be made after closing the GSDF.

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 pointer to GatherScatterDataFlow handler

inline void cupvaGSDFClose(GSDFHandlerUniform *handler)#

Close GatherScatterDataFlow.

Overload of cupvaGSDFClose for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler

inline void cupvaGSDFCycleBuffers(GSDFHandler *handler)#

Cycle active config buffer.

GSDF supports two configuration buffers which are independent. This means that calling a cupvaGSDFUpdate* API or cupvaGSDFResetExtBase() will only take effect on the currently active configuration buffer. All parameters set on the host or specified to cupvaGSDFOpen() are broadcast to both buffers during initialization.

Buffers are cycled by calling cupvaGSDFTrig(). However, if user wishes to configure the state of a buffer manually without transferring data, this API may be used.

For example, if user is processing data in a ping-pong fashions such that each set of data ends up in a different VMEM location, they might wish to pre-configure the config buffers at the start of their kernel. In such a case, the call sequence below may be used:

cupvaGSDFOpen with the ping VMEM buffer
cupvaGSDFCycleBuffers to make the pong buffer active
cupvaGSDFUpdateVmemAddr with the pong VMEM buffer
cupvaGSDFCycleBuffers to reset back to the ping buffer

This API shall be called only when GSDF is idle.

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 pointer to GatherScatterDataFlow handler

inline void cupvaGSDFCycleBuffers(GSDFHandlerUniform *handler)#

Cycle active config buffer.

Overload of cupvaGSDFCycleBuffers for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler

inline bool cupvaGSDFOpen( GSDFHandler *handler, void *addr, uint16_t linePitch, uint32_t stride, )#

Initialize GatherScatterDataFlow.

This API must be called before invoking any other methods on the GSDF.

User must specify a VMEM buffer when opening the GSDF. See cupvaGSDFUpdateVmemAddr() for more information.

GSDF supports two independent configuration buffers which may be cycled with cupvaGSDFCycleBuffers. This API will initialize both of these buffers using the parameters specified by the user in host code as well as the addr, linePitch and stride parameters.

If the user specified a surface as the external buffer, the GSDF will be opened in surface mode. Otherwise, it will be opened in raw pointer mode. The mode will be broadcast to both buffers without needing to call cupvaGSDFCycleBuffers(). See cupvaGSDFResetExtBase() for more details.

This API will perform bounds checking of the external buffer dimensions and return false if the dimensions exceed the bounds of the external allocation.

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 pointer to GatherScatterDataFlow handler
addr – The address of VMEM buffer. Refer cupvaGSDFUpdateVmemAddr()
linePitch – The line pitch of VMEM buffer. Refer cupvaGSDFUpdateVmemAddr()
stride – The stride of VMEM buffer. Refer cupvaGSDFUpdateVmemAddr()

Returns:

The flag to indicate whether parameters in GSDFHandler are valids.

inline bool cupvaGSDFOpen( GSDFHandlerUniform *handler, void *addr, uint16_t linePitch, uint32_t stride, )#

Initialize GatherScatterDataFlow declared as uniform.

Overload of cupvaGSDFOpen for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler
addr – The address of VMEM buffer. Refer cupvaGSDFUpdateVmemAddr()
linePitch – The line pitch of VMEM buffer. Refer cupvaGSDFUpdateVmemAddr()
stride – The stride of VMEM buffer. Refer cupvaGSDFUpdateVmemAddr()

Returns:

The flag to indicate whether parameters in GSDFHandler are valids.

inline bool cupvaGSDFResetExtBase( GSDFHandlerUniform *handler, ExtMemPointer const *addr, uint16_t width, uint16_t height, uint16_t linePitch, )#

Reset the base address to an external pointer.

Overload of cupvaGSDFResetExtBase for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler
addr – The pointer to an ExtMemPointer object
width – The width of the external surface that addr points to
height – The height of the external surface
linePitch – The line pitch of the external surface

Returns:

true if the API was successful, false otherwise

inline bool cupvaGSDFResetExtBase( GSDFHandlerUniform *handler, ExtMemPointer const *addr, PlanarGeometry *geometry, )#

Reset the base address to an external pointer for multi-planar use cases.

Overload of cupvaGSDFResetExtBase for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler
addr – The pointer to an ExtMemPointer object
geometry – The pointer to an PlanarGeometry object

Returns:

true if the API was successful, false otherwise

inline bool cupvaGSDFResetExtBase( GSDFHandler *handler, ExtMemPointer const *addr, uint16_t width, uint16_t height, uint16_t linePitch, )#

Reset the base address to an external pointer.

This API resets the external base pointer for the currently active buffer. Upon calling this API, the following will take place:

Any external offsets or coordinates specified by the user via any method will be reset to zero. All tiles will point to the top left corner of addr.
All padding will be reset to zero.
The currently active buffer will be put into raw pointer mode. In this mode, data will be available starting at the address specified in cupvaGSDFUpdateVmemAddr() or cupvaGSDFOpen(). Refer cupvaGSDFOpen() for more information.
Future calls to the GSDF when the current buffer is active will use the new external address.

GSDF supports two buffers containing separate configurations. Each time the GSDF is triggered, the next configuration becomes active. Calling this API on one of the buffers does not affect the other buffer.

This API will return false and have no effect if the geometry specified by width, height and linePitch exceeds the bounds of the buffer referred to by addr.

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 pointer to GatherScatterDataFlow handler
addr – The pointer to an ExtMemPointer object
width – The width of the external surface that addr points to
height – The height of the external surface
linePitch – The line pitch of the external surface

Returns:

true if the API was successful, false otherwise

inline bool cupvaGSDFResetExtBase( GSDFHandler *handler, ExtMemPointer const *addr, PlanarGeometry const *geom, )#

Reset the base address to an external pointer for multi-planar use cases.

This API resets the external base pointer for the currently active buffer. Upon calling this API, the following will take place:

Any external offsets or coordinates specified by the user via any method will be reset to zero. All plane geometry will be updated with the provided geom. All tiles will point to the top left corner of planes that the tiles reside.
All padding will be reset to zero.
The currently active buffer will be put into raw pointer mode. In this mode, data will be available starting at the address specified in cupvaGSDFUpdateVmemAddr() or cupvaGSDFOpen(). Refer cupvaGSDFOpen() for more information.
Future calls to the GSDF when the current buffer is active will use the new external address.

If user doesn’t specify allow Non-inform line pitch through host API cupva::GatherScatterDataFlow::bufferType. The line pitch for each plane in the PlanarGeometry must be filled with the same value. Violation of this requirement will lead to undefined behavior.

GSDF supports two buffers containing separate configurations. Each time the GSDF is triggered, the next configuration becomes active. Calling this API on one of the buffers does not affect the other buffer.

This API will return false and have no effect if the geometry specified by geom->widths, geom->heights and geom->linePitches exceeds the bounds of the buffer referred to by addr.

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 pointer to GatherScatterDataFlow handler
addr – The pointer to an ExtMemPointer object
geom – The pointer to a PlanarGeometry object

Returns:

true if the API was successful, false otherwise

inline bool cupvaGSDFResetExtBase( GSDFHandler *handler, VPUSurfaceData const *surfObj, )#

Reset the base address to an external surface.

This API resets the external surface for the currently active buffer. Upon calling this API, the following will take place:

Any external offsets or coordinates specified by the user via any method will be reset to zero. All tiles will point to the top left corner of surfObj.
The currently active buffer will be put into surface mode. In this mode, data will be available from an offset within the tile buffer specified in cupvaGSDFUpdateVmemAddr() or cupvaGSDFOpen(). The tile buffer must be contain extra space for surface alignment. Refer cupvaGSDFUpdateVmemAddr() for more information.
Future calls to the GSDF when the current buffer is active will use the new external address.

This API may only be used in the following cases:

A surface must have been specified as either src or dst in host APIs.
If an OffsetPointer was used, the bufferType() API must have been called to specify a surface buffer type.
This API must be targeting the start of a plane in the surface passed to the host APIs, or a plane in a surface allocated with the exact same parameters as the surface specified to host APIs. In the case of surfaces allocated with NvSciBuf, this means all engines and all parameters must be identical between the allocations.

Violation of (1) or (2) will result in this API returning false. Violation of (3) results in undefined behavior.

GSDF supports two buffers containing separate configurations. Each time the GSDF is triggered, the next configuration becomes active. Calling this API on one of the buffers does not affect the other buffer.

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 pointer to GatherScatterDataFlow handler
surfObj – VPUSurfaceData object representing the start of a plane within a surface allocation

Returns:

true if successful, false otherwise

inline bool cupvaGSDFResetExtBase( GSDFHandler *handler, VPUSurfaceData const *surfObj, PlanarGeometry const *geom, )#

Reset the base address to an external surface.

This API resets the external surface for the currently active buffer. Upon calling this API, the following will take place:

Any external offsets or coordinates specified by the user via any method will be reset to zero. All plane geometry will be updated with the provided geom. All tiles will point to the top left corner of planes that the tiles reside.
The currently active buffer will be put into surface mode. In this mode, data will be available from an offset within the tile buffer specified in cupvaGSDFUpdateVmemAddr() or cupvaGSDFOpen(). The tile buffer must be contain extra space for surface alignment. Refer cupvaGSDFUpdateVmemAddr() for more information.
Future calls to the GSDF when the current buffer is active will use the new external address.

This API may only be used in the following cases:

A surface must have been specified as either src or dst in host APIs.
If an OffsetPointer was used, the bufferType() API must have been called to specify a surface buffer type.
This API must be targeting the base of the surface passed to surfObj.

Violation of (1) or (2) will result in this API returning false. Violation of (3) results in undefined behavior.

GSDF supports two buffers containing separate configurations. Each time the GSDF is triggered, the next configuration becomes active. Calling this API on one of the buffers does not affect the other buffer.

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 pointer to GatherScatterDataFlow handler
surfObj – VPUSurfaceData object passed from host APIs
geom – The pointer to a PlanarGeometry object describing the geometry of the surface

Returns:

true if successful, false otherwise

inline void cupvaGSDFSync(GSDFHandlerUniform *handler)#

Wait for a GatherScatterDataFlow to complete.

Overload of cupvaGSDFSync for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler

inline void cupvaGSDFSync(GSDFHandler *handler)#

Wait for a GatherScatterDataFlow to complete.

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 pointer to GatherScatterDataFlow handler

inline void cupvaGSDFTrig(GSDFHandler *handler)#

Trigger GatherScatterDataFlow.

This API flushes the data in the current active internal buffer to hardware and triggers the current transfer, then cycles to the next buffer. This allows update APIs to be immediately called without affecting the transfers in-flight. User may update dataflow info for the next DMA transfer without the need to wait for the current transfer to complete.

User needs to ensure that only one trigger per GSDF is active at a time, which means that user must call cupvaGSDFSync() before calling this trigger API again.

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 pointer to GatherScatterDataFlow handler

inline void cupvaGSDFTrig(GSDFHandlerUniform *handler)#

Trigger GatherScatterDataFlow.

Overload of cupvaGSDFTrig for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler

inline void cupvaGSDFUpdateOffsets1D( GSDFHandler *handler, int32_t const *offsets, )#

Set the offsets from external base address to tiles.

The API may be used to specify offsets to tiles in 1D.

GSDF gathers/scatters multiple tiles at offsets from a single external base. This API is used to specify the offsets on a per-tile basis. The index within offsets corresponds to the tile idx, for example offsets[4] specifies the offset for the 5th tile in VMEM.

This API must not be called when the current GSDF buffer is in surface mode.

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 pointer to GatherScatterDataFlow handler
offsets – The pointer to an array of offsets (in pixel). Must contain at least as many elements as number of tiles specified in host code.

inline void cupvaGSDFUpdateOffsets1D( GSDFHandlerUniform *handler, int32_t const *offsets, )#

Update the offsets to tiles.

Overload of cupvaGSDFUpdateOffsets1D for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler
offsets – The pointer to an array of offsets (in pixel). Must contain at least as many elements as number of tiles specified in host code.

inline void cupvaGSDFUpdateOffsets2D( GSDFHandlerUniform *handler, int32_t const *xCoords, int32_t const *yCoords, )#

Set the 2D offsets from external base address to tiles.

Overload of cupvaGSDFUpdateOffsets2D for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler
xCoords – The pointer to the array of X coordinates in pixels. Must contain at least as many elements as number of tiles specified in host code.
yCoords – The pointer to the array of Y coordinates in pixels. Must contain at least as many elements as number of tiles specified in host code.

inline void cupvaGSDFUpdateOffsets2D( GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, )#

Set the 2D offsets from external base address to tiles.

The API may be used to specify offsets to tiles in 2D.

GSDF gathers/scatters multiple tiles at offsets from a single external base. This API is used to specify the offsets on a per-tile basis. The index within offsets corresponds to the tile idx, for example offsets[4] specifies the offset for the 5th tile in VMEM.

For reads to VMEM, this API doesn’t apply paddings for the tiles that have out-of-bounds accesses. Please use cupvaGSDFUpdateTiles() if you want out-of-bounds pixels to be replaced by padding.

When writing from VMEM to an external surface, xCoords must be aligned to 32bytes and yCoords must be aligned to 2.

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 pointer to GatherScatterDataFlow handler
xCoords – The pointer to the array of X coordinates in pixels. Must contain at least as many elements as number of tiles specified in host code.
yCoords – The pointer to the array of Y coordinates in pixels. Must contain at least as many elements as number of tiles specified in host code.

inline void cupvaGSDFUpdatePlaneIndices( GSDFHandler *handler, uint8_t const *planeIndices, int32_t size, )#

Update the plane indices storing in the handler.

To support multi-planar transfers, the plane indices array must be used in conjunction with the tile coordinates arrays passed to other cupvaGSDFUpdate* APIs, such as cupvaGSDFUpdateTiles and cupvaGSDFUpdateOffsets2D. The plane index is used to look up the fields of PlanarGeometry provided to cupvaGSDFResetExtBase. This allows the correct offset and plane bounds to be applied when configuring each transfer. The plane indices array applies globally, unlike other cupvaGSDFUpdate* APIs which operate on the the currently active GSDF configuration buffer only (see cupvaGSDFCycleBuffers for more details). Calling cupvaGSDFUpdatePlaneIndices alone is insufficient to modify the active GSDF configuration buffer. Any time plane indices are modified, a subsequent call to another cupvaGSDFUpdate* API is required for the new plane indices to take effect on the active buffer.

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 pointer to GatherScatterDataFlow handler
planeIndices – The pointer to an array storing plane indices. Each value in planeIndices corresponds to an index to the array of PlanarGeometry passed to cupvaGSDFResetExtBase(), and must be between 0 and number of planes - 1.
size – The size of the arrays. Tiles past the end of the arrays will be predicated off, resulting in no data transferred. Must respect 0 < size <= most recent size configured for the currently cycled buffer. To increase the size after calling this API, users shall call the APIs accepting both size and tile dimensions parameters.

inline void cupvaGSDFUpdatePlaneIndices( GSDFHandlerUniform *handler, uint8_t const *planeIndices, )#

Update the pointer to an array storing the plane indices, which will be used for the next GSDF transfer.

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 pointer to GatherScatterDataFlow handler
planeIndices – The pointer to an array storing plane indices.

inline void cupvaGSDFUpdateSize1D( GSDFHandler *handler, uint16_t const *transferSizes, int32_t size, )#

Update the transfer sizes for single dim transfers.

This API may be used to update transfer dimensions. Transfers of size zero are considered ‘dummy’ transfers which will not result in any data access. The size parameter can be used as a convenience to pass arrays which are smaller than the total number of tiles in the GSDF and to disable data transfer for all tiles with index >= size.

Using this API is identical to calling cupvaGSDFUpdateSize2D with ty=1.

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

Parameters:

handler – Pointer to GatherScatterDataFlow handler
transferSizes – Pointer to an array of transfer sizes in pixels. Must contain at least size elements. Elements in the array must be greater than 0.
size – Number of valid tiles. Tiles past the end will be predicated off, resulting in no data transferred. Must respect 0 < size <= maximum number of tiles used when configuring the GSDF in host APIs.

inline void cupvaGSDFUpdateSize1D( GSDFHandler *handler, uint16_t transferSize, int32_t size, )#

Broadcast transfer size to all tiles.

Overload for cupvaGSDFUpdateSize1D where user wishes to broadcast transfer size to all tiles in the GSDF.

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 pointer to GatherScatterDataFlow handler
transferSize – The transfer size in pixels
size – Number of valid tiles. Tiles greater than this will be predicated off, resulting in no data transferred. Must respect 0 < size <= maximum number of tiles used when configuring the GSDF in host APIs.

inline void cupvaGSDFUpdateSize1D( GSDFHandlerUniform *handler, uint16_t transferSize, )#

Broadcast transfer size to all tiles.

Overload for cupvaGSDFUpdateSize1D for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler
transferSize – The transfer size in pixels

inline void cupvaGSDFUpdateSize2D( GSDFHandler *handler, uint16_t tx, uint16_t ty, int32_t size, )#

Broadcast tile dimension update to all tiles.

Overload for cupvaGSDFUpdateSize2D where user wishes to broadcast tx and ty to all tiles in the GSDF.

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 pointer to GatherScatterDataFlow handler
tx – The 2D tile widths in pixels. Must be greater than 0.
ty – The 2D tile heights in pixels. Must be greater than 0.
size – Number of valid tiles. Tiles greater than this will be predicated off, resulting in no data transferred. Must respect 0 < size <= maximum number of tiles used when configuring the GSDF in host APIs.

inline void cupvaGSDFUpdateSize2D( GSDFHandlerUniform *handler, uint16_t tx, uint16_t ty, )#

Broadcast tile dimension update to all tiles.

Overload of cupvaGSDFUpdateSize2D for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler
tx – The 2D tile widths in pixels
ty – The 2D tile heights in pixels

inline void cupvaGSDFUpdateSize2D( GSDFHandler *handler, uint16_t const *tx, uint16_t const *ty, int32_t size, )#

Update the tile dimensions.

This API may be used to update tile dimensions. Tiles which have both tx=ty=0 are considered ‘dummy’ transfers which will not result in any data access. The size parameter can be used as a convenience to pass arrays which are smaller than the total number of tiles in the GSDF and to disable data transfer for all tiles with index >= size.

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

Parameters:

handler – Pointer to GatherScatterDataFlow handler
tx – Pointer to an array of 2D tile widths in pixels. Must contain at least size elements and elements must be greater than 0.
ty – Pointer to an array of 2D tile heights in pixels. Must contain at least size elements and elements must be greater than 0.
size – Number of valid tiles. Tiles greater than this will be predicated off, resulting in no data transferred. Must respect 0 < size <= maximum number of tiles used when configuring the GSDF in host APIs.

inline void cupvaGSDFUpdateTiles( GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, int32_t size, )#

Update tiles for 2D access with no change to tile size.

Overload for cupvaGSDFUpdateTiles for cases where tile width/height are not explicitly modified. Despite this, the size parameter will still cause tiles past the end of the arrays to be predicated off, resulting in no data transferred.

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

Parameters:

handler – Pointer to GatherScatterDataFlow handler
xCoords – Pointer to an array of X coordinates in pixels. Must contain at least size elements.
yCoords – Pointer to an array of Y coordinates in pixels. Must contain at least size elements.
size – The size of the arrays. Tiles past the end of the arrays will be predicated off, resulting in no data transferred. Must respect 0 < size <= most recent size configured for the currently cycled buffer. To increase the size after calling this API, users shall call the APIs accepting both size and tile dimensions parameters.

inline void cupvaGSDFUpdateTiles( GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, uint16_t const tx, uint16_t const ty, int32_t size, )#

Update tiles for 2D access with tile size broadcast.

Overload for cupvaGSDFUpdateTiles for cases where tile width/height may be broadcast.

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

Parameters:

handler – Pointer to GatherScatterDataFlow handler
xCoords – Pointer to an array of X coordinates in pixels. Must contain at least size elements.
yCoords – Pointer to an array of Y coordinates in pixels. Must contain at least size elements.
tx – Tile width in pixels. Must be greater than 0.
ty – Tile height in pixels. Must be greater than 0.
size – The size of the arrays. Tiles past the end of the arrays will be predicated off, resulting in no data transferred. Must respect 0 < size <= maximum number of tiles used when configuring the GSDF in host APIs.

inline void cupvaGSDFUpdateTiles( GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, uint16_t const *tx, uint16_t const *ty, int32_t size, )#

Update tiles for 2D access.

This API shall be used for accessing 2D tiles in a 2D image. The external 2D image attributes are provided by the user either during host configuration or during a call to cupvaGSDFResetExtBase.

When reading to VMEM, out of bounds pixels will be replaced by padding. For reads to VMEM, this API will do the following:

Clamp the provided coordinates such that:
- At least one pixel in the tile comes from the external memory, and
- No more than 255 pixels of padding is needed in either x or y dimensions
Apply padding so that any accesses out of the image bounds are instead filled with either constant values or pixel extension, depending on the users election in host code.

When writing from VMEM, no clamping or padding will be done. The user must ensure that all parameters specified result in writes within valid boundaries of the external allocation. When writing from VMEM to an external surface, each of xCoords must be aligned to 32 bytes and each of yCoords must be aligned to 2. For example, with 2 byte pixels, the coordinates x = 16, y = 10 are appropriately aligned for a surface write.

For both reads and writes, this API will predicate off any tiles past those specified by size. This will result in no data transferred for such tiles.

Any call to cupvaGSDFResetExtBase for the currently cycled buffer will invalidate previous calls to this API.

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

Parameters:

handler – Pointer to GatherScatterDataFlow handler
xCoords – Pointer to an array of X coordinates in pixels. Must contain at least size elements.
yCoords – Pointer to an array of Y coordinates in pixels. Must contain at least size elements.
tx – Pointer to an array of 2D tile widths in pixels. Must contain at least size elements and elements must be greater than 0.
ty – Pointer to an array of 2D tile heights in pixels. Must contain at least size elements and elements must be greater than 0.
size – The size of the arrays. Tiles past the end of the arrays will be predicated off, resulting in no data transferred. Must respect 0 < size <= maximum number of tiles used when configuring the GSDF in host APIs.

inline void cupvaGSDFUpdateTilesWithOffsets( GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, int32_t const *offsets, uint16_t const tx, uint16_t const ty, int32_t size, )#

Update tiles for 2D access with planar offsets and tile size broadcast.

Deprecated:: This API is deprecated. Use cupvaGSDFUpdatePlaneIndices() and cupvaGSDFResetExtBase() instead.

Overload for cupvaGSDFUpdateTilesWithOffsets for cases where tile width/height may be broadcast.

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

Parameters:

handler – Pointer to GatherScatterDataFlow handler
xCoords – Pointer to an array of X coordinates in pixels. Must contain at least size elements.
yCoords – Pointer to an array of Y coordinates in pixels. Must contain at least size elements.
offsets – Additional offset in pixels to apply to each tile. Must contain at least size elements.
tx – Tile width in pixels. Must be greater than 0.
ty – Tile height in pixels. Must be greater than 0.
size – The size of the arrays. Tiles past the end of the arrays will be predicated off, resulting in no data transferred. Must respect 0 < size <= maximum number of tiles used when configuring the GSDF in host APIs.

inline void cupvaGSDFUpdateTilesWithOffsets( GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, int32_t const *offsets, int32_t size, )#

Update tiles for 2D access with planar offsets and no change to tile size.

Deprecated:: This API is deprecated. Use cupvaGSDFUpdatePlaneIndices() and cupvaGSDFResetExtBase() instead.

Overload for cupvaGSDFUpdateTilesWithOffsets for cases where tile width/height are not explicitly modified. Despite this, the size parameter will still cause tiles past the end of the arrays to be predicated off, resulting in no data transferred.

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

Parameters:

handler – Pointer to GatherScatterDataFlow handler
xCoords – Pointer to an array of X coordinates in pixels. Must contain at least size elements.
yCoords – Pointer to an array of Y coordinates in pixels. Must contain at least size elements.
offsets – Additional offset in pixels to apply to each tile. Must contain at least size elements.
size – The size of the arrays. Tiles past the end of the arrays ill be predicated off, resulting in no data transferred. Must respect 0 < size <= most recent size configured for the currently cycled buffer. To increase the size after calling this API, users shall call the APIs accepting both size and tile dimensions parameters.

inline void cupvaGSDFUpdateTilesWithOffsets( GSDFHandler *handler, int32_t const *xCoords, int32_t const *yCoords, int32_t const *offsets, uint16_t const *tx, uint16_t const *ty, int32_t size, )#

Update tiles for 2D access with planar offsets.

Deprecated:: This API is deprecated. Use cupvaGSDFUpdatePlaneIndices() and cupvaGSDFResetExtBase() instead.

This API works identically to cupvaGSDFUpdateTiles, however it allow the user to specify offsets which will be applied to each tile after bounds calculations. Since offsets are applied after computing padding, this API may be used to access tiles from separate planes in the same allocation, provided each plane shares the same geometry.

When writing from VMEM to an external surface, each of offsets must be aligned to 64 bytes. For example, with 2 byte pixels, the offset 32 is appropriately aligned for a surface write. Typically though, this offset will be much larger and represent the stride between planes in a surface.

Any call to cupvaGSDFResetExtBase for the currently cycled buffer will invalidate previous calls to this API.

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

Parameters:

handler – Pointer to GatherScatterDataFlow handler
xCoords – Pointer to an array of X coordinates in pixels. Must contain at least size elements.
yCoords – Pointer to an array of Y coordinates in pixels. Must contain at least size elements.
offsets – Additional offset in pixels to apply to each tile. Must contain at least size elements.
tx – Pointer to an array of 2D tile widths in pixels. Must contain at least size elements and elements must be greater than 0.
ty – Pointer to an array of 2D tile heights in pixels. Must contain at least size elements and elements must be greater than 0.
size – The size of the arrays. Tiles past the end of the arrays will be predicated off, resulting in no data transferred. Must respect 0 < size <= maximum number of tiles used when configuring the GSDF in host APIs.

inline void cupvaGSDFUpdateVmemAddr( GSDFHandler *handler, void *addr, uint16_t linePitch, uint32_t stride, )#

Update the VMEM tile buffer.

GSDF will gather to/scatter from tiles in VMEM which have consistent line pitch and constant stride. These parameters are specified during cupvaGSDFOpen() and broadcasted to all buffers without user needing to call cupvaGSDFCycleBuffers(). This API updates the address, line pitch and stride for only the currently cycled buffer.

If the GSDF is in raw pointer mode, or in surface mode and writing from VMEM, user should ensure that linePitch is larger than the tile width and that stride is larger than linePitch multiplied by the tile height.

If the GSDF is in surface mode and reading to VMEM, GSDF needs a larger VMEM tile buffer due to alignment constraints. In this case, the tiles are aligned within the buffer as follows:

┌─────────────────────┐
│       Tile 1        │
│   ┌─────────────────┤
│   │                 │
│   │                 │
│   │ Valid tile data │
│   │                 │
│   │                 │
├───┴─────────────────┤
│       Tile 2        │
│   ┌─────────────────┤
│   │                 │
│   │                 │
│   │ Valid tile data │
│   │                 │
│   │                 │
├───┴─────────────────┤
│       Tile 3        │
│   ┌─────────────────┤
│   │                 │
│   │                 │
│   │ Valid tile data │
│   │                 │
│   │                 │
└───┴─────────────────┘

Certain minimum alignment and stride values must be met when reading from an external surface to VMEM. Users can use the following macros to determine these minimum values:

GSDF_SURFACE_MIN_TILE_PITCH as the minimum value to linePitch
GSDF_SURFACE_MIN_TILE_STRIDE as the minimum value to stride

Additionally, GSDF_SURFACE_TILE_OFFSET can be used to find the offset from addr to the top left corner of the first tile. Subsequent tiles will be placed at regular offsets from this first tile as specified at stride.

Typical GSDF calling sequence for reads from external surfaces:

Use GSDF_SURFACE_MIN_TILEBUFFER_SIZE macro to declare VMEM tile buffer.

VMEM(A, int16_t, buf_v, GSDF_SURFACE_MIN_TILEBUFFER_SIZE(int16_t, TILE_WIDTH, TILE_HEIGHT, NUM_TILES));

Call cupvaGSDFUpdateVmemAddr() or cupvaGSDFOpen() to set up the VMEM buffer. GSDF_SURFACE_MIN_TILE_PITCH and GSDF_SURFACE_MIN_TILE_STRIDE macros can to be used to ensure the minimum line pitch and stride for tile transfers.
```
cupvaGSDFUpdateVmemAddr(tbl_0_v, &buf_v[0], GSDF_SURFACE_MIN_TILE_PITCH(int16_t, PATCH_WIDTH),
                         GSDF_SURFACE_MIN_TILE_STRIDE(int16_t, PATCH_WIDTH, PATCH_HEIGHT));
```
Ensure that the GSDF is in surface mode by specifying a surface in host side APIs.
Call cupvaGSDFUpdateOffsets2D to configure the coordinates of the input tiles.
Trigger DMA transfer by calling cupvaGSDFTrig().
Wait for DMA transactions to complete using cupvaGSDFSync().
Use GSDF_SURFACE_TILE_OFFSET macro to get the starting address of valid data in the tile arena, and process the data.
```
int16_t addr = &buf_v[GSDF_SURFACE_TILE_OFFSET(int16_t, 0, PATCH_WIDTH)];
```

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 pointer to GatherScatterDataFlow handler
addr – The address of VMEM buffer
linePitch – The line pitch of VMEM buffer. See above for restrictions when reading in surface mode.
stride – The stride of VMEM buffer. See above for restrictions when reading in surface mode.

inline void cupvaGSDFUpdateVmemAddr( GSDFHandlerUniform *handler, void *addr, uint16_t linePitch, uint32_t stride, )#

Update the address and layout of the VMEM buffer.

Overload of cupvaGSDFUpdateVmemAddr for GSDF declared as uniform.

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 pointer to GatherScatterDataFlow handler
addr – The address of VMEM buffer
linePitch – The line pitch of VMEM buffer
stride – The stride of VMEM buffer