Detailed Description

The VIC HW Diagnostics API encompasses functionality to run diagnostic tests on VIC hardware.

6

Data Structures
struct	VicDiagnosticsAttributes
	Attributes structure for VicDiagnosticsCreate(). More...

struct	VicDiagnosticsResult
	Stores information returned from VicDiagnosticsExecute(). More...

Macros
#define	VICDIAGNOSTICS_VERSION_MAJOR 1
	Major version number of VIC Diagnostics header. More...

#define	VICDIAGNOSTICS_VERSION_MINOR 0
	Minor version number of VIC Diagnostics header. More...

#define	VICDIAGNOSTICS_VERSION_PATCH 1
	Patch version number of VIC Diagnostics header. More...

#define	VICDIAGNOSTICS_TASK_STATUS_CHECKSUM_MISMATCH 41u
	Task status value indicating the test checksum did not match the expected one. More...

Typedefs
typedef uint32_t	VicDiagnosticsParameters
	Stores configuration for the VicDiagnosticsExecute() operation. More...

typedef struct VicDiagnostics	VicDiagnostics
	VicDiagnostics Context. More...

Functions
NvMediaStatus	VicDiagnosticsGetVersion (NvMediaVersion *const version)
	Returns the version number of the NvMedia Vic Diagnostics library. More...

NvMediaStatus	VicDiagnosticsCreate (VicDiagnostics *const handle, VicDiagnosticsAttributes const const attr)
	Creates a new VicDiagnostics context. More...

NvMediaStatus	VicDiagnosticsDestroy (VicDiagnostics const *const handle)
	Destroys the VicDiagnostics context. More...

NvMediaStatus	VicDiagnosticsGetParameters (VicDiagnostics const const handle, VicDiagnosticsParameters const params)
	Returns an VicDiagnosticsParameters instance. More...

NvMediaStatus	VicDiagnosticsExecute (VicDiagnostics const const handle, VicDiagnosticsParameters const params, VicDiagnosticsResult const result)
	Performs a VIC HW diagnostic operation. More...

NvMediaStatus	VicDiagnosticsGetNumTests (VicDiagnostics const const handle, uint32_t const numTests)
	Gets the number of available diagnostics tests. More...

NvMediaStatus	VicDiagnosticsSetTest (VicDiagnostics const *const handle, VicDiagnosticsParameters const params, uint32_t const testId)
	Sets the test ID for an VicDiagnosticsParameters instance. More...

Macro Definition Documentation

◆ VICDIAGNOSTICS_TASK_STATUS_CHECKSUM_MISMATCH

#define VICDIAGNOSTICS_TASK_STATUS_CHECKSUM_MISMATCH 41u

Task status value indicating the test checksum did not match the expected one.

Definition at line 353 of file vicdiagnostics.h.

◆ VICDIAGNOSTICS_VERSION_MAJOR

#define VICDIAGNOSTICS_VERSION_MAJOR 1

Major version number of VIC Diagnostics header.

This defines the major version of the API defined in this header. This is intended to be used when validating the version number returned by the VicDiagnosticsGetVersion() function.

See also: VicDiagnosticsGetVersion()

Definition at line 46 of file vicdiagnostics.h.

◆ VICDIAGNOSTICS_VERSION_MINOR

#define VICDIAGNOSTICS_VERSION_MINOR 0

Minor version number of VIC Diagnostics header.

This defines the minor version of the API defined in this header. This is intended to be used when validating the version number returned by the VicDiagnosticsGetVersion() function.

See also: VicDiagnosticsGetVersion()

Definition at line 56 of file vicdiagnostics.h.

◆ VICDIAGNOSTICS_VERSION_PATCH

#define VICDIAGNOSTICS_VERSION_PATCH 1

Patch version number of VIC Diagnostics header.

This defines the patch version of the API defined in this header.

See also: VicDiagnosticsGetVersion()

Definition at line 64 of file vicdiagnostics.h.

Typedef Documentation

◆ VicDiagnostics

typedef struct VicDiagnostics VicDiagnostics

VicDiagnostics Context.

This type represents a context for the VicDiagnostics library. This context is an opaque data type that encapsulates the state needed to service the VicDiagnostics API calls.

See also: VicDiagnosticsCreate()

Definition at line 191 of file vicdiagnostics.h.

◆ VicDiagnosticsParameters

typedef uint32_t VicDiagnosticsParameters

Stores configuration for the VicDiagnosticsExecute() operation.

This object stores the information needed to configure the diagnostic operation that is executed inside the VicDiagnosticsExecute() function.

The underlying object cannot be instantiated directly by the client. Instead use the VicDiagnosticsGetParameters() function to retrieve a handle to an available instance.

Value 0 is never a valid handle value, and can be used to initialize a VicDiagnosticsParameters handle to a known value.

See also: VicDiagnosticsGetParameters(); VicDiagnosticsInsertPreNvSciSyncFence(); VicDiagnosticsSetNvSciSyncObjforEOF(); VicDiagnosticsExecute()

Definition at line 118 of file vicdiagnostics.h.

Function Documentation

◆ VicDiagnosticsCreate()

NvMediaStatus VicDiagnosticsCreate	(	VicDiagnostics **const	handle,
		VicDiagnosticsAttributes const *const	attr
	)

Creates a new VicDiagnostics context.

This function creates a new instance of an VicDiagnostics context, and returns a pointer to that context. Ownership of this context is passed to the caller. When no longer in use, the caller must destroy the context using the VicDiagnosticsDestroy() function.

Default attributes (when not specified by caller):

numDiagnosticsParameters: 1
maxRegisteredSyncs: 16
flags: 0.

Parameters

[out]	handle	Pointer to receive the handle to the new VicDiagnostics context.
[in]	attr	Pointer to VicDiagnosticsAttributes struct, or NULL for default attributes.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Context created successfully.
NVMEDIA_STATUS_BAD_PARAMETER	handle is NULL, or attr has bad attribute values.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_NOT_SUPPORTED	NvMedia Vic Diagnostics is not supported on this hardware platform.
NVMEDIA_STATUS_OUT_OF_MEMORY	Memory allocation failed for internal data structures or device memory buffers.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to create the context.

Precondition: None.

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different VicDiagnostics handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: No

See also: VicDiagnostics; VicDiagnosticsDestroy()

◆ VicDiagnosticsDestroy()

NvMediaStatus VicDiagnosticsDestroy ( VicDiagnostics const *const handle )

Destroys the VicDiagnostics context.

This function destroys the specified VicDiagnostics context.

Before calling this function, the caller must ensure:

There are no NvSciSync objects still registered against the VicDiagnostics context.
All previous Vic Diagnostics operations submitted using VicDiagnosticsExecute() have completed.

Parameters

[in] handle Pointer to the VicDiagnostics context.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Context destroyed successfully.
NVMEDIA_STATUS_BAD_PARAMETER	handle is NULL.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_PENDING	There are still some NvSciSync objects registered against the VicDiagnostics context.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to destroy the context. The context is in state where the only valid operation is to attempt to destroy it again.

Precondition

handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different VicDiagnostics handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: No
- De-Init: Yes

See also: VicDiagnostics; VicDiagnosticsCreate()

◆ VicDiagnosticsExecute()

NvMediaStatus VicDiagnosticsExecute	(	VicDiagnostics const *const	handle,
		VicDiagnosticsParameters const	params,
		VicDiagnosticsResult *const	result
	)

Performs a VIC HW diagnostic operation.

A diagnostic operation performs a pre-defined hardware diagnostic test based on calculating a checksum for an operation and comparing it to an expected value. The test to be run can be chosen with VicDiagnosticsSetTest().

To get full diagnostic coverage of the VIC HW, all of the available tests need to be executed periodically. The possibility to select a single test to be run independently through VicDiagnosticsSetTest() is offered to allow for more fine-grained scheduling of the test execution.

The result of the diagnostic test is indicated in the task status that can be queried from the EOF fence:

NvSciSyncTaskStatus_Success: test passed
VICDIAGNOSTICS_TASK_STATUS_CHECKSUM_MISMATCH: calculated checksum did not match the expected one
Other: an internal failure

Because of this, EOF sync object must always be set with VicDiagnosticsSetNvSciSyncObjforEOF() prior to calling VicDiagnosticsExecute().

This example runs a diagnostic test with id 0.

VicDiagnosticsParameters params;
VicDiagnosticsGetParameters(handle, &params);
VicDiagnosticsSetTest(handle, params, 0);
VicDiagnosticsSetNvSciSyncObjforEOF(handle, params, eofSyncObj);
VicDiagnosticsExecute(handle, params, NULL);

Restrictions on concurrency:

There can be a maximum of 16 operations submitted through the same VicDiagnostics handle pending simultaneously.

If any of the restrictions are violated, this function will fail with an error code.

The result info returned in result is tied to the specific VicDiagnostics context instance passed in handle and cannot be used with other context instances.

Parameters

[in]	handle	Pointer to the VicDiagnostics context.
[in]	params	An VicDiagnosticsParameters handle.
[out]	result	Pointer to VicDiagnosticsResult struct that will be populated with result info. May be NULL.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Operation submitted successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL params is invalid EOF sync object has not been set some of the parameters configured through params have invalid values.
NVMEDIA_STATUS_NOT_SUPPORTED	Requested operation is not supported by current platform.
NVMEDIA_STATUS_TIMED_OUT	No space available in the command buffer for this operation, because previous operations are still pending (see restrictions on concurrency). The caller should wait for the least recently submitted operation to complete and then try again.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to perform the diagnostic operation. This error indicates the system is potentially in an unrecoverable state.

Precondition

handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().
params must be valid VicDiagnosticsParameters handle created with VicDiagnosticsGetParameters().
params must have a valid EOF sync object set with VicDiagnosticsSetNvSciSyncObjforEOF().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different VicDiagnostics handle
- Re-entrant: No
- Async/Sync: Async
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

See also: VicDiagnosticsParameters; VicDiagnosticsGetParameters(); VicDiagnosticsInsertPreNvSciSyncFence(); VicDiagnosticsSetNvSciSyncObjforEOF(); VicDiagnosticsGetEOFNvSciSyncFence()

◆ VicDiagnosticsGetNumTests()

NvMediaStatus VicDiagnosticsGetNumTests	(	VicDiagnostics const *const	handle,
		uint32_t *const	numTests
	)

Gets the number of available diagnostics tests.

This function returns the number of available diagnostics tests.

Parameters

[in]	handle	Pointer to the VicDiagnostics context.
[out]	numTests	A uint32_t to receive the number of available tests.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Test id was set successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value, either: handle is NULL. numTests is NULL.

Precondition

handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different VicDiagnostics handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

See also: VicDiagnosticsSetTest()

◆ VicDiagnosticsGetParameters()

NvMediaStatus VicDiagnosticsGetParameters	(	VicDiagnostics const *const	handle,
		VicDiagnosticsParameters *const	params
	)

Returns an VicDiagnosticsParameters instance.

This functions returns a handle to an VicDiagnosticsParameters object. The object will be initialized and ready to use. The caller takes ownership of this handle. Ownership will be passed back to the VicDiagnostics context when it is subsequently used in the VicDiagnosticsExecute() operation.

The handle returned in params is tied to the specific VicDiagnostics context instance passed in handle and cannot be used with other context instances.

Parameters

[in]	handle	Pointer to the VicDiagnostics context.
[out]	params	Pointer to an #VicDiagnosticsarameters, which will be populated with the handle.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Parameters instance is initialized successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value, either: handle is NULL params is NULL.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING	There is no free instance available.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to retrieve the parameters object.

Precondition

handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different VicDiagnostics handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

See also: VicDiagnosticsParameters; VicDiagnosticsExecute()

◆ VicDiagnosticsGetVersion()

NvMediaStatus VicDiagnosticsGetVersion ( NvMediaVersion *const version )

Returns the version number of the NvMedia Vic Diagnostics library.

This function returns the major and minor version number of the Vic Diagnostics library. The client must pass an NvMediaVersion struct to this function, and the version information will be returned in this struct.

This allows the client to verify that the version of the library matches and is compatible with the the version number of the header file they are using.

Parameters

[out] version Pointer to an NvMediaVersion struct that will be populated with the version information.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Version information returned successfully.
NVMEDIA_STATUS_BAD_PARAMETER	version is NULL.

Precondition: None.

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different NvMediaVersion object
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: Yes
- Runtime: Yes
- De-Init: Yes

See also: VICDIAGNOSTICS_VERSION_MAJOR; VICDIAGNOSTICS_VERSION_MINOR; VICDIAGNOSTICS_VERSION_PATCH; NvMediaVersion

◆ VicDiagnosticsSetTest()

NvMediaStatus VicDiagnosticsSetTest	(	VicDiagnostics const *const	handle,
		VicDiagnosticsParameters const	params,
		uint32_t const	testId
	)

Sets the test ID for an VicDiagnosticsParameters instance.

This function updates the VicDiagnosticsParameters instance with a test ID to be run when VicDiagnosticsExecute() is called. Test ID must be in the range [0, VicDiagnosticsGetNumTests()[

Parameters

[in]	handle	Pointer to the VicDiagnostics context.
[in]	params	An VicDiagnosticsParameters handle.
[in]	testId	A testId to run.

Returns: An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Test id was set successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value, either: handle is NULL. params is invalid. testId is out of range.

Precondition

handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().
params must be valid VicDiagnosticsParameters handle created with VicDiagnosticsGetParameters().

Usage considerations

Allowed context for the API call
- Interrupt handler: No
- Signal handler: No
- Thread-safe: Yes, with the following conditions:
  - Each thread uses different VicDiagnostics handle
- Re-entrant: No
- Async/Sync: Sync
Required privileges: None
API group
- Init: No
- Runtime: Yes
- De-Init: No

See also: VicDiagnosticsGetNumTests

NVIDIA DriveOS Linux NSR SDK API Reference

7.0.3.0 Release

Detailed Description

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ VICDIAGNOSTICS_TASK_STATUS_CHECKSUM_MISMATCH

◆ VICDIAGNOSTICS_VERSION_MAJOR

◆ VICDIAGNOSTICS_VERSION_MINOR

◆ VICDIAGNOSTICS_VERSION_PATCH

Typedef Documentation

◆ VicDiagnostics

◆ VicDiagnosticsParameters

Function Documentation

◆ VicDiagnosticsCreate()

◆ VicDiagnosticsDestroy()

◆ VicDiagnosticsExecute()

◆ VicDiagnosticsGetNumTests()

◆ VicDiagnosticsGetParameters()

◆ VicDiagnosticsGetVersion()

◆ VicDiagnosticsSetTest()