Device - Extensions

oneAPI Level Zero Specification - Version 1.18.31

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:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pProperties

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

  • User does not have permissions to perform this operation.

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

  • Reset cannot be performed because applications are using this device.

• ZE_RESULT_ERROR_UNKNOWN

  • There were problems unloading the device driver, performing a bus reset or reloading the device driver.

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:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pendingAction

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

  • User does not have permissions to perform this operation.

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:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pHealth

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:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDevice

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • ZES_DEVICE_HEALTH_STATUS_EXT_FAILED < health

• ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

  • User does not have permissions to set health status.

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_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_pci_link_speed_downgrade_ext_state_t

Added in version 1.15

struct zes_pci_link_speed_downgrade_ext_state_t

Query PCIe downgrade status.

• This structure can be passed in the ‘pNext’ of zes_pci_state_t

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

ze_bool_t pciLinkSpeedDowngradeStatus

[out] Returns the current PCIe downgrade status.

zes_pci_link_speed_downgrade_ext_properties_t

Added in version 1.15

struct zes_pci_link_speed_downgrade_ext_properties_t

Query PCIe downgrade capability.

• This structure can be passed in the ‘pNext’ of zes_pci_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).

ze_bool_t pciLinkSpeedUpdateCapable

[out] Returns if PCIe downgrade capability is available.

int32_t maxPciGenSupported

[out] Returns the max supported PCIe generation of the device. -1 indicates the information is not available

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.