CUPVA_Stream_C

Detailed Description

Data Structures
struct	cupvaCmd_t
	Unit of work which may be submitted to the PVA engine. More...

Typedefs
typedef struct cupvaCmdBufferRec *	cupvaCmdBuffer_t
	A container for a set of commands. More...
typedef struct cupvaStreamRec *	cupvaStream_t
	Streams are used to submit PVA commands. More...
typedef struct cupvaCmdStatusRec *	cupvaCmdStatus_t
	Status output resulting from a submission. More...

Enumerations
enum	cupvaOrderType_t {   CUPVA_ORDER_TYPE_INVALID = 0,   CUPVA_IN_ORDER,   CUPVA_OUT_OF_ORDER,   CUPVA_ORDER_TYPE_MAX }
	Specifies scheduling and execution order for the commands submitted to the Stream. More...
enum	cupvaEngineType_t {   CUPVA_ENGINE_TYPE_INVALID = 0,   CUPVA_PVA0,   CUPVA_PVA1,   CUPVA_ENGINE_TYPE_MAX }
	Specifies PVA Engine ID for a Stream. More...
enum	cupvaAffinityType_t {   CUPVA_AFFINITY_TYPE_INVALID = 0,   CUPVA_VPU0,   CUPVA_VPU1,   CUPVA_VPU_ANY,   CUPVA_AFFINITY_TYPE_MAX }
	Specifies VPU affinity for a Stream. More...

Functions
DLL_EXPORT cupvaError_t	CupvaStreamCreate (cupvaStream_t *const stream, cupvaEngineType_t const absEngine, cupvaAffinityType_t const vpuAffinity)
	Create a new Stream object. More...
DLL_EXPORT cupvaError_t	CupvaStreamDestroy (cupvaStream_t const stream)
	Destroy a stream object. More...
DLL_EXPORT cupvaError_t	CupvaStreamSubmit (cupvaStream_t const stream, cupvaCmd_t const *const *const command, cupvaCmdStatus_t *const status, int32_t const count, cupvaOrderType_t const order, int32_t const executionTimeout, int32_t const submitTimeout)
	Submit a batch of Commands to the Stream. More...
DLL_EXPORT cupvaError_t	CupvaStreamSubmitCmdBuffer (cupvaStream_t const stream, cupvaCmdBuffer_t const cmdBuffer, int32_t const executionTimeout, int32_t const submitTimeout)
	Submit cupvaCmdBuffer_t to the stream. More...
DLL_EXPORT cupvaError_t	CupvaGetPFSDTestCount (uint32_t *const PFSDTestCount)
	Get the count of supported PFSD tests. More...
DLL_EXPORT cupvaError_t	CupvaCmdPFSDCreate (cupvaCmd_t *const command, uint32_t const idx)
	Create a PFSD command. More...
DLL_EXPORT cupvaError_t	CupvaCheckCommandStatus (cupvaCmdStatus_t const status, cupvaError_t *const errorCode)
	Check the status of a command. More...
DLL_EXPORT cupvaError_t	CupvaCmdDestroy (cupvaCmd_t *const command)
	Destroy command. More...
DLL_EXPORT cupvaError_t	CupvaCmdBufferCreate (cupvaCmdBuffer_t *const cmdBuffer, cupvaCmd_t **const cmdList, int32_t const cmdListSize, cupvaCmdStatus_t *const status, cupvaOrderType_t const order)
	Create a CmdBuffer object for the given list of commands. More...
DLL_EXPORT cupvaError_t	CupvaCmdBufferDestroy (cupvaCmdBuffer_t const cmdBuffer)
	Destroy a CommandBuffer object. More...

Typedef Documentation

cupvaCmdBuffer_t

typedef struct cupvaCmdBufferRec* cupvaCmdBuffer_t

A container for a set of commands.

Definition at line 73 of file cupva_host_types.h.

cupvaCmdStatus_t

typedef struct cupvaCmdStatusRec* cupvaCmdStatus_t

Status output resulting from a submission.

Definition at line 103 of file cupva_host_types.h.

cupvaStream_t

typedef struct cupvaStreamRec* cupvaStream_t

Streams are used to submit PVA commands.

Definition at line 85 of file cupva_host_types.h.

