Synchronization#

APIs to synchronize the access to resources from multiple asynchronous engines.

The synchronization APIs are used to ensure synchronization between host application and the VPUs/other engines.

Enumerations#

cupvaSyncClientType_t

The synchronization client type.

cupvaSyncWaitMode_t

The sync object wait mode.

Functions#

cupvaError_t CupvaCmdBarrierInit(cupvaCmd_t *const cmdBarrier)

Create a Barrier command.

cupvaError_t CupvaCmdRequestFencesInit(cupvaCmd_t *const command, cupvaFence_t *const fence, int32_t const count)

Initialize a Request Fence command from the given fence.

cupvaError_t CupvaCmdWaitOnFencesInit(cupvaCmd_t *const command, cupvaFence_t const *const fence, int32_t const count)

Initialize a WaitOnFence command from the given fence.

cupvaError_t CupvaFenceGetTimeStamp(cupvaFence_t const *const fence, uint64_t *const timeStamp)

Gets the time at which current fence expired (in nanoseconds).

cupvaError_t CupvaFenceInit(cupvaFence_t *const fence, cupvaSyncObj_t const syncObj)

Initialize an empty fence.

cupvaError_t CupvaFenceWait(cupvaFence_t const *const fence, int64_t const timeout, bool *const waitSuccess)

Block the calling thread until the fence is triggered or time out.

cupvaError_t CupvaSyncObjCreate(cupvaSyncObj_t *const syncObj, bool const isTimeStamp, cupvaSyncClientType_t const clientType, cupvaSyncWaitMode_t const waitMode)

Create and set syncObj to be an empty cupva sync object.

cupvaError_t CupvaSyncObjDestroy(cupvaSyncObj_t const syncObj)

Destroy a cupva sync object.

Data Structures#

cupvaFence_t

Used synchronize PVA workloads with other engines, including CPU.

Typedefs#

cupvaSyncObj_t

A synchronization object which holds resources needed by fences.

Enumerations#

enum cupvaSyncClientType_t#

The synchronization client type.

Values:

enumerator CUPVA_SYNC_CLIENT_TYPE_INVALID#

Sentinel value

enumerator CUPVA_SIGNALER#

Synchronization client type for signal

enumerator CUPVA_WAITER#

Synchronization client type for wait

enumerator CUPVA_SIGNALER_WAITER#

Synchronization client type supporting both signal and wait

enumerator CUPVA_SYNC_CLIENT_TYPE_MAX#

One greater than max valid value

enum cupvaSyncWaitMode_t#

The sync object wait mode.

This controls how an app interacts with the OS scheduler while blocked by calling Fence::wait().

Values:

enumerator CUPVA_SYNC_WAIT_MODE_INVALID#

Sentinel value

enumerator CUPVA_SYNC_YIELD#

Yield the caller thread while blocked by calling CupvaFenceWait().

enumerator CUPVA_SYNC_SPIN#

Actively spin while blocked by calling CupvaFenceWait().

enumerator CUPVA_SYNC_WAIT_MODE_MAX#

One greater than max valid value

Functions#

cupvaError_t CupvaCmdBarrierInit(cupvaCmd_t *const cmdBarrier)#

Create a Barrier command.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

cmdBarrier – [in] 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 cmdBarrier was a NULL pointer.

cupvaError_t CupvaCmdRequestFencesInit(
cupvaCmd_t *const command,
cupvaFence_t *const fence,
int32_t const count,
)#

Initialize a Request Fence command from the given fence.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

  • command – [in] The pointer to a cupvaCmd_t object.

  • fence – [in] The pointer to a cupvaFence_t array.

  • count – [in] The number of fences in the array.

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:

    • command was a NULL pointer.

    • fence was a NULL pointer.

    • count > MAX_CMD_REQUEST_FENCES_ARRAY_SIZE.

cupvaError_t CupvaCmdWaitOnFencesInit(
cupvaCmd_t *const command,
cupvaFence_t const *const fence,
int32_t const count,
)#

Initialize a WaitOnFence command from the given fence.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

  • command – [in] The pointer to a cupvaCmd_t object.

  • fence – [in] The pointer to a cupvaFence_t array.

  • count – [in] The number of fences in the array.

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:

    • command was a NULL pointer.

    • fence was a NULL pointer.

    • count > MAX_CMD_REQUEST_FENCES_ARRAY_SIZE.

cupvaError_t CupvaFenceGetTimeStamp(
cupvaFence_t const *const fence,
uint64_t *const timeStamp,
)#

Gets the time at which current fence expired (in nanoseconds).

CupvaFenceWait() must return with success and set waitSuccess argument to true prior to calling this API or the timestamp value cannot be considered valid.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: Yes

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

  • fence – [in] The pointer to a cupvaFence_t object.

  • timeStamp – [out] An uint64_t pointer to return the timestamp.

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:

    • fence was a NULL pointer.

    • timeStamp was a NULL pointer.

  • CUPVA_DRIVER_API_ERROR The PVA driver returned an unexpected error.

cupvaError_t CupvaFenceInit(
cupvaFence_t *const fence,
cupvaSyncObj_t const syncObj,
)#

Initialize an empty fence.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

  • fence – [in] The pointer to a cupvaFence_t object.

  • syncObj – [in] The pointer to a CUPVA sync object.

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:

    • fence was a NULL pointer.

    • syncObj was a NULL pointer.

cupvaError_t CupvaFenceWait(
cupvaFence_t const *const fence,
int64_t const timeout,
bool *const waitSuccess,
)#

Block the calling thread until the fence is triggered or time out.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: Yes

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

  • fence – [in] The pointer to a cupvaFence_t object.

  • timeout – [in] The maximum time to wait in micro seconds. -1 will wait forever.

  • waitSuccess – [out] The pointer a boolean variable used to store wait status - true if wait was successful; false if timeout occurred before the fence was triggered. Can be NULL, in which case it will be ignored.

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:

    • fence was a NULL pointer.

  • CUPVA_DRIVER_API_ERROR The PVA driver returned an unexpected error.

cupvaError_t CupvaSyncObjCreate(
cupvaSyncObj_t *const syncObj,
bool const isTimeStamp,
cupvaSyncClientType_t const clientType,
cupvaSyncWaitMode_t const waitMode,
)#

Create and set syncObj to be an empty cupva sync object.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: Yes

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

  • syncObj – [out] The pointer to return the newly constructed Sync object.

  • isTimeStamp – [in] The flag to turn on/off the time-stamp in the SyncObj.

  • clientType – [in] The synchronization client type.

  • waitMode – [in] The sync object wait 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:

    • syncObj was a NULL pointer.

    • clientType was invalid.

    • waitMode 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”

cupvaError_t CupvaSyncObjDestroy(cupvaSyncObj_t const syncObj)#

Destroy a cupva sync object.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: No

    • De-Init: Yes

Parameters:

syncObj – [in] The pointer to a cupvaSyncObj_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 syncObj was a NULL pointer.

  • 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”

Typedefs#

typedef struct cupvaSyncObjRec *cupvaSyncObj_t#

A synchronization object which holds resources needed by fences.