Ras

Ras#

oneAPI Level Zero Specification - Version 1.18.31

Ras Functions#

zesRasGetProperties#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesRasGetProperties(zes_ras_handle_t hRas, zes_ras_properties_t *pProperties)#

Get RAS properties of a given RAS error set - this enables discovery of the type of RAS error set (correctable/uncorrectable) and if located on a sub-device.

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

  • pProperties – [in,out] Structure describing RAS properties

Returns:

zesRasGetConfig#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesRasGetConfig(zes_ras_handle_t hRas, zes_ras_config_t *pConfig)#

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

Parameters:

  • hRas – [in] Handle for the component.

  • pConfig – [in,out] Will be populed with the current RAS configuration - thresholds used to trigger events

Returns:

zesRasSetConfig#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesRasSetConfig(zes_ras_handle_t hRas, const zes_ras_config_t *pConfig)#

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

Parameters:

  • hRas – [in] Handle for the component.

  • pConfig – [in] Change the RAS configuration - thresholds used to trigger events

Returns:

zesRasGetState#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesRasGetState(zes_ras_handle_t hRas, ze_bool_t clear, zes_ras_state_t *pState)#

Get the current value of RAS error counters for a particular error set.

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

  • Clearing errors requires write permissions.

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

  • clear – [in] Set to 1 to clear the counters of this type

  • pState – [in,out] Breakdown of where errors have occurred

Returns:

Ras Enums#

zes_ras_error_type_t#

Added in version 1.0

enum zes_ras_error_type_t#

RAS error type.

Values:

enumerator ZES_RAS_ERROR_TYPE_CORRECTABLE#

Errors were corrected by hardware.

enumerator ZES_RAS_ERROR_TYPE_UNCORRECTABLE#

Error were not corrected.

enumerator ZES_RAS_ERROR_TYPE_FORCE_UINT32#

Value marking end of ZES_RAS_ERROR_TYPE_* ENUMs.

zes_ras_error_cat_t#

Added in version 1.0

enum zes_ras_error_cat_t#

RAS error categories.

Values:

enumerator ZES_RAS_ERROR_CAT_RESET#

The number of accelerator engine resets attempted by the driver.

enumerator ZES_RAS_ERROR_CAT_PROGRAMMING_ERRORS#

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

enumerator ZES_RAS_ERROR_CAT_DRIVER_ERRORS#

The number of low level driver communication errors have occurred.

enumerator ZES_RAS_ERROR_CAT_COMPUTE_ERRORS#

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

enumerator ZES_RAS_ERROR_CAT_NON_COMPUTE_ERRORS#

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

enumerator ZES_RAS_ERROR_CAT_CACHE_ERRORS#

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

enumerator ZES_RAS_ERROR_CAT_DISPLAY_ERRORS#

The number of errors that have occurred in the display.

enumerator ZES_RAS_ERROR_CAT_FORCE_UINT32#

Value marking end of ZES_RAS_ERROR_CAT_* ENUMs.

Ras Structures#

zes_ras_properties_t#

Added in version 1.0

struct zes_ras_properties_t#

RAS 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).

zes_ras_error_type_t type#

[out] The type of RAS error

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

zes_ras_state_t#

Added in version 1.0

struct zes_ras_state_t#

RAS error details.

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 category[ZES_MAX_RAS_ERROR_CATEGORY_COUNT]#

[in][out] Breakdown of error by category

zes_ras_config_t#

Added in version 1.0

struct zes_ras_config_t#

RAS error configuration - thresholds used for triggering RAS events (ZES_EVENT_TYPE_FLAG_RAS_CORRECTABLE_ERRORS, ZES_EVENT_TYPE_FLAG_RAS_UNCORRECTABLE_ERRORS)

  • The driver maintains a total counter which is updated every time a hardware block covered by the corresponding RAS error set notifies that an error has occurred. When this total count goes above the totalThreshold specified below, a RAS event is triggered.

  • The driver also maintains a counter for each category of RAS error (see zes_ras_state_t for a breakdown). Each time a hardware block of that category notifies that an error has occurred, that corresponding category counter is updated. When it goes above the threshold specified in detailedThresholds, a RAS event is triggered.

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 totalThreshold#

[in,out] If the total RAS errors exceeds this threshold, the event will be triggered. A value of 0ULL disables triggering the event based on the total counter.

zes_ras_state_t detailedThresholds#

[in,out] If the RAS errors for each category exceed the threshold for that category, the event will be triggered. A value of 0ULL will disable an event being triggered for that category.