Enumeration Type Documentation

cupvaAffinityType_t

enum cupvaAffinityType_t

Specifies VPU affinity for a Stream.

Enumerator
CUPVA_AFFINITY_TYPE_INVALID	Sentinel value.
CUPVA_VPU0
CUPVA_VPU1
CUPVA_VPU_ANY
CUPVA_AFFINITY_TYPE_MAX	One greater than max valid value.

Definition at line 95 of file cupva_host_types_scheduling.h.

cupvaEngineType_t

enum cupvaEngineType_t

Specifies PVA Engine ID for a Stream.

Enumerator
CUPVA_ENGINE_TYPE_INVALID	Sentinel value.
CUPVA_PVA0
CUPVA_PVA1
CUPVA_ENGINE_TYPE_MAX	One greater than max valid value.

Definition at line 79 of file cupva_host_types_scheduling.h.

cupvaOrderType_t

enum cupvaOrderType_t

Specifies scheduling and execution order for the commands submitted to the Stream.

Commands submitted to a Stream can be scheduled and executed by the hardware in two distinct ways. Commands submitted in IN_ORDER mode (default) will begin and complete the execution in the submission order, i.e., the order they appear in the CupvaStreamSubmit() call. Commands submitted in OUT_OF_ORDER mode begin execution in submission order, but may complete out of order. Completion ordering in OUT_OF_ORDER mode can be partially or fully enforced via CmdBarrier command which blocks Stream processing until all preceding (in submission order) commands are completed. This is different from CmdWaitOnFences, which blocks subsequent command processing until specific Fence objects are signalled.

OUT_OF_ORDER mode is useful in Stream instances configured to use VPU_ANY affinity, since multiple VPU engines can be used to process multiple independent commands in parallel.

To maximize the execution performance, it is recommended to terminate the submitted command list with a CmdBarrier instance in the following scenarios:

• Submission has an execution time out specified,
• Submission includes a CmdProgram instance that uses L2SRAM (Orin-specific),
• Stream has CUDA interop enabled.

Enumerator
CUPVA_ORDER_TYPE_INVALID	Sentinel value.
CUPVA_IN_ORDER
CUPVA_OUT_OF_ORDER
CUPVA_ORDER_TYPE_MAX	One greater than max valid value.

Definition at line 45 of file cupva_host_types_scheduling.h.

Function Documentation

CupvaCheckCommandStatus()

DLL_EXPORT cupvaError_t CupvaCheckCommandStatus	(	cupvaCmdStatus_t const	status,
		cupvaError_t *const	errorCode
	)

Check the status of a command.

Parameters

[in]	status	The pointer to the command status buffer.
[out]	errorCode	The pointer to return an error code.

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:
  • a NULL status pointer.
  • a NULL errorCode pointer.
• CUPVA_DRIVER_API_ERROR The PVA driver returned an unexpected error.

Usage considerations

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

CupvaCmdBufferCreate()

DLL_EXPORT cupvaError_t CupvaCmdBufferCreate	(	cupvaCmdBuffer_t *const	cmdBuffer,
		cupvaCmd_t **const	cmdList,
		int32_t const	cmdListSize,
		cupvaCmdStatus_t *const	status,
		cupvaOrderType_t const	order
	)

Create a CmdBuffer object for the given list of commands.

Parameters

[out]	cmdBuffer	The pointer to return the newly constructed command buffer object.
[in]	cmdList	Array of pointers to commands. Each command pointed to in the array will be consumed and can only be submitted as part of the CmdBuffer. It is still safe to destroy the consumed commands.
[in]	cmdListSize	The number of commands in cmdList.
[in]	status	The pointer to the array of the command status. The array has to be at least as large as the command list. NULL pointer can be passed if command status is not needed.
[in]	order	The command scheduling mode.

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:
  • a NULL cmdBuffer pointer.
  • a NULL cmdList pointer.
• CUPVA_NOT_ALLOWED_IN_OPERATIONAL_STATE if called when NVIDIA DRIVE OS VM state is "Operational"

Usage considerations

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

CupvaCmdBufferDestroy()

DLL_EXPORT cupvaError_t CupvaCmdBufferDestroy

(

cupvaCmdBuffer_t const

cmdBuffer

)

Destroy a CommandBuffer object.

Parameters

[in]

cmdBuffer

The pointer to a cupvaCmdBuffer_t 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 cmdBuffer was a NULL pointer.
• CUPVA_NOT_ALLOWED_IN_OPERATIONAL_STATE if called when NVIDIA DRIVE OS VM state is "Operational"

Usage considerations

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

CupvaCmdDestroy()

DLL_EXPORT cupvaError_t CupvaCmdDestroy

(

cupvaCmd_t *const

command

)

Destroy command.

Parameters

[in]

command

The pointer to a cupvaCmd_t 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 command was a NULL pointer.
• CUPVA_DRIVER_API_ERROR The PVA driver returned an unexpected error.
• CUPVA_NOT_ALLOWED_IN_OPERATIONAL_STATE if called to destroy CmdProgram or CmdPFSD when NVIDIA DRIVE OS VM state is "Operational"

Usage considerations

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

CupvaCmdPFSDCreate()

DLL_EXPORT cupvaError_t CupvaCmdPFSDCreate	(	cupvaCmd_t *const	command,
		uint32_t const	idx
	)

Create a PFSD command.

The PFSD obeys the same scheduling rules as CmdProgram, including respecting barriers, fence waits, fence signals, status buffers etc.

The PFSD application will execute a series of tasks on the hardware and record the result in a CRC checksum. If this checksum does not match the pre-defined expected value, the CupvaCheckCommandStatus() will return CUPVA_PSFD_CHECK_MISMATCH.

CupvaCheckCommandStatus() will return CUPVA_PSFD_TIMEOUT error if the execution of the PFSD task is not completed within the timeout duration. PFSD task execution timeout duration is set internally and different from the the command(s) execution timeout, CupvaStreamSubmit() executionTimeout parameter. User may still set the executionTimeout value while submitting PFSD command(s) to a stream.

Parameters

[in]	command	The pointer to a cupvaCmd_t object.
[in]	idx	Zero-based integer specifying the PFSD index. Refer to platform documentation for supported PFSD indices and details.

Returns

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

• CUPVA_ERROR_NONE if the operation was successful.
• CUPVA_INVALID_ARGUMENT indicates:
  • command was a NULL pointer.
  • idx is not a supported PFSD test index
• CUPVA_DRIVER_API_ERROR if driver returned error due to one of the following:
  • Internal driver memory allocation failed.
  • PVA engine was in a bad state.
  • The PVA hardware does not support PFSD.
  • The operating system does not support PFSD
• CUPVA_NOT_ALLOWED_IN_OPERATIONAL_STATE if called when NVIDIA DRIVE OS VM state is "Operational"

Usage considerations

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

CupvaGetPFSDTestCount()

DLL_EXPORT cupvaError_t CupvaGetPFSDTestCount

(

uint32_t *const

PFSDTestCount

)

Get the count of supported PFSD tests.

Parameters

[in]

PFSDTestCount

a uint32_t pointer to return the count of supported PFSD tests.

Returns

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

• CUPVA_ERROR_NONE if the operation was successful.
• CUPVA_INVALID_ARGUMENT if PFSDTestCount was a NULL pointer.
• CUPVA_NOT_ALLOWED_IN_OPERATIONAL_STATE if current context is null and default context does not exist and NVIDIA DRIVE OS VM state is "Operational"

Usage considerations

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

CupvaStreamCreate()

DLL_EXPORT cupvaError_t CupvaStreamCreate	(	cupvaStream_t *const	stream,
		cupvaEngineType_t const	absEngine,
		cupvaAffinityType_t const	vpuAffinity
	)

Create a new Stream object.

Parameters

[out]	stream	The pointer to return the the newly constructed Stream object.
[in]	absEngine	The PVA engine Id.
[in]	vpuAffinity	The queue submission affinity.

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:
  • stream is a NULL pointer.
  • vpuAffinity was invalid.
• CUPVA_DRIVER_API_ERROR The PVA driver returned an unexpected error.
• CUPVA_NOT_ALLOWED_IN_OPERATIONAL_STATE if called when NVIDIA DRIVE OS VM state is "Operational"

Usage considerations

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

CupvaStreamDestroy()

DLL_EXPORT cupvaError_t CupvaStreamDestroy

(

cupvaStream_t const

stream

)

Destroy a stream object.

Parameters

[in]

stream

The pointer to an Stream Object.

Returns

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

• CUPVA_ERROR_NONE if the operation was successful.
• CUPVA_DRIVER_API_ERROR if driver returned error due to one of the following:
  • Releasing symbols previously obtained via CupvaCmdProgramGetParameter
  • Destroying and de-allocating driver resources failed

Usage considerations

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

CupvaStreamSubmit()

DLL_EXPORT cupvaError_t CupvaStreamSubmit	(	cupvaStream_t const	stream,
		cupvaCmd_t const *const *const	command,
		cupvaCmdStatus_t *const	status,
		int32_t const	count,
		cupvaOrderType_t const	order,
		int32_t const	executionTimeout,
		int32_t const	submitTimeout
	)

Submit a batch of Commands to the Stream.

The first PVA task of each instance will likely incur a PVA engine power-up delay (Linux/L4T specific). To avoid CUPVA_COMMAND_SUBMISSION_TIMEOUT error when calling submit with a small submitTimeout, the user needs to submit a single fence request command and wait on it by calling fence.wait() at beginning of PVA application.

Parameters

[in]	stream	The pointer to an Stream Object.
[in]	command	The pointer to the array of the commands.
[in]	status	The pointer to the array of the command status. Size of this array should match the size of the command array. Each index in the command status array will give the status for the corresponding index in the commands array.
[in]	count	The number of commands to be submitted.
[in]	order	The command scheduling mode.
[in]	executionTimeout	The timeout (in usec) for the execution of the commands. If the entire batch doesn't finish in the specified time, the hardware will abort any currently running command and flush the remaining ones from current batch. The abort status is communicated via command status. A negative timeout value indicates commands are allowed to run indefinitely.
[in]	submitTimeout	The maximum time (in usec) the calling thread will be blocked on CupvaStreamSubmit() call. A negative timeout value indicates calling thread is blocked until the submission succeeds.

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:
  • stream was a NULL pointer.
  • command was a NULL pointer.
  • The number of commands exceeded the maximum.
  • An invalid command program was provided.
• CUPVA_COMMAND_SUBMISSION_TIMEOUT The submitTimeout value was reached before commands could be submitted.
• CUPVA_DRIVER_API_ERROR he PVA driver returned an unexpected error.
• CUPVA_NOT_ALLOWED_IN_OPERATIONAL_STATE if called when NVIDIA DRIVE OS VM state is "Operational"

Usage considerations

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

CupvaStreamSubmitCmdBuffer()

DLL_EXPORT cupvaError_t CupvaStreamSubmitCmdBuffer	(	cupvaStream_t const	stream,
		cupvaCmdBuffer_t const	cmdBuffer,
		int32_t const	executionTimeout,
		int32_t const	submitTimeout
	)

Submit cupvaCmdBuffer_t to the stream.

The first PVA task of each instance will likely incur a PVA engine power-up delay (Linux/L4T specific). To avoid CUPVA_COMMAND_SUBMISSION_TIMEOUT error when calling submit with a small submitTimeout, the user needs to submit a single fence request command and wait on it by calling fence.wait() at beginning of PVA application.

Parameters

[in]	stream	The pointer to an Stream Object.
[in]	cmdBuffer	The pointer to the cupvaCmdBuffer_t to be submitted.
[in]	executionTimeout	The timeout (in usec) for the execution of the command. If the command doesn't finish in the specified time it gets aborted. The abort is communicated via command status. By default commands are allowed to run indefinitely.
[in]	submitTimeout	The maximum time (in usec) the calling thread will be blocked on CupvaStreamSubmitCmdBuffer() call. By default the calling thread is blocked until the submission succeeds.

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:
  • stream was a NULL pointer.
  • cmdBuffer was a NULL pointer.
  • An invalid command program was provided.
• CUPVA_COMMAND_SUBMISSION_TIMEOUT The submitTimeout value was reached before commands could be submitted.
• CUPVA_DRIVER_API_ERROR he PVA driver returned an unexpected error.

Usage considerations

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