Diagnostics

Diagnostics#

oneAPI Level Zero Specification - Version 1.18.31

Diagnostics Functions#

zesDiagnosticsGetProperties#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesDiagnosticsGetProperties(zes_diag_handle_t hDiagnostics, zes_diag_properties_t *pProperties)#

Get properties of a diagnostics test suite.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDiagnostics – [in] Handle for the component.

  • pProperties – [in,out] Structure describing the properties of a diagnostics test suite

Returns:

zesDiagnosticsGetTests#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesDiagnosticsGetTests(zes_diag_handle_t hDiagnostics, uint32_t *pCount, zes_diag_test_t *pTests)#

Get individual tests that can be run separately. Not all test suites permit running individual tests, check the haveTests member of zes_diag_properties_t.

  • The list of available tests is returned in order of increasing test index (see the index member of zes_diag_test_t).

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDiagnostics – [in] Handle for the component.

  • pCount – [in,out] pointer to the number of tests. if count is zero, then the driver shall update the value with the total number of tests that are available. if count is greater than the number of tests that are available, then the driver shall update the value with the correct number of tests.

  • pTests – [in,out][optional][range(0, *pCount)] array of information about individual tests sorted by increasing value of the index member of zes_diag_test_t. if count is less than the number of tests that are available, then the driver shall only retrieve that number of tests.

Returns:

zesDiagnosticsRunTests#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesDiagnosticsRunTests(zes_diag_handle_t hDiagnostics, uint32_t startIndex, uint32_t endIndex, zes_diag_result_t *pResult)#

Run a diagnostics test suite, either all tests or a subset of tests.

  • WARNING: Running diagnostics may destroy current device state information. Gracefully close any running workloads before initiating.

  • To run all tests in a test suite, set start = ZES_DIAG_FIRST_TEST_INDEX and end = ZES_DIAG_LAST_TEST_INDEX.

  • If the test suite permits running individual tests, the haveTests member of zes_diag_properties_t will be true. In this case, the function zesDiagnosticsGetTests() can be called to get the list of tests and corresponding indices that can be supplied to the arguments start and end in this function.

  • This function will block until the diagnostics have completed and force reset based on result

Parameters:

  • hDiagnostics – [in] Handle for the component.

  • startIndex – [in] The index of the first test to run. Set to ZES_DIAG_FIRST_TEST_INDEX to start from the beginning.

  • endIndex – [in] The index of the last test to run. Set to ZES_DIAG_LAST_TEST_INDEX to complete all tests after the start test.

  • pResult – [in,out] The result of the diagnostics

Returns:

Diagnostics Enums#

zes_diag_result_t#

Added in version 1.0

enum zes_diag_result_t#

Diagnostic results.

Values:

enumerator ZES_DIAG_RESULT_NO_ERRORS#

Diagnostic completed without finding errors to repair.

enumerator ZES_DIAG_RESULT_ABORT#

Diagnostic had problems running tests.

enumerator ZES_DIAG_RESULT_FAIL_CANT_REPAIR#

Diagnostic had problems setting up repairs.

enumerator ZES_DIAG_RESULT_REBOOT_FOR_REPAIR#

Diagnostics found errors, setup for repair and reboot is required to complete the process

enumerator ZES_DIAG_RESULT_FORCE_UINT32#

Value marking end of ZES_DIAG_RESULT_* ENUMs.

Diagnostics Structures#

zes_diag_test_t#

Added in version 1.0

struct zes_diag_test_t#

Diagnostic test.

Public Members

uint32_t index#

[out] Index of the test

char name[ZES_STRING_PROPERTY_SIZE]#

[out] Name of the test

zes_diag_properties_t#

Added in version 1.0

struct zes_diag_properties_t#

Diagnostics test suite properties.

Public Members

zes_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_bool_t onSubdevice#

[out] True if the resource is located on a sub-device; false means that the resource is on the device of the calling Sysman handle

uint32_t subdeviceId#

[out] If onSubdevice is true, this gives the ID of the sub-device

char name[ZES_STRING_PROPERTY_SIZE]#

[out] Name of the diagnostics test suite

ze_bool_t haveTests#

[out] Indicates if this test suite has individual tests which can be run separately (use the function zesDiagnosticsGetTests() to get the list of these tests)

In this class