Context#

APIs to create and manage cuPVA contexts.

Macros#

CUPVA_COMMAND_UNKNOWN

Value of cupvaStatus_t::command when the failing command could not be identified.

CUPVA_SUBMISSION_UNKNOWN

Value of cupvaStatus_t::submissionsSinceError when the failing submission could not be located.

Functions#

cupvaError_t CupvaContextCreate(cupvaContext_t *const context, uint32_t const engineMask)

Create a new Context object.

cupvaError_t CupvaContextDestroy(cupvaContext_t const context)

Destroy context.

cupvaError_t CupvaContextGetCurrent(cupvaContext_t *const context)

Gets the pointer to the context instance used.

cupvaError_t CupvaContextSetCurrent(cupvaContext_t const context)

Sets the context for the calling thread.

cupvaError_t CupvaGetStatus(cupvaStatus_t *const outStatus)

Return the health of the current Context.

Data Structures#

cupvaStatus_t

Health of the cuPVA runtime, and a description of the failure when it is not healthy.

Typedefs#

cupvaContext_t

Context holds all resources required by other CUPVA APIs.

Functions#

cupvaError_t CupvaContextCreate(
cupvaContext_t *const context,
uint32_t const engineMask,
)#

Create a new Context object.

The context automatically becomes current for the calling thread.

The context abstracts the PVA hardware. The current context is stored in thread-local storage. All CUPVA API calls are implicitly using the current context of the calling thread, and all CUPVA objects created are implicitly owned by the current context.

If a calling thread does not have a current context when an API call requiring a Context is made, a default context is used. The default Context is process-wide. The system has a limit on the number of Contexts created across all processes, which includes default Contexts. On currently supported platforms, this limit is 4. If the limit is exceeded, this API will fail with a DriverAPIError.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: Yes

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: No

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

  • context – [out] The pointer to return the newly allocated context object.

  • engineMask – [in] Bitmask indicating which engines to enable in the context.

Returns:

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

  • CUPVA_ERROR_NONE if the operation was successful.

  • CUPVA_INVALID_ARGUMENT if context is a NULL pointer.

  • CUPVA_DRIVER_API_ERROR if the PVA driver returned an unexpected error.

  • CUPVA_INTERNAL_ERROR if it failed to initialize internal state

  • CUPVA_NOT_ALLOWED_IN_OPERATIONAL_STATE if called when NVIDIA DRIVE OS VM state is “Operational”

Pre:

None

cupvaError_t CupvaContextDestroy(cupvaContext_t const context)#

Destroy context.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: No

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: No

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

context – [in] The pointer to the Context 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 context is a NULL pointer.

  • CUPVA_DRIVER_API_ERROR if The PVA driver returned an unexpected error.

  • CUPVA_NOT_ALLOWED_IN_OPERATIONAL_STATE if called when NVIDIA DRIVE OS VM state is “Operational”

  • CUPVA_INVALID_STATE if called without freeing all allocations

Pre:

None

cupvaError_t CupvaContextGetCurrent(cupvaContext_t *const context)#

Gets the pointer to the context instance used.

The context abstracts the PVA hardware. The current context is stored in thread-local storage. All CUPVA API calls are implicitly using the current context of the calling thread, and all CUPVA objects created are implicitly owned by the current context.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: Yes

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

context – [out] The pointer to return the context instance used by calling thread.

Returns:

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

  • CUPVA_ERROR_NONE if the operation was successful.

  • CUPVA_INVALID_ARGUMENT if context is a NULL pointer.

Pre:

None

cupvaError_t CupvaContextSetCurrent(cupvaContext_t const context)#

Sets the context for the calling thread.

The context abstracts the PVA hardware. The current context is stored in thread-local storage. All CUPVA API calls are implicitly using the current context of the calling thread, and all CUPVA objects created are implicitly owned by the current context.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: Yes

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

context – [in] A pointer to the context instance which current for the calling thread. Passing null causes the thread to use the default application context.

Pre:

None

cupvaError_t CupvaGetStatus(cupvaStatus_t *const outStatus)#

Return the health of the current Context.

Once an asynchronous error has occurred, the associated Context becomes invalid and the Streams that belong to the Context will fail to submit new Commands. This reports whether the current Context is still valid, and describes the source of the failure when it is not.

For a quick validity check, test outStatus->err against CUPVA_ERROR_NONE. The remaining fields describe where the failure came from; see cupvaStatus_t.

Once a user created Context becomes invalid, the application has a chance to recover by tearing down all the resources owned by the Context, destroying the Context, and then starting over with a freshly created Context. The default Context owned by cuPVA is not recoverable in this way. Once the default Context becomes invalid, the process must exit and restart to establish a valid default Context.

The errorMsg and streamName members remain valid for the life of the Context they describe.

The return value reports whether the query itself succeeded, not whether the Context is healthy. It is CUPVA_ERROR_NONE whenever outStatus was written.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: Yes

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

outStatus – [out] Receives the health of the current Context. When it is healthy, err is CUPVA_ERROR_NONE, errorMsg receives “No error”, stream is zero, streamName is NULL, and submissionsSinceError and command are CUPVA_SUBMISSION_UNKNOWN and CUPVA_COMMAND_UNKNOWN.

Returns:

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

  • CUPVA_ERROR_NONE if outStatus was written.

  • CUPVA_INVALID_ARGUMENT if outStatus is a NULL pointer.

  • CUPVA_INSUFFICIENT_DRIVER_VERSION if the driver does not support Context error reporting.

  • CUPVA_DRIVER_API_ERROR if the PVA driver returned an unexpected error.

Pre:

None

Typedefs#

typedef struct cupvaContextRec *cupvaContext_t#

Context holds all resources required by other CUPVA APIs.

  • Maturity: GA