Device - Extensions

Contents

Device - Extensions#

oneAPI Level Zero Specification - Version 1.20.41

Device - Extension Functions#

zesDeviceResetExt#

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceResetExt(zes_device_handle_t hDevice, zes_reset_properties_t *pProperties)#

Reset device extension.

  • Performs a PCI bus reset of the device. This will result in all current device state being lost.

  • Prior to calling this function, user is responsible for closing applications using the device unless force argument is specified.

  • If the force argument is specified, all applications using the device will be forcibly killed.

  • The function will block until the device has restarted or a implementation specific timeout occurred waiting for the reset to complete.

Parameters:

  • hDevice – [in] Sysman handle for the device

  • pProperties – [in] Device reset properties to apply

Returns:

zesDevicePciLinkSpeedUpdateExt#

Added in version 1.15

ZE_APIEXPORT ze_result_t ZE_APICALL zesDevicePciLinkSpeedUpdateExt(zes_device_handle_t hDevice, ze_bool_t shouldDowngrade, zes_device_action_t *pendingAction)#

Update PCI Link Speed (Downgrade or Upgrade (restore to its default speed))

  • This function allows updating the PCI link speed to downgrade or upgrade (restore to its default speed) the connection.

Parameters:

  • hDevice – [in] Sysman handle of the device.

  • shouldDowngrade – [in] boolean value to decide whether to perform PCIe downgrade(true) or set to default speed(false)

  • pendingAction – [out] Pending action

Returns:

zesDeviceGetHealthStatusExt#

Added in version 1.18

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceGetHealthStatusExt(zes_device_handle_t hDevice, zes_device_health_status_ext_t *pHealth)#

Get device health status.

  • This function retrieves the current health status of the device.

  • The health status is stored in non-volatile memory and persists across resets and updates.

  • The health indicator serves purely as telemetry without downstream functional effects.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] Sysman handle of the device.

  • pHealth – [out] Current health status of the device.

Returns:

zesDeviceSetHealthStatusExt#

Added in version 1.18

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceSetHealthStatusExt(zes_device_handle_t hDevice, zes_device_health_status_ext_t health)#

Set device health status.

  • This function sets the health status of the device.

  • The health status is persisted to non-volatile memory.

  • Setting health status requires appropriate permissions.

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

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

Parameters:

  • hDevice – [in] Sysman handle of the device.

  • health – [in] New health status to be set for the device.

Returns:

Device - Extension Enums#

zes_device_state_ext_flags_t#

Added in version 1.17

enum zes_device_state_ext_flag_t#

Values:

enumerator ZES_DEVICE_STATE_EXT_FLAG_NORMAL#

The device is operating normally.

enumerator ZES_DEVICE_STATE_EXT_FLAG_WEDGED#

The device is wedged.

enumerator ZES_DEVICE_STATE_EXT_FLAG_SURVIVABILITY#

The device is in survivability mode.

enumerator ZES_DEVICE_STATE_EXT_FLAG_FLASH_OVERRIDE#

The device has flash override enabled.

enumerator ZES_DEVICE_STATE_EXT_FLAG_GPU_LOST#

The GPU has fallen off the pci bus or is otherwise inaccessible. (since v1.18)

enumerator ZES_DEVICE_STATE_EXT_FLAG_DRIVER_NOT_LOADED#

No kernel driver is bound to the device. (since v1.18)

enumerator ZES_DEVICE_STATE_EXT_FLAG_FORCE_UINT32#

Value marking end of ZES_DEVICE_STATE_EXT_FLAG_* ENUMs.

zes_device_health_status_ext_t#

Added in version 1.18

enum zes_device_health_status_ext_t#

Device health status.

  • Device health represents a comprehensive assessment of a device’s reliability and expected performance in upcoming operations.

  • The health indicator is stored in non-volatile memory (NVM) and persists across resets and firmware updates.

Values:

enumerator ZES_DEVICE_HEALTH_STATUS_EXT_OK#

Device is healthy with no known issues.

enumerator ZES_DEVICE_HEALTH_STATUS_EXT_WARNING#

Device may have issues, diagnostics recommended.

enumerator ZES_DEVICE_HEALTH_STATUS_EXT_CRITICAL#

Device should not be used until maintenance is performed.

enumerator ZES_DEVICE_HEALTH_STATUS_EXT_FAILED#

Permanent non-recoverable failure; FRU replacement required.

enumerator ZES_DEVICE_HEALTH_STATUS_EXT_FORCE_UINT32#

Value marking end of ZES_DEVICE_HEALTH_STATUS_EXT_* ENUMs.

Device - Extension Structures#

zes_device_ext_properties_t#

Added in version 1.7

struct zes_device_ext_properties_t#

Device 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_uuid_t uuid#

[out] universal unique identifier. Note: uuid obtained from Sysman API is the same as from core API. Subdevices will have their own uuid.

zes_device_type_t type#

[out] generic device type

zes_device_property_flags_t flags#

[out] 0 (none) or a valid combination of zes_device_property_flag_t

zes_device_index_ext_properties_t#

Added in version 1.20

struct zes_device_index_ext_properties_t#

Device Index Properties extension structure.

  • This structure can be passed as an extension to zesDeviceGetProperties via pNext member

  • Returns an integer identifier for the Sysman device handle

  • The device index is set at zesInit(), subsequent calls may add new devices but will not change existing indexes

  • To identify a device across processes or reboots, it is recommended that devices be looked up by their PCI IDs or UUID

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

uint32_t deviceIndex#

[out] Integer identifier for the Sysman device handle.

zes_device_ecc_default_properties_ext_t#

Added in version 1.13

struct zes_device_ecc_default_properties_ext_t#

This structure may be passed to zesDeviceGetEccState as pNext member of zes_device_ecc_properties_t.

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_device_ecc_state_t defaultState#

[out] Default ECC state

zes_device_ext_state_t#

Added in version 1.17

struct zes_device_ext_state_t#

Extension properties for Device State.

  • This structure may be returned from zesDeviceGetState via the pNext member of zes_device_state_t

  • Provides extended device state information including wedged state, survivability mode, flash override status, GPU lost condition, and kernel driver binding status

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_device_state_ext_flags_t flags#

[out] Device state flags. Returns 0 (if state cannot be determined) or a combination of zes_device_state_ext_flags_t

zes_oem_serial_id_ext_properties_t#

Added in version 1.17

struct zes_oem_serial_id_ext_properties_t#

OEM Serial ID Properties structure.

  • This structure can be passed as an extension structure to zesDeviceGetProperties via pNext member

  • Returns the OEM serial ID of the device

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

uint16_t length#

[out] OEM serial ID length

char oemSerialId[ZES_OEM_SERIAL_ID_SIZE]#

[out] OEM serial ID for the device.

zes_device_gpu_topology_ext_properties_t#

Added in version 1.20

struct zes_device_gpu_topology_ext_properties_t#

Device GPU Topology Extension structure.

  • This structure can be passed as an extension structure to zesDeviceGetProperties via pNext member

  • Returns the GPU topology of the device

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

uint32_t numSlices#

[out] Total number of slices across the entire device.

uint32_t numXeCores#

[out] Total number of Xe Cores across the entire device. An Xe Core is what earlier GPU generations call a sub-slice.

uint32_t numVectorEngines#

[out] Total number of vector engines across the entire device. A vector engine is what earlier GPU generations call an EU.

uint32_t numMatrixEngines#

[out] Total number of matrix engines across the entire device.

uint32_t numThreads#

[out] Total number of hardware threads across the entire device.

char generationName[ZES_STRING_PROPERTY_SIZE]#

[out] Name of the GPU generation of the device. This value is human-readable text intended for display and logging purposes only. Applications that make decisions based on the device architecture should instead use an immutable identifier, such as the ipVersion member of ze_device_ip_version_ext_t, the deviceId member of ze_device_properties_t, or the uuid member of zes_device_ext_properties_t.