SequenceDataFlowTransfer#

Fully qualified name: cupva::SequenceDataFlowTransfer

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

class SequenceDataFlowTransfer#

Represents a transfer within a SequenceDataFlow.

SequenceDataFlowTransfer is used to configure the transfers within SequenceDataFlow prior to submission. Some of these configuration parameters may be reconfigured on the device during runtime, refer to device side API documentation of SequenceDataFlow for more information.

SequenceDataFlowTransfer is a wrapper for an object owned by a SequenceDataFlow. SequenceDataFlowTransfer should be initialized from cupva::SequenceDataFlow::addTransfer(). SequenceDataFlowTransfers are owned by SequenceDataFlow objects and become invalid when the owning SequenceDataFlow is destroyed.

SequenceDataFlowTransfer may be moved or copied, however this is always a shallow operation which simply copies an internal pointer. To do a deep copy of SequenceDataFlowTransfer, use the copy() method.

Public Functions

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

Set tile size.

A “dummy” transfer can be declared by simply not calling the tile() API or setting both width and height arguments to 0. User may find “dummy” transfers useful for conditionally enabling SequenceDataFlowTransfers in device code.

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 bytes, 0 < width < 65536

  • height – The height of the tile in rows of width, 0 < height < 65536

Throws:

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

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

Returns:

SequenceDataFlowTransfer& The reference to current object.

SequenceDataFlowTransfer &src(
const void *const ptr,
int32_t const linePitch,
)#

Set source buffer.

A CUPVA device pointer (DRAM, SRAM or VMEM-typed) is accepted. The pointer provided to this API may be reconfigured in device code each time the SequenceDataFlow is executed.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

  • ptr – A device pointer to the source for this transfer.

  • linePitch – The source buffer line pitch in bytes.

Throws:

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

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

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

Returns:

SequenceDataFlowTransfer& The reference to current object.

SequenceDataFlowTransfer &src(
OffsetPointer<void const> const op,
int32_t const linePitch,
)#

Set source buffer with OffsetPointer.

A CUPVA device pointer (DRAM, SRAM or VMEM-typed) is accepted. The pointer provided to this API may be reconfigured in device code each time the SequenceDataFlow is executed.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

  • op – An OffsetPointer to the source buffer.

  • linePitch – The source buffer line pitch in bytes.

Throws:

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

  • cupva::Exception(InvalidArgument) – sizeof(T) is not supported

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

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

Returns:

SequenceDataFlowTransfer& The reference to current object.

SequenceDataFlowTransfer &srcDim1(
int32_t const niter,
int32_t const adv,
)#

Set source 1st dimension traversal.

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

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 src 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 bytes) of each iteration

Throws:
Returns:

SequenceDataFlowTransfer& The reference to current object

SequenceDataFlowTransfer &srcDim2(
int32_t const niter,
int32_t const adv,
)#

Set source 2nd dimension traversal.

The 2nd dimension will increment 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 adv.

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 src 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 bytes) of each iteration

Throws:
Returns:

SequenceDataFlowTransfer& The reference to current object

SequenceDataFlowTransfer &srcDim3(
int32_t const niter,
int32_t const adv,
)#

Set source 3rd dimension traversal.

The 3rd dimension increments 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 adv.

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 src 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 bytes) of each iteration

Throws:
Returns:

SequenceDataFlowTransfer& The reference to current object

SequenceDataFlowTransfer &dst(
void *const ptr,
int32_t const linePitch,
)#

Set destination buffer.

A CUPVA device pointer (DRAM, SRAM or VMEM-typed) is accepted. The pointer provided to this API may be reconfigured in device code each time the SequenceDataFlow is executed.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

  • ptr – A device pointer to the destination for this transfer.

  • linePitch – The destination buffer line pitch in bytes.

Throws:

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

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

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

Returns:

SequenceDataFlowTransfer& The reference to current object.

SequenceDataFlowTransfer &dst(
OffsetPointer<void> const op,
int32_t const linePitch,
)#

Set destination buffer with OffsetPointer.

A CUPVA device pointer (DRAM, SRAM or VMEM-typed) is accepted. The pointer provided to this API may be reconfigured in device code each time the SequenceDataFlow is executed.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

  • op – An OffsetPointer to the destination buffer.

  • linePitch – The destination buffer line pitch in bytes.

Throws:

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

  • cupva::Exception(InvalidArgument) – sizeof(T) is not supported

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

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

Returns:

SequenceDataFlowTransfer& The reference to current object.

SequenceDataFlowTransfer &dstDim1(
int32_t const niter,
int32_t const adv,
)#

Set destination 1st dimension traversal.

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

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 bytes) of each iteration

Throws:
Returns:

SequenceDataFlowTransfer& The reference to current object

SequenceDataFlowTransfer &dstDim2(
int32_t const niter,
int32_t const adv,
)#

Set destination 2nd dimension traversal.

The 2nd dimension will increment 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 adv.

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 bytes) of each iteration

Throws:
Returns:

SequenceDataFlowTransfer& The reference to current object

SequenceDataFlowTransfer &dstDim3(
int32_t const niter,
int32_t const adv,
)#

Set destination 3rd dimension traversal.

The 3rd dimension increments 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 adv.

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 bytes) of each iteration

Throws:
Returns:

SequenceDataFlowTransfer& The reference to current object

SequenceDataFlowTransfer &mode(TransferModeType const mode)#

Set mode for the transfer.

Refer to cupva::TransferModeType for details. Defaults to cupva::TransferModeType::CONTINUOUS if not specified.

Transfers which do not target VMEM as either src or dst must use cupva::TransferModeType::CONTINUOUS

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

mode – The transfer mode

Throws:

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

Returns:

SequenceDataFlowTransfer& The reference to current object

SequenceDataFlowTransfer &copy(SequenceDataFlowTransfer const other)#

Deep copy of all parameters from another SequenceDataFlowTransfer.

Special member functions on SequenceDataFlowTransfer are shallow, i.e. copies will refer to the same underlying object. This API can be used to instead duplicate user specified configuration from another SequenceDataFlowTransfer.

The SequenceDataFlowTransfer must belong to the same cupva::Context. This is always true if the owning SequenceDataFlow is the same, or the CmdProgram which owns the SequenceDataFlows is the same.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

other – The SequenceDataFlowTransfer whose parameters we should duplicate.

Throws:

cupva::Exception(InvalidArgument) – The SequenceDataFlowTransfers belong to different cupva::Context objects.

Returns:

SequenceDataFlowTransfer& The reference to current object.