Ras - Experimental

Ras - Experimental#

oneAPI Level Zero Specification - Version 1.18.31

Ras - Experimental Functions#

zesRasGetStateExp#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesRasGetStateExp(zes_ras_handle_t hRas, uint32_t *pCount, zes_ras_state_exp_t *pState)#

Ras Get State.

  • This function retrieves error counters for different RAS error categories.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hRas – [in] Handle for the component.

  • pCount – [in,out] pointer to the number of RAS state structures that can be retrieved. if count is zero, then the driver shall update the value with the total number of error categories for which state can be retrieved. if count is greater than the number of RAS states available, then the driver shall update the value with the correct number of RAS states available.

  • pState – [in,out][optional][range(0, *pCount)] array of query results for RAS error states for different categories. if count is less than the number of RAS states available, then driver shall only retrieve that number of RAS states.

Returns:

zesRasClearStateExp#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesRasClearStateExp(zes_ras_handle_t hRas, zes_ras_error_category_exp_t category)#

Ras Clear State.

  • This function clears error counters for a RAS error category.

  • Clearing errors will affect other threads/applications - the counter values will start from zero.

  • Clearing errors requires write permissions.

  • The application should not call this function from simultaneous threads.

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

Parameters:

  • hRas – [in] Handle for the component.

  • category – [in] category for which error counter is to be cleared.

Returns:

zesRasGetSupportedCategoriesExp#

Added in version 1.16

ZE_APIEXPORT ze_result_t ZE_APICALL zesRasGetSupportedCategoriesExp(zes_ras_handle_t hRas, uint32_t *pCount, zes_ras_error_category_exp_t *pCategories)#

Get supported RAS error categories.

  • This function retrieves the supported RAS error categories for the given RAS handle.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hRas – [in] Handle for the component.

  • pCount – [in,out] pointer to the number of categories. if count is zero, then the driver shall update the value with the total number of categories supported. if count is non-zero, then driver shall only retrieve that number of categories.

  • pCategories – [in,out][optional][range(0, *pCount)] array of category types. if count is less than the number of categories supported, then driver shall only retrieve that number of categories.

Returns:

zesRasGetStateExp2#

Added in version 1.16

ZE_APIEXPORT ze_result_t ZE_APICALL zesRasGetStateExp2(zes_ras_handle_t hRas, const uint32_t count, const zes_ras_error_category_exp_t *pCategories, zes_ras_state_exp2_t *pState)#

Get RAS error counters for different categories.

  • This function retrieves error counters for different RAS error categories.

  • The categories and states arrays have 1:1 correspondence - pState[i] contains the error counter for pCategories[i].

  • The caller must initialize stype and pNext fields in each element of the pState array.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hRas – [in] Handle for the component.

  • count – [in] Number of elements in pCategories (same as in pState array).

  • pCategories – [in][range(0, count)] Array of RAS error categories to query.

  • pState – [out][range(0, count)] Array of RAS error states. Caller must initialize stype and pNext for each element.

Returns:

zesRasGetConfigExp#

Added in version 1.16

ZE_APIEXPORT ze_result_t ZE_APICALL zesRasGetConfigExp(zes_ras_handle_t hRas, const uint32_t count, zes_ras_config_exp_t *pConfig)#

Get RAS error thresholds that control when RAS events are generated.

  • This function retrieves the RAS error thresholds for the specified RAS error categories.

  • When a particular RAS error counter for a given category exceeds the configured threshold, the corresponding RAS event will be triggered.

  • For correctable errors: ZES_EVENT_TYPE_FLAG_RAS_CORRECTABLE_ERRORS

  • For uncorrectable errors: ZES_EVENT_TYPE_FLAG_RAS_UNCORRECTABLE_ERRORS

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hRas – [in] Handle for the component.

  • count – [in] Number of RAS configuration structures in pConfig array.

  • pConfig – [in,out][range(0, count)] array of RAS configuration structures. The caller should set the category field for each entry to specify which categories to query.

Returns:

zesRasSetConfigExp#

Added in version 1.16

ZE_APIEXPORT ze_result_t ZE_APICALL zesRasSetConfigExp(zes_ras_handle_t hRas, const uint32_t count, const zes_ras_config_exp_t *pConfig)#

Set RAS error thresholds that control when RAS events are generated.

  • This function sets the RAS error thresholds for the specified RAS error categories.

  • When a particular RAS error counter for a given category exceeds the specified threshold, the corresponding RAS event will be generated.

  • Setting a threshold of 0 disables event generation for that category.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hRas – [in] Handle for the component.

  • count – [in] Number of RAS configuration structures in pConfig array.

  • pConfig – [in][range(0, count)] array of RAS configuration structures specifying thresholds for different error categories.

Returns:

Ras - Experimental Enums#

zes_ras_error_category_exp_t#

Added in version 1.7

enum zes_ras_error_category_exp_t#

RAS error categories.

Values:

enumerator ZES_RAS_ERROR_CATEGORY_EXP_RESET#

The number of accelerator engine resets attempted by the driver.

enumerator ZES_RAS_ERROR_CATEGORY_EXP_PROGRAMMING_ERRORS#

The number of hardware exceptions generated by the way workloads have programmed the hardware.

enumerator ZES_RAS_ERROR_CATEGORY_EXP_DRIVER_ERRORS#

The number of low level driver communication errors have occurred.

enumerator ZES_RAS_ERROR_CATEGORY_EXP_COMPUTE_ERRORS#

The number of errors that have occurred in the compute accelerator hardware

enumerator ZES_RAS_ERROR_CATEGORY_EXP_NON_COMPUTE_ERRORS#

The number of errors that have occurred in the fixed-function accelerator hardware.

enumerator ZES_RAS_ERROR_CATEGORY_EXP_CACHE_ERRORS#

The number of errors that have occurred in caches (L1/L3/register file/shared local memory/sampler).

enumerator ZES_RAS_ERROR_CATEGORY_EXP_DISPLAY_ERRORS#

The number of errors that have occurred in the display.

enumerator ZES_RAS_ERROR_CATEGORY_EXP_MEMORY_ERRORS#

The number of errors that have occurred in Memory Subsystem.

enumerator ZES_RAS_ERROR_CATEGORY_EXP_SCALE_ERRORS#

The number of errors that have occurred in Scale Fabric.

enumerator ZES_RAS_ERROR_CATEGORY_EXP_L3FABRIC_ERRORS#

The number of errors that have occurred in L3 Fabric.

enumerator ZES_RAS_ERROR_CATEGORY_EXP_PCIE_ERRORS#

The number of errors that have occurred in the PCIe subsystem. (since v1.16)

enumerator ZES_RAS_ERROR_CATEGORY_EXP_FABRIC_ERRORS#

The number of errors that have occurred in the Fabric interconnect in the SOC (since v1.16)

enumerator ZES_RAS_ERROR_CATEGORY_EXP_SOC_INTERNAL_ERRORS#

The number of errors that have occurred in the SOC internal components. (since v1.16)

enumerator ZES_RAS_ERROR_CATEGORY_EXP_FORCE_UINT32#

Value marking end of ZES_RAS_ERROR_CATEGORY_EXP_* ENUMs.

Ras - Experimental Structures#

zes_ras_state_exp_t#

Added in version 1.7

struct zes_ras_state_exp_t#

Extension structure for providing RAS error counters for different error sets.

Public Members

zes_ras_error_category_exp_t category#

[out] category for which error counter is provided.

uint64_t errorCounter#

[out] Current value of RAS counter for specific error category.

zes_ras_state_exp2_t#

Added in version 1.16

struct zes_ras_state_exp2_t#

Extension structure for providing RAS error counters.

Public Members

zes_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

uint64_t errorCounter#

[out] Current value of RAS counter for the corresponding error category.

zes_ras_config_exp_t#

Added in version 1.16

struct zes_ras_config_exp_t#

RAS error configuration for per-category threshold management.

Public Members

zes_structure_type_t stype#

[in] type of this structure

const void *pNext#

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

zes_ras_error_category_exp_t category#

[in] RAS error category for which threshold is being configured.

uint64_t threshold#

[in,out] Error count threshold to trigger RAS events. A value of 0 disables event triggering for this category.