Ctrl+K

Sysman API

Contents

Sysman API#

oneAPI Level Zero Specification - Version 1.11

Common#

Common Enums#

zes_structure_type_t#

enum zes_structure_type_t#

Defines structure types.

Values:

enumerator ZES_STRUCTURE_TYPE_DEVICE_PROPERTIES#

zes_device_properties_t

enumerator ZES_STRUCTURE_TYPE_PCI_PROPERTIES#

zes_pci_properties_t

enumerator ZES_STRUCTURE_TYPE_PCI_BAR_PROPERTIES#

zes_pci_bar_properties_t

enumerator ZES_STRUCTURE_TYPE_DIAG_PROPERTIES#

zes_diag_properties_t

enumerator ZES_STRUCTURE_TYPE_ENGINE_PROPERTIES#

zes_engine_properties_t

enumerator ZES_STRUCTURE_TYPE_FABRIC_PORT_PROPERTIES#

zes_fabric_port_properties_t

enumerator ZES_STRUCTURE_TYPE_FAN_PROPERTIES#

zes_fan_properties_t

enumerator ZES_STRUCTURE_TYPE_FIRMWARE_PROPERTIES#

zes_firmware_properties_t

enumerator ZES_STRUCTURE_TYPE_FREQ_PROPERTIES#

zes_freq_properties_t

enumerator ZES_STRUCTURE_TYPE_LED_PROPERTIES#

zes_led_properties_t

enumerator ZES_STRUCTURE_TYPE_MEM_PROPERTIES#

zes_mem_properties_t

enumerator ZES_STRUCTURE_TYPE_PERF_PROPERTIES#

zes_perf_properties_t

enumerator ZES_STRUCTURE_TYPE_POWER_PROPERTIES#

zes_power_properties_t

enumerator ZES_STRUCTURE_TYPE_PSU_PROPERTIES#

zes_psu_properties_t

enumerator ZES_STRUCTURE_TYPE_RAS_PROPERTIES#

zes_ras_properties_t

enumerator ZES_STRUCTURE_TYPE_SCHED_PROPERTIES#

zes_sched_properties_t

enumerator ZES_STRUCTURE_TYPE_SCHED_TIMEOUT_PROPERTIES#

zes_sched_timeout_properties_t

enumerator ZES_STRUCTURE_TYPE_SCHED_TIMESLICE_PROPERTIES#

zes_sched_timeslice_properties_t

enumerator ZES_STRUCTURE_TYPE_STANDBY_PROPERTIES#

zes_standby_properties_t

enumerator ZES_STRUCTURE_TYPE_TEMP_PROPERTIES#

zes_temp_properties_t

enumerator ZES_STRUCTURE_TYPE_DEVICE_STATE#

zes_device_state_t

enumerator ZES_STRUCTURE_TYPE_PROCESS_STATE#

zes_process_state_t

enumerator ZES_STRUCTURE_TYPE_PCI_STATE#

zes_pci_state_t

enumerator ZES_STRUCTURE_TYPE_FABRIC_PORT_CONFIG#

zes_fabric_port_config_t

enumerator ZES_STRUCTURE_TYPE_FABRIC_PORT_STATE#

zes_fabric_port_state_t

enumerator ZES_STRUCTURE_TYPE_FAN_CONFIG#

zes_fan_config_t

enumerator ZES_STRUCTURE_TYPE_FREQ_STATE#

zes_freq_state_t

enumerator ZES_STRUCTURE_TYPE_OC_CAPABILITIES#

zes_oc_capabilities_t

enumerator ZES_STRUCTURE_TYPE_LED_STATE#

zes_led_state_t

enumerator ZES_STRUCTURE_TYPE_MEM_STATE#

zes_mem_state_t

enumerator ZES_STRUCTURE_TYPE_PSU_STATE#

zes_psu_state_t

enumerator ZES_STRUCTURE_TYPE_BASE_STATE#

zes_base_state_t

enumerator ZES_STRUCTURE_TYPE_RAS_CONFIG#

zes_ras_config_t

enumerator ZES_STRUCTURE_TYPE_RAS_STATE#

zes_ras_state_t

enumerator ZES_STRUCTURE_TYPE_TEMP_CONFIG#

zes_temp_config_t

enumerator ZES_STRUCTURE_TYPE_PCI_BAR_PROPERTIES_1_2#

zes_pci_bar_properties_1_2_t

enumerator ZES_STRUCTURE_TYPE_DEVICE_ECC_DESC#

zes_device_ecc_desc_t

enumerator ZES_STRUCTURE_TYPE_DEVICE_ECC_PROPERTIES#

zes_device_ecc_properties_t

enumerator ZES_STRUCTURE_TYPE_POWER_LIMIT_EXT_DESC#

zes_power_limit_ext_desc_t

enumerator ZES_STRUCTURE_TYPE_POWER_EXT_PROPERTIES#

zes_power_ext_properties_t

enumerator ZES_STRUCTURE_TYPE_OVERCLOCK_PROPERTIES#

zes_overclock_properties_t

enumerator ZES_STRUCTURE_TYPE_FABRIC_PORT_ERROR_COUNTERS#

zes_fabric_port_error_counters_t

enumerator ZES_STRUCTURE_TYPE_ENGINE_EXT_PROPERTIES#

zes_engine_ext_properties_t

enumerator ZES_STRUCTURE_TYPE_RESET_PROPERTIES#

zes_reset_properties_t

enumerator ZES_STRUCTURE_TYPE_DEVICE_EXT_PROPERTIES#

zes_device_ext_properties_t

enumerator ZES_STRUCTURE_TYPE_DEVICE_UUID#

zes_uuid_t

enumerator ZES_STRUCTURE_TYPE_POWER_DOMAIN_EXP_PROPERTIES#

zes_power_domain_exp_properties_t

enumerator ZES_STRUCTURE_TYPE_MEM_BANDWIDTH_COUNTER_BITS_EXP_PROPERTIES#

zes_mem_bandwidth_counter_bits_exp_properties_t

enumerator ZES_STRUCTURE_TYPE_MEMORY_PAGE_OFFLINE_STATE_EXP#

zes_mem_page_offline_state_exp_t

enumerator ZES_STRUCTURE_TYPE_SUBDEVICE_EXP_PROPERTIES#

zes_subdevice_exp_properties_t

enumerator ZES_STRUCTURE_TYPE_VF_EXP_PROPERTIES#

zes_vf_exp_properties_t

enumerator ZES_STRUCTURE_TYPE_VF_UTIL_MEM_EXP#

zes_vf_util_mem_exp_t

enumerator ZES_STRUCTURE_TYPE_VF_UTIL_ENGINE_EXP#

zes_vf_util_engine_exp_t

enumerator ZES_STRUCTURE_TYPE_VF_EXP_CAPABILITIES#

zes_vf_exp_capabilities_t

enumerator ZES_STRUCTURE_TYPE_VF_UTIL_MEM_EXP2#

zes_vf_util_mem_exp2_t

enumerator ZES_STRUCTURE_TYPE_VF_UTIL_ENGINE_EXP2#

zes_vf_util_engine_exp2_t

enumerator ZES_STRUCTURE_TYPE_FORCE_UINT32#

Common Structures#

zes_base_properties_t#

struct zes_base_properties_t#

Base for all properties types.

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

struct zes_base_desc_t#

Base for all descriptor types.

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

struct zes_base_state_t#

Base for all state types.

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

struct zes_base_config_t#

Base for all config types.

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

struct zes_base_capability_t#

Base for all capability types.

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

Driver#

Driver Functions#

zesInit#

ZE_APIEXPORT ze_result_t ZE_APICALL zesInit(zes_init_flags_t flags)#

Initialize ‘oneAPI’ System Resource Management (sysman)

  • The application must call this function or zeInit with the ::ZES_ENABLE_SYSMAN environment variable set before calling any other sysman function.

  • If this function is not called then all other sysman functions will return ZE_RESULT_ERROR_UNINITIALIZED.

  • This function will only initialize sysman. To initialize other functions, call zeInit.

  • There is no requirement to call this function before or after zeInit.

  • Only one instance of sysman will be initialized per process.

  • The application must call this function after forking new processes. Each forked process must call this function.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe for scenarios where multiple libraries may initialize sysman simultaneously.

Parameters:

flags – [in] initialization flags. currently unused, must be 0 (default).

Returns:

zesDriverGet#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverGet(uint32_t *pCount, zes_driver_handle_t *phDrivers)#

Retrieves sysman driver instances.

  • A sysman driver represents a collection of physical devices.

  • Multiple calls to this function will return identical sysman driver handles, in the same order.

  • The application may pass nullptr for pDrivers when only querying the number of sysman drivers.

  • The application may call this function from simultaneous threads.

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

Parameters:

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

  • phDrivers – [in,out][optional][range(0, *pCount)] array of sysman driver instance handles. if count is less than the number of sysman drivers available, then the loader shall only retrieve that number of sysman drivers.

Returns:

zesDriverGetExtensionProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverGetExtensionProperties(zes_driver_handle_t hDriver, uint32_t *pCount, zes_driver_extension_properties_t *pExtensionProperties)#

Retrieves extension properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

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

  • pExtensionProperties – [in,out][optional][range(0, *pCount)] array of query results for extension properties. if count is less than the number of extension properties available, then driver shall only retrieve that number of extension properties.

Returns:

zesDriverGetExtensionFunctionAddress#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverGetExtensionFunctionAddress(zes_driver_handle_t hDriver, const char *name, void **ppFunctionAddress)#

Retrieves function pointer for vendor-specific or experimental extensions.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

  • name – [in] extension function name

  • ppFunctionAddress – [out] pointer to function pointer

Returns:

Driver Enums#

zes_init_flags_t#

enum zes_init_flag_t#

Values:

enumerator ZES_INIT_FLAG_PLACEHOLDER#

placeholder for future use

enumerator ZES_INIT_FLAG_FORCE_UINT32#

Driver Structures#

zes_driver_extension_properties_t#

struct zes_driver_extension_properties_t#

Extension properties queried using zesDriverGetExtensionProperties.

Public Members

char name[ZES_MAX_EXTENSION_NAME]#

[out] extension name

uint32_t version#

[out] extension version using ZE_MAKE_VERSION

Device#

Device Functions#

zesDeviceGet#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceGet(zes_driver_handle_t hDriver, uint32_t *pCount, zes_device_handle_t *phDevices)#

Retrieves sysman devices within a sysman driver.

  • Multiple calls to this function will return identical sysman device handles, in the same order.

  • The number and order of handles returned from this function is NOT affected by the ::ZE_AFFINITY_MASK, ::ZE_ENABLE_PCI_ID_DEVICE_ORDER, or ::ZE_FLAT_DEVICE_HIERARCHY environment variables.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the sysman driver instance

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

  • phDevices – [in,out][optional][range(0, *pCount)] array of handle of sysman devices. if count is less than the number of sysman devices available, then driver shall only retrieve that number of sysman devices.

Returns:

zesDeviceGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceGetProperties(zes_device_handle_t hDevice, zes_device_properties_t *pProperties)#

Get properties about the device.

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

  • pProperties – [in,out] Structure that will contain information about the device.

Returns:

zesDeviceGetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceGetState(zes_device_handle_t hDevice, zes_device_state_t *pState)#

Get information about the state of the device - if a reset is required, reasons for the reset and if the device has been repaired.

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

  • pState – [in,out] Structure that will contain information about the device.

Returns:

zesDeviceReset#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceReset(zes_device_handle_t hDevice, ze_bool_t force)#

Reset device.

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

  • All applications using the device should be stopped before calling this function.

  • 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 an implementation defined timeout occurred waiting for the reset to complete.

Parameters:

  • hDevice – [in] Sysman handle for the device

  • force – [in] If set to true, all applications that are currently using the device will be forcibly killed.

Returns:

zesDeviceResetExt#

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:

zesDeviceProcessesGetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceProcessesGetState(zes_device_handle_t hDevice, uint32_t *pCount, zes_process_state_t *pProcesses)#

Get information about host processes using the device.

  • The number of processes connected to the device is dynamic. This means that between a call to determine the value of pCount and the subsequent call, the number of processes may have increased or decreased. It is recommended that a large array be passed in so as to avoid receiving the error ZE_RESULT_ERROR_INVALID_SIZE. Also, always check the returned value in pCount since it may be less than the earlier call to get the required array size.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] Sysman handle for the device

  • pCount – [in,out] pointer to the number of processes. if count is zero, then the driver shall update the value with the total number of processes currently attached to the device. if count is greater than the number of processes currently attached to the device, then the driver shall update the value with the correct number of processes.

  • pProcesses – [in,out][optional][range(0, *pCount)] array of process information. if count is less than the number of processes currently attached to the device, then the driver shall only retrieve information about that number of processes. In this case, the return code will ZE_RESULT_ERROR_INVALID_SIZE.

Returns:

zesDevicePciGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDevicePciGetProperties(zes_device_handle_t hDevice, zes_pci_properties_t *pProperties)#

Get PCI properties - address, max speed.

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

  • pProperties – [in,out] Will contain the PCI properties.

Returns:

zesDevicePciGetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDevicePciGetState(zes_device_handle_t hDevice, zes_pci_state_t *pState)#

Get current PCI state - current speed.

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

  • pState – [in,out] Will contain the PCI properties.

Returns:

zesDevicePciGetBars#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDevicePciGetBars(zes_device_handle_t hDevice, uint32_t *pCount, zes_pci_bar_properties_t *pProperties)#

Get information about each configured bar.

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

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

  • pProperties – [in,out][optional][range(0, *pCount)] array of information about setup PCI bars. if count is less than the number of PCI bars that are setup, then the driver shall only retrieve information about that number of PCI bars.

Returns:

zesDevicePciGetStats#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDevicePciGetStats(zes_device_handle_t hDevice, zes_pci_stats_t *pStats)#

Get PCI stats - bandwidth, number of packets, number of replays.

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

  • pStats – [in,out] Will contain a snapshot of the latest stats.

Returns:

Device Enums#

zes_engine_type_flags_t#

enum zes_engine_type_flag_t#

Values:

enumerator ZES_ENGINE_TYPE_FLAG_OTHER#

Undefined types of accelerators.

enumerator ZES_ENGINE_TYPE_FLAG_COMPUTE#

Engines that process compute kernels only (no 3D content).

enumerator ZES_ENGINE_TYPE_FLAG_3D#

Engines that process 3D content only (no compute kernels).

enumerator ZES_ENGINE_TYPE_FLAG_MEDIA#

Engines that process media workloads.

enumerator ZES_ENGINE_TYPE_FLAG_DMA#

Engines that copy blocks of data.

enumerator ZES_ENGINE_TYPE_FLAG_RENDER#

Engines that can process both 3D content and compute kernels.

enumerator ZES_ENGINE_TYPE_FLAG_FORCE_UINT32#

zes_repair_status_t#

enum zes_repair_status_t#

Device repair status.

Values:

enumerator ZES_REPAIR_STATUS_UNSUPPORTED#

The device does not support in-field repairs.

enumerator ZES_REPAIR_STATUS_NOT_PERFORMED#

The device has never been repaired.

enumerator ZES_REPAIR_STATUS_PERFORMED#

The device has been repaired.

enumerator ZES_REPAIR_STATUS_FORCE_UINT32#

zes_reset_reason_flags_t#

enum zes_reset_reason_flag_t#

Values:

enumerator ZES_RESET_REASON_FLAG_WEDGED#

The device needs to be reset because one or more parts of the hardware is wedged

enumerator ZES_RESET_REASON_FLAG_REPAIR#

The device needs to be reset in order to complete in-field repairs.

enumerator ZES_RESET_REASON_FLAG_FORCE_UINT32#

zes_reset_type_t#

enum zes_reset_type_t#

Device reset type.

Values:

enumerator ZES_RESET_TYPE_WARM#

Apply warm reset.

enumerator ZES_RESET_TYPE_COLD#

Apply cold reset.

enumerator ZES_RESET_TYPE_FLR#

Apply FLR reset.

enumerator ZES_RESET_TYPE_FORCE_UINT32#

zes_device_type_t#

enum zes_device_type_t#

Supported device types.

Values:

enumerator ZES_DEVICE_TYPE_GPU#

Graphics Processing Unit.

enumerator ZES_DEVICE_TYPE_CPU#

Central Processing Unit.

enumerator ZES_DEVICE_TYPE_FPGA#

Field Programmable Gate Array.

enumerator ZES_DEVICE_TYPE_MCA#

Memory Copy Accelerator.

enumerator ZES_DEVICE_TYPE_VPU#

Vision Processing Unit.

enumerator ZES_DEVICE_TYPE_FORCE_UINT32#

zes_device_property_flags_t#

enum zes_device_property_flag_t#

Values:

enumerator ZES_DEVICE_PROPERTY_FLAG_INTEGRATED#

Device is integrated with the Host.

enumerator ZES_DEVICE_PROPERTY_FLAG_SUBDEVICE#

Device handle used for query represents a sub-device.

enumerator ZES_DEVICE_PROPERTY_FLAG_ECC#

Device supports error correction memory access.

enumerator ZES_DEVICE_PROPERTY_FLAG_ONDEMANDPAGING#

Device supports on-demand page-faulting.

enumerator ZES_DEVICE_PROPERTY_FLAG_FORCE_UINT32#

zes_pci_bar_type_t#

enum zes_pci_bar_type_t#

PCI bar types.

Values:

enumerator ZES_PCI_BAR_TYPE_MMIO#

MMIO registers.

enumerator ZES_PCI_BAR_TYPE_ROM#

ROM aperture.

enumerator ZES_PCI_BAR_TYPE_MEM#

Device memory.

enumerator ZES_PCI_BAR_TYPE_FORCE_UINT32#

Device Structures#

zes_device_state_t#

struct zes_device_state_t#

Device state.

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_reset_reason_flags_t reset#

[out] Indicates if the device needs to be reset and for what reasons. returns 0 (none) or combination of zes_reset_reason_flag_t

zes_repair_status_t repaired#

[out] Indicates if the device has been repaired

zes_reset_properties_t#

struct zes_reset_properties_t#

Device reset 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 force#

[in] If set to true, all applications that are currently using the device will be forcibly killed.

zes_reset_type_t resetType#

[in] Type of reset needs to be performed

zes_uuid_t#

struct zes_uuid_t#

Device universal unique id (UUID)

Public Members

uint8_t id[ZES_MAX_UUID_SIZE]#

[out] opaque data representing a device UUID

zes_device_properties_t#

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

ze_device_properties_t core#

[out] (Deprecated, use zes_uuid_t in the extended structure) Core device properties

uint32_t numSubdevices#

[out] Number of sub-devices. A value of 0 indicates that this device doesn’t have sub-devices.

char serialNumber[ZES_STRING_PROPERTY_SIZE]#

[out] Manufacturing serial number (NULL terminated string value). This value is intended to reflect the Part ID/SoC ID assigned by manufacturer that is unique for a SoC. Will be set to the string “unknown” if this cannot be determined for the device.

char boardNumber[ZES_STRING_PROPERTY_SIZE]#

[out] Manufacturing board number (NULL terminated string value). Alternatively “boardSerialNumber”, this value is intended to reflect the string printed on board label by manufacturer. Will be set to the string “unknown” if this cannot be determined for the device.

char brandName[ZES_STRING_PROPERTY_SIZE]#

[out] Brand name of the device (NULL terminated string value). Will be set to the string “unknown” if this cannot be determined for the device.

char modelName[ZES_STRING_PROPERTY_SIZE]#

[out] Model name of the device (NULL terminated string value). Will be set to the string “unknown” if this cannot be determined for the device.

char vendorName[ZES_STRING_PROPERTY_SIZE]#

[out] Vendor name of the device (NULL terminated string value). Will be set to the string “unknown” if this cannot be determined for the device.

char driverVersion[ZES_STRING_PROPERTY_SIZE]#

[out] Installed driver version (NULL terminated string value). Will be set to the string “unknown” if this cannot be determined for the device.

zes_device_ext_properties_t#

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

struct zes_process_state_t#

Contains information about a process that has an open connection with this device.

  • The application can use the process ID to query the OS for the owner and the path to the executable.

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

uint32_t processId#

[out] Host OS process ID.

uint64_t memSize#

[out] Device memory size in bytes allocated by this process (may not necessarily be resident on the device at the time of reading).

uint64_t sharedSize#

[out] The size of shared device memory mapped into this process (may not necessarily be resident on the device at the time of reading).

zes_engine_type_flags_t engines#

[out] Bitfield of accelerator engine types being used by this process.

zes_pci_address_t#

struct zes_pci_address_t#

PCI address.

Public Members

uint32_t domain#

[out] BDF domain

uint32_t bus#

[out] BDF bus

uint32_t device#

[out] BDF device

uint32_t function#

[out] BDF function

zes_pci_speed_t#

struct zes_pci_speed_t#

PCI speed.

Public Members

int32_t gen#

[out] The link generation. A value of -1 means that this property is unknown.

int32_t width#

[out] The number of lanes. A value of -1 means that this property is unknown.

int64_t maxBandwidth#

[out] The maximum bandwidth in bytes/sec (sum of all lanes). A value of -1 means that this property is unknown.

zes_pci_properties_t#

struct zes_pci_properties_t#

Static PCI 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_pci_address_t address#

[out] The BDF address

zes_pci_speed_t maxSpeed#

[out] Fastest port configuration supported by the device (sum of all lanes)

ze_bool_t haveBandwidthCounters#

[out] Indicates whether the rxCounter and txCounter members of zes_pci_stats_t will have valid values

ze_bool_t havePacketCounters#

[out] Indicates whether the packetCounter member of zes_pci_stats_t will have a valid value

ze_bool_t haveReplayCounters#

[out] Indicates whether the replayCounter member of zes_pci_stats_t will have a valid value

zes_pci_state_t#

struct zes_pci_state_t#

Dynamic PCI state.

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_pci_link_status_t status#

[out] The current status of the port

zes_pci_link_qual_issue_flags_t qualityIssues#

[out] If status is ZES_PCI_LINK_STATUS_QUALITY_ISSUES, then this gives a combination of zes_pci_link_qual_issue_flag_t for quality issues that have been detected; otherwise, 0 indicates there are no quality issues with the link at this time.”

zes_pci_link_stab_issue_flags_t stabilityIssues#

[out] If status is ZES_PCI_LINK_STATUS_STABILITY_ISSUES, then this gives a combination of zes_pci_link_stab_issue_flag_t for reasons for the connection instability; otherwise, 0 indicates there are no connection stability issues at this time.”

zes_pci_speed_t speed#

[out] The current port configure speed

zes_pci_bar_properties_t#

struct zes_pci_bar_properties_t#

Properties of a pci bar.

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_pci_bar_type_t type#

[out] The type of bar

uint32_t index#

[out] The index of the bar

uint64_t base#

[out] Base address of the bar.

uint64_t size#

[out] Size of the bar.

zes_pci_bar_properties_1_2_t#

struct zes_pci_bar_properties_1_2_t#

Properties of a pci bar, including the resizable bar.

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_pci_bar_type_t type#

[out] The type of bar

uint32_t index#

[out] The index of the bar

uint64_t base#

[out] Base address of the bar.

uint64_t size#

[out] Size of the bar.

ze_bool_t resizableBarSupported#

[out] Support for Resizable Bar on this device.

ze_bool_t resizableBarEnabled#

[out] Resizable Bar enabled on this device

zes_pci_stats_t#

struct zes_pci_stats_t#

PCI stats counters.

  • Percent replays is calculated by taking two snapshots (s1, s2) and using the equation: replay = 10^6 * (s2.replayCounter - s1.replayCounter) / (s2.maxBandwidth * (s2.timestamp - s1.timestamp))

  • Percent throughput is calculated by taking two snapshots (s1, s2) and using the equation: bw = 10^6 * ((s2.rxCounter - s1.rxCounter) + (s2.txCounter - s1.txCounter)) / (s2.maxBandwidth * (s2.timestamp - s1.timestamp))

Public Members

uint64_t timestamp#

[out] Monotonic timestamp counter in microseconds when the measurement was made. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

uint64_t replayCounter#

[out] Monotonic counter for the number of replay packets (sum of all lanes). Will always be 0 when the haveReplayCounters member of zes_pci_properties_t is FALSE.

uint64_t packetCounter#

[out] Monotonic counter for the number of packets (sum of all lanes). Will always be 0 when the havePacketCounters member of zes_pci_properties_t is FALSE.

uint64_t rxCounter#

[out] Monotonic counter for the number of bytes received (sum of all lanes). Will always be 0 when the haveBandwidthCounters member of zes_pci_properties_t is FALSE.

uint64_t txCounter#

[out] Monotonic counter for the number of bytes transmitted (including replays) (sum of all lanes). Will always be 0 when the haveBandwidthCounters member of zes_pci_properties_t is FALSE.

zes_pci_speed_t speed#

[out] The current speed of the link (sum of all lanes)

Overclock#

Overclock Functions#

zesDeviceSetOverclockWaiver#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceSetOverclockWaiver(zes_device_handle_t hDevice)#

Set the overclock waiver.The overclock waiver setting is persistent until the next pcode boot.

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

Returns:

zesDeviceGetOverclockDomains#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceGetOverclockDomains(zes_device_handle_t hDevice, uint32_t *pOverclockDomains)#

Get the list of supported overclock domains for this device.

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

  • pOverclockDomains – [in,out] Returns the overclock domains that are supported (a bit for each of enum zes_overclock_domain_t). If no bits are set, the device doesn’t support overclocking.

Returns:

zesDeviceGetOverclockControls#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceGetOverclockControls(zes_device_handle_t hDevice, zes_overclock_domain_t domainType, uint32_t *pAvailableControls)#

Get the list of supported overclock controls available for one of the supported overclock domains on the device.

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

  • domainType – [in] Domain type.

  • pAvailableControls – [in,out] Returns the overclock controls that are supported for the specified overclock domain (a bit for each of enum zes_overclock_control_t).

Returns:

zesDeviceResetOverclockSettings#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceResetOverclockSettings(zes_device_handle_t hDevice, ze_bool_t onShippedState)#

Reset all overclock settings to default values (shipped = 1 or manufacturing =0)

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

  • onShippedState – [in] True will reset to shipped state; false will reset to manufacturing state

Returns:

zesDeviceReadOverclockState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceReadOverclockState(zes_device_handle_t hDevice, zes_overclock_mode_t *pOverclockMode, ze_bool_t *pWaiverSetting, ze_bool_t *pOverclockState, zes_pending_action_t *pPendingAction, ze_bool_t *pPendingReset)#

Determine the state of overclocking.

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

  • pOverclockMode – [out] One of overclock mode.

  • pWaiverSetting – [out] Waiver setting: 0 = Waiver not set, 1 = waiver has been set.

  • pOverclockState – [out] Current settings 0 =manufacturing state, 1= shipped state)..

  • pPendingAction – [out] This enum is returned when the driver attempts to set an overclock control or reset overclock settings.

  • pPendingReset – [out] Pending reset 0 =manufacturing state, 1= shipped state)..

Returns:

zesDeviceEnumOverclockDomains#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumOverclockDomains(zes_device_handle_t hDevice, uint32_t *pCount, zes_overclock_handle_t *phDomainHandle)#

Get handle of overclock domains.

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

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

  • phDomainHandle – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesOverclockGetDomainProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesOverclockGetDomainProperties(zes_overclock_handle_t hDomainHandle, zes_overclock_properties_t *pDomainProperties)#

Get overclock domain control properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDomainHandle – [in] Handle for the component domain.

  • pDomainProperties – [in,out] The overclock properties for the specified domain.

Returns:

zesOverclockGetDomainVFProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesOverclockGetDomainVFProperties(zes_overclock_handle_t hDomainHandle, zes_vf_property_t *pVFProperties)#

Read overclock VF min,max and step values.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDomainHandle – [in] Handle for the component domain.

  • pVFProperties – [in,out] The VF min,max,step for a specified domain.

Returns:

zesOverclockGetDomainControlProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesOverclockGetDomainControlProperties(zes_overclock_handle_t hDomainHandle, zes_overclock_control_t DomainControl, zes_control_property_t *pControlProperties)#

Read overclock control values - min/max/step/default/ref.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDomainHandle – [in] Handle for the component domain.

  • DomainControl – [in] Handle for the component.

  • pControlProperties – [in,out] overclock control values.

Returns:

zesOverclockGetControlCurrentValue#

ZE_APIEXPORT ze_result_t ZE_APICALL zesOverclockGetControlCurrentValue(zes_overclock_handle_t hDomainHandle, zes_overclock_control_t DomainControl, double *pValue)#

Read the current value for a given overclock control.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDomainHandle – [in] Handle for the component.

  • DomainControl – [in] Overclock Control.

  • pValue – [in,out] Getting overclock control value for the specified control.

Returns:

zesOverclockGetControlPendingValue#

ZE_APIEXPORT ze_result_t ZE_APICALL zesOverclockGetControlPendingValue(zes_overclock_handle_t hDomainHandle, zes_overclock_control_t DomainControl, double *pValue)#

Read the the reset pending value for a given overclock control.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDomainHandle – [in] Handle for the component domain.

  • DomainControl – [in] Overclock Control.

  • pValue – [out] Returns the pending value for a given control. The units and format of the value depend on the control type.

Returns:

zesOverclockSetControlUserValue#

ZE_APIEXPORT ze_result_t ZE_APICALL zesOverclockSetControlUserValue(zes_overclock_handle_t hDomainHandle, zes_overclock_control_t DomainControl, double pValue, zes_pending_action_t *pPendingAction)#

Set the value for a given overclock control.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDomainHandle – [in] Handle for the component domain.

  • DomainControl – [in] Domain Control.

  • pValue – [in] The new value of the control. The units and format of the value depend on the control type.

  • pPendingAction – [out] Pending overclock setting.

Returns:

zesOverclockGetControlState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesOverclockGetControlState(zes_overclock_handle_t hDomainHandle, zes_overclock_control_t DomainControl, zes_control_state_t *pControlState, zes_pending_action_t *pPendingAction)#

Determine the state of an overclock control.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDomainHandle – [in] Handle for the component domain.

  • DomainControl – [in] Domain Control.

  • pControlState – [out] Current overclock control state.

  • pPendingAction – [out] Pending overclock setting.

Returns:

zesOverclockGetVFPointValues#

ZE_APIEXPORT ze_result_t ZE_APICALL zesOverclockGetVFPointValues(zes_overclock_handle_t hDomainHandle, zes_vf_type_t VFType, zes_vf_array_type_t VFArrayType, uint32_t PointIndex, uint32_t *PointValue)#

Read the frequency or voltage of a V-F point from the default or custom V-F curve.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDomainHandle – [in] Handle for the component domain.

  • VFType – [in] Voltage or Freqency point to read.

  • VFArrayType – [in] User,Default or Live VF array to read from

  • PointIndex – [in] Point index - number between (0, max_num_points - 1).

  • PointValue – [out] Returns the frequency in 1kHz units or voltage in millivolt units from the custom V-F curve at the specified zero-based index

Returns:

zesOverclockSetVFPointValues#

ZE_APIEXPORT ze_result_t ZE_APICALL zesOverclockSetVFPointValues(zes_overclock_handle_t hDomainHandle, zes_vf_type_t VFType, uint32_t PointIndex, uint32_t PointValue)#

Write the frequency or voltage of a V-F point to custom V-F curve.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDomainHandle – [in] Handle for the component domain.

  • VFType – [in] Voltage or Freqency point to read.

  • PointIndex – [in] Point index - number between (0, max_num_points - 1).

  • PointValue – [in] Writes frequency in 1kHz units or voltage in millivolt units to custom V-F curve at the specified zero-based index

Returns:

Overclock Enums#

zes_overclock_domain_t#

enum zes_overclock_domain_t#

Overclock domains.

Values:

enumerator ZES_OVERCLOCK_DOMAIN_CARD#

Overclocking card level properties such as temperature limits.

enumerator ZES_OVERCLOCK_DOMAIN_PACKAGE#

Overclocking package level properties such as power limits.

enumerator ZES_OVERCLOCK_DOMAIN_GPU_ALL#

Overclocking a GPU that has all accelerator assets on the same PLL/VR.

enumerator ZES_OVERCLOCK_DOMAIN_GPU_RENDER_COMPUTE#

Overclocking a GPU with render and compute assets on the same PLL/VR.

enumerator ZES_OVERCLOCK_DOMAIN_GPU_RENDER#

Overclocking a GPU with render assets on its own PLL/VR.

enumerator ZES_OVERCLOCK_DOMAIN_GPU_COMPUTE#

Overclocking a GPU with compute assets on its own PLL/VR.

enumerator ZES_OVERCLOCK_DOMAIN_GPU_MEDIA#

Overclocking a GPU with media assets on its own PLL/VR.

enumerator ZES_OVERCLOCK_DOMAIN_VRAM#

Overclocking device local memory.

enumerator ZES_OVERCLOCK_DOMAIN_ADM#

Overclocking LLC/L4 cache.

enumerator ZES_OVERCLOCK_DOMAIN_FORCE_UINT32#

zes_overclock_control_t#

enum zes_overclock_control_t#

Overclock controls.

Values:

enumerator ZES_OVERCLOCK_CONTROL_VF#

This control permits setting a custom V-F curve.

enumerator ZES_OVERCLOCK_CONTROL_FREQ_OFFSET#

The V-F curve of the overclock domain can be shifted up or down using this control.

enumerator ZES_OVERCLOCK_CONTROL_VMAX_OFFSET#

This control is used to increase the permitted voltage above the shipped voltage maximum.

enumerator ZES_OVERCLOCK_CONTROL_FREQ#

This control permits direct changes to the operating frequency.

enumerator ZES_OVERCLOCK_CONTROL_VOLT_LIMIT#

This control prevents frequencies that would push the voltage above this value, typically used by V-F scanners.

enumerator ZES_OVERCLOCK_CONTROL_POWER_SUSTAINED_LIMIT#

This control changes the sustained power limit (PL1).

enumerator ZES_OVERCLOCK_CONTROL_POWER_BURST_LIMIT#

This control changes the burst power limit (PL2).

enumerator ZES_OVERCLOCK_CONTROL_POWER_PEAK_LIMIT#

his control changes the peak power limit (PL4).

enumerator ZES_OVERCLOCK_CONTROL_ICCMAX_LIMIT#

This control changes the value of IccMax..

enumerator ZES_OVERCLOCK_CONTROL_TEMP_LIMIT#

This control changes the value of TjMax.

enumerator ZES_OVERCLOCK_CONTROL_ITD_DISABLE#

This control permits disabling the adaptive voltage feature ITD.

enumerator ZES_OVERCLOCK_CONTROL_ACM_DISABLE#

This control permits disabling the adaptive voltage feature ACM.

enumerator ZES_OVERCLOCK_CONTROL_FORCE_UINT32#

zes_overclock_mode_t#

enum zes_overclock_mode_t#

Overclock modes.

Values:

enumerator ZES_OVERCLOCK_MODE_MODE_OFF#

Overclock mode is off.

enumerator ZES_OVERCLOCK_MODE_MODE_STOCK#

Stock (manufacturing settings) are being used.

enumerator ZES_OVERCLOCK_MODE_MODE_ON#

Overclock mode is on.

enumerator ZES_OVERCLOCK_MODE_MODE_UNAVAILABLE#

Overclocking is unavailable at this time since the system is running on battery.

enumerator ZES_OVERCLOCK_MODE_MODE_DISABLED#

Overclock mode is disabled.

enumerator ZES_OVERCLOCK_MODE_FORCE_UINT32#

zes_control_state_t#

enum zes_control_state_t#

Overclock control states.

Values:

enumerator ZES_CONTROL_STATE_STATE_UNSET#

No overclock control has not been changed by the driver since the last boot/reset.

enumerator ZES_CONTROL_STATE_STATE_ACTIVE#

The overclock control has been set and it is active.

enumerator ZES_CONTROL_STATE_STATE_DISABLED#

The overclock control value has been disabled due to the current power configuration (typically when running on DC).

enumerator ZES_CONTROL_STATE_FORCE_UINT32#

zes_pending_action_t#

enum zes_pending_action_t#

Overclock pending actions.

Values:

enumerator ZES_PENDING_ACTION_PENDING_NONE#

There no pending actions. .

enumerator ZES_PENDING_ACTION_PENDING_IMMINENT#

The requested change is in progress and should complete soon.

enumerator ZES_PENDING_ACTION_PENDING_COLD_RESET#

The requested change requires a device cold reset (hotplug, system boot).

enumerator ZES_PENDING_ACTION_PENDING_WARM_RESET#

The requested change requires a device warm reset (PCIe FLR).

enumerator ZES_PENDING_ACTION_FORCE_UINT32#

zes_vf_program_type_t#

enum zes_vf_program_type_t#

Overclock V-F curve programing.

Values:

enumerator ZES_VF_PROGRAM_TYPE_VF_ARBITRARY#

Can program an arbitrary number of V-F points up to the maximum number and each point can have arbitrary voltage and frequency values within the min/max/step limits

enumerator ZES_VF_PROGRAM_TYPE_VF_FREQ_FIXED#

Can only program the voltage for the V-F points that it reads back - the frequency of those points cannot be changed

enumerator ZES_VF_PROGRAM_TYPE_VF_VOLT_FIXED#

Can only program the frequency for the V-F points that is reads back - the voltage of each point cannot be changed.

enumerator ZES_VF_PROGRAM_TYPE_FORCE_UINT32#

zes_vf_type_t#

enum zes_vf_type_t#

VF type.

Values:

enumerator ZES_VF_TYPE_VOLT#

VF Voltage point.

enumerator ZES_VF_TYPE_FREQ#

VF Frequency point.

enumerator ZES_VF_TYPE_FORCE_UINT32#

zes_vf_array_type_t#

enum zes_vf_array_type_t#

VF type.

Values:

enumerator ZES_VF_ARRAY_TYPE_USER_VF_ARRAY#

User V-F array.

enumerator ZES_VF_ARRAY_TYPE_DEFAULT_VF_ARRAY#

Default V-F array.

enumerator ZES_VF_ARRAY_TYPE_LIVE_VF_ARRAY#

Live V-F array.

enumerator ZES_VF_ARRAY_TYPE_FORCE_UINT32#

Overclock Structures#

zes_overclock_properties_t#

struct zes_overclock_properties_t#

Overclock properties.

  • Information on the overclock domain type and all the contols that are part of the domain.

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_overclock_domain_t domainType#

[out] The hardware block that this overclock domain controls (GPU, VRAM, …)

uint32_t AvailableControls#

[out] Returns the overclock controls that are supported (a bit for each of enum zes_overclock_control_t). If no bits are set, the domain doesn’t support overclocking.

zes_vf_program_type_t VFProgramType#

[out] Type of V-F curve programming that is permitted:.

uint32_t NumberOfVFPoints#

[out] Number of VF points that can be programmed - max_num_points

zes_control_property_t#

struct zes_control_property_t#

Overclock Control properties.

  • Provides all the control capabilities supported by the device for the overclock domain.

Public Members

double MinValue#

[out] This provides information about the limits of the control value so that the driver can calculate the set of valid values.

double MaxValue#

[out] This provides information about the limits of the control value so that the driver can calculate the set of valid values.

double StepValue#

[out] This provides information about the limits of the control value so that the driver can calculate the set of valid values.

double RefValue#

[out] The reference value provides the anchor point, UIs can combine this with the user offset request to show the anticipated improvement.

double DefaultValue#

[out] The shipped out-of-box position of this control. Driver can request this value at any time to return to the out-of-box behavior.

zes_vf_property_t#

struct zes_vf_property_t#

Overclock VF properties.

  • Provides all the VF capabilities supported by the device for the overclock domain.

Public Members

double MinFreq#

[out] Read the minimum frequency that can be be programmed in the custom V-F point..

double MaxFreq#

[out] Read the maximum frequency that can be be programmed in the custom V-F point..

double StepFreq#

[out] Read the frequency step that can be be programmed in the custom V-F point..

double MinVolt#

[out] Read the minimum voltage that can be be programmed in the custom V-F point..

double MaxVolt#

[out] Read the maximum voltage that can be be programmed in the custom V-F point..

double StepVolt#

[out] Read the voltage step that can be be programmed in the custom V-F point.

Diagnostics#

Diagnostics Functions#

zesDeviceEnumDiagnosticTestSuites#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumDiagnosticTestSuites(zes_device_handle_t hDevice, uint32_t *pCount, zes_diag_handle_t *phDiagnostics)#

Get handle of diagnostics test suites.

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

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

  • phDiagnostics – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesDiagnosticsGetProperties#

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#

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#

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#

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#

Diagnostics Structures#

zes_diag_test_t#

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#

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)

Ecc#

Ecc Functions#

zesDeviceEccAvailable#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEccAvailable(zes_device_handle_t hDevice, ze_bool_t *pAvailable)#

Is ECC functionality available - true or false?

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] Handle for the component.

  • pAvailable – [out] ECC functionality is available (true)/unavailable (false).

Returns:

zesDeviceEccConfigurable#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEccConfigurable(zes_device_handle_t hDevice, ze_bool_t *pConfigurable)#

Is ECC support configurable - true or false?

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] Handle for the component.

  • pConfigurable – [out] ECC can be enabled/disabled (true)/enabled/disabled (false).

Returns:

zesDeviceGetEccState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceGetEccState(zes_device_handle_t hDevice, zes_device_ecc_properties_t *pState)#

Get current ECC state, pending state, and pending action.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] Handle for the component.

  • pState – [out] ECC state, pending state, and pending action for state change.

Returns:

zesDeviceSetEccState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceSetEccState(zes_device_handle_t hDevice, const zes_device_ecc_desc_t *newState, zes_device_ecc_properties_t *pState)#

Set new ECC state.

  • The application may call this function from simultaneous threads.

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

  • zesDeviceGetState should be called to determine pending action required to implement state change.

Parameters:

  • hDevice – [in] Handle for the component.

  • newState – [in] Pointer to desired ECC state.

  • pState – [out] ECC state, pending state, and pending action for state change.

Returns:

Ecc Enums#

zes_device_ecc_state_t#

enum zes_device_ecc_state_t#

ECC State.

Values:

enumerator ZES_DEVICE_ECC_STATE_UNAVAILABLE#

None.

enumerator ZES_DEVICE_ECC_STATE_ENABLED#

ECC enabled.

enumerator ZES_DEVICE_ECC_STATE_DISABLED#

ECC disabled.

enumerator ZES_DEVICE_ECC_STATE_FORCE_UINT32#

zes_device_action_t#

enum zes_device_action_t#

State Change Requirements.

Values:

enumerator ZES_DEVICE_ACTION_NONE#

No action.

enumerator ZES_DEVICE_ACTION_WARM_CARD_RESET#

Warm reset of the card.

enumerator ZES_DEVICE_ACTION_COLD_CARD_RESET#

Cold reset of the card.

enumerator ZES_DEVICE_ACTION_COLD_SYSTEM_REBOOT#

Cold reboot of the system.

enumerator ZES_DEVICE_ACTION_FORCE_UINT32#

Ecc Structures#

zes_device_ecc_desc_t#

struct zes_device_ecc_desc_t#

ECC State Descriptor.

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_ecc_state_t state#

[out] ECC state

zes_device_ecc_properties_t#

struct zes_device_ecc_properties_t#

ECC State.

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

[out] Current ECC state

zes_device_ecc_state_t pendingState#

[out] Pending ECC state

zes_device_action_t pendingAction#

[out] Pending action

Engine#

Engine Functions#

zesDeviceEnumEngineGroups#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumEngineGroups(zes_device_handle_t hDevice, uint32_t *pCount, zes_engine_handle_t *phEngine)#

Get handle of engine groups.

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

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

  • phEngine – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesEngineGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesEngineGetProperties(zes_engine_handle_t hEngine, zes_engine_properties_t *pProperties)#

Get engine group properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEngine – [in] Handle for the component.

  • pProperties – [in,out] The properties for the specified engine group.

Returns:

zesEngineGetActivity#

ZE_APIEXPORT ze_result_t ZE_APICALL zesEngineGetActivity(zes_engine_handle_t hEngine, zes_engine_stats_t *pStats)#

Get the activity stats for an engine group.

  • This function also returns the engine activity inside a Virtual Machine (VM), in the presence of hardware virtualization (SRIOV)

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEngine – [in] Handle for the component.

  • pStats – [in,out] Will contain a snapshot of the engine group activity counters.

Returns:

Engine Enums#

zes_engine_group_t#

enum zes_engine_group_t#

Accelerator engine groups.

Values:

enumerator ZES_ENGINE_GROUP_ALL#

Access information about all engines combined.

enumerator ZES_ENGINE_GROUP_COMPUTE_ALL#

Access information about all compute engines combined. Compute engines can only process compute kernels (no 3D content).

enumerator ZES_ENGINE_GROUP_MEDIA_ALL#

Access information about all media engines combined.

enumerator ZES_ENGINE_GROUP_COPY_ALL#

Access information about all copy (blitter) engines combined.

enumerator ZES_ENGINE_GROUP_COMPUTE_SINGLE#

Access information about a single compute engine - this is an engine that can process compute kernels. Note that single engines may share the same underlying accelerator resources as other engines so activity of such an engine may not be indicative of the underlying resource utilization - use ZES_ENGINE_GROUP_3D_RENDER_COMPUTE_ALL for that.

enumerator ZES_ENGINE_GROUP_RENDER_SINGLE#

Access information about a single render engine - this is an engine that can process both 3D content and compute kernels. Note that single engines may share the same underlying accelerator resources as other engines so activity of such an engine may not be indicative of the underlying resource utilization - use ZES_ENGINE_GROUP_3D_RENDER_COMPUTE_ALL for that.

enumerator ZES_ENGINE_GROUP_MEDIA_DECODE_SINGLE#

[DEPRECATED] No longer supported.

enumerator ZES_ENGINE_GROUP_MEDIA_ENCODE_SINGLE#

[DEPRECATED] No longer supported.

enumerator ZES_ENGINE_GROUP_COPY_SINGLE#

Access information about a single media encode engine. Note that single engines may share the same underlying accelerator resources as other engines so activity of such an engine may not be indicative of the underlying resource utilization - use ZES_ENGINE_GROUP_COPY_ALL for that.

enumerator ZES_ENGINE_GROUP_MEDIA_ENHANCEMENT_SINGLE#

Access information about a single media enhancement engine. Note that single engines may share the same underlying accelerator resources as other engines so activity of such an engine may not be indicative of the underlying resource utilization - use ZES_ENGINE_GROUP_MEDIA_ALL for that.

enumerator ZES_ENGINE_GROUP_3D_SINGLE#

[DEPRECATED] No longer supported.

enumerator ZES_ENGINE_GROUP_3D_RENDER_COMPUTE_ALL#

[DEPRECATED] No longer supported.

enumerator ZES_ENGINE_GROUP_RENDER_ALL#

Access information about all render engines combined. Render engines are those than process both 3D content and compute kernels.

enumerator ZES_ENGINE_GROUP_3D_ALL#

[DEPRECATED] No longer supported.

enumerator ZES_ENGINE_GROUP_MEDIA_CODEC_SINGLE#

Access information about a single media engine. Note that single engines may share the same underlying accelerator resources as other engines so activity of such an engine may not be indicative of the underlying resource utilization - use ZES_ENGINE_GROUP_MEDIA_ALL for that.

enumerator ZES_ENGINE_GROUP_FORCE_UINT32#

Engine Structures#

zes_engine_properties_t#

struct zes_engine_properties_t#

Engine group 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_engine_group_t type#

[out] The engine group

ze_bool_t onSubdevice#

[out] True if this 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_engine_stats_t#

struct zes_engine_stats_t#

Engine activity counters.

  • Percent utilization is calculated by taking two snapshots (s1, s2) and using the equation: util = (s2.activeTime - s1.activeTime) / (s2.timestamp - s1.timestamp)

  • The activeTime time units are implementation-specific since the value is only intended to be used for calculating utilization percentage.

  • The timestamp should only be used to calculate delta between snapshots of this structure.

  • The application should never take the delta of timestamp with the timestamp from a different structure since they are not guaranteed to have the same base.

  • When taking the delta, the difference between timestamp samples could be 0, if the frequency of sampling the snapshots is higher than the frequency of the timestamp update.

  • The absolute value of timestamp is only valid during within the application and may be different on the next execution.

Public Members

uint64_t activeTime#

[out] Monotonic counter where the resource is actively running workloads.

uint64_t timestamp#

[out] Monotonic counter when activeTime counter was sampled.

Events#

Events Functions#

zesDeviceEventRegister#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEventRegister(zes_device_handle_t hDevice, zes_event_type_flags_t events)#

Specify the list of events to listen to for a given device.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDevice – [in] The device handle.

  • events – [in] List of events to listen to.

Returns:

zesDriverEventListen#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverEventListen(ze_driver_handle_t hDriver, uint32_t timeout, uint32_t count, zes_device_handle_t *phDevices, uint32_t *pNumDeviceEvents, zes_event_type_flags_t *pEvents)#

Wait for events to be received from a one or more devices.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

  • timeout – [in] if non-zero, then indicates the maximum time (in milliseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then will check status and return immediately; if UINT32_MAX, then function will not return until events arrive.

  • count – [in] Number of device handles in phDevices.

  • phDevices – [in][range(0, count)] Device handles to listen to for events. Only devices from the provided driver handle can be specified in this list.

  • pNumDeviceEvents – [in,out] Will contain the actual number of devices in phDevices that generated events. If non-zero, check pEvents to determine the devices and events that were received.

  • pEvents – [in,out] An array that will continue the list of events for each device listened in phDevices. This array must be at least as big as count. For every device handle in phDevices, this will provide the events that occurred for that device at the same position in this array. If no event was received for a given device, the corresponding array entry will be zero.

Returns:

zesDriverEventListenEx#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverEventListenEx(ze_driver_handle_t hDriver, uint64_t timeout, uint32_t count, zes_device_handle_t *phDevices, uint32_t *pNumDeviceEvents, zes_event_type_flags_t *pEvents)#

Wait for events to be received from a one or more devices.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

  • timeout – [in] if non-zero, then indicates the maximum time (in milliseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then will check status and return immediately; if UINT64_MAX, then function will not return until events arrive.

  • count – [in] Number of device handles in phDevices.

  • phDevices – [in][range(0, count)] Device handles to listen to for events. Only devices from the provided driver handle can be specified in this list.

  • pNumDeviceEvents – [in,out] Will contain the actual number of devices in phDevices that generated events. If non-zero, check pEvents to determine the devices and events that were received.

  • pEvents – [in,out] An array that will continue the list of events for each device listened in phDevices. This array must be at least as big as count. For every device handle in phDevices, this will provide the events that occurred for that device at the same position in this array. If no event was received for a given device, the corresponding array entry will be zero.

Returns:

Events Enums#

zes_event_type_flags_t#

enum zes_event_type_flag_t#

Values:

enumerator ZES_EVENT_TYPE_FLAG_DEVICE_DETACH#

Event is triggered when the device is no longer available (due to a reset or being disabled).

enumerator ZES_EVENT_TYPE_FLAG_DEVICE_ATTACH#

Event is triggered after the device is available again.

enumerator ZES_EVENT_TYPE_FLAG_DEVICE_SLEEP_STATE_ENTER#

Event is triggered when the driver is about to put the device into a deep sleep state

enumerator ZES_EVENT_TYPE_FLAG_DEVICE_SLEEP_STATE_EXIT#

Event is triggered when the driver is waking the device up from a deep sleep state

enumerator ZES_EVENT_TYPE_FLAG_FREQ_THROTTLED#

Event is triggered when the frequency starts being throttled.

enumerator ZES_EVENT_TYPE_FLAG_ENERGY_THRESHOLD_CROSSED#

Event is triggered when the energy consumption threshold is reached (use zesPowerSetEnergyThreshold() to configure).

enumerator ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL#

Event is triggered when the critical temperature is reached (use zesTemperatureSetConfig() to configure - disabled by default).

enumerator ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1#

Event is triggered when the temperature crosses threshold 1 (use zesTemperatureSetConfig() to configure - disabled by default).

enumerator ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2#

Event is triggered when the temperature crosses threshold 2 (use zesTemperatureSetConfig() to configure - disabled by default).

enumerator ZES_EVENT_TYPE_FLAG_MEM_HEALTH#

Event is triggered when the health of device memory changes.

enumerator ZES_EVENT_TYPE_FLAG_FABRIC_PORT_HEALTH#

Event is triggered when the health of fabric ports change.

enumerator ZES_EVENT_TYPE_FLAG_PCI_LINK_HEALTH#

Event is triggered when the health of the PCI link changes.

enumerator ZES_EVENT_TYPE_FLAG_RAS_CORRECTABLE_ERRORS#

Event is triggered when accelerator RAS correctable errors cross thresholds (use zesRasSetConfig() to configure - disabled by default).

enumerator ZES_EVENT_TYPE_FLAG_RAS_UNCORRECTABLE_ERRORS#

Event is triggered when accelerator RAS uncorrectable errors cross thresholds (use zesRasSetConfig() to configure - disabled by default).

enumerator ZES_EVENT_TYPE_FLAG_DEVICE_RESET_REQUIRED#

Event is triggered when the device needs to be reset (use zesDeviceGetState() to determine the reasons for the reset).

enumerator ZES_EVENT_TYPE_FLAG_SURVIVABILITY_MODE_DETECTED#

Event is triggered when graphics driver encounter an error condition.

enumerator ZES_EVENT_TYPE_FLAG_FORCE_UINT32#

Fabric#

Fabric Functions#

zesDeviceEnumFabricPorts#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumFabricPorts(zes_device_handle_t hDevice, uint32_t *pCount, zes_fabric_port_handle_t *phPort)#

Get handle of Fabric ports in a device.

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

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

  • phPort – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesFabricPortGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetProperties(zes_fabric_port_handle_t hPort, zes_fabric_port_properties_t *pProperties)#

Get Fabric port properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPort – [in] Handle for the component.

  • pProperties – [in,out] Will contain properties of the Fabric Port.

Returns:

zesFabricPortGetLinkType#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetLinkType(zes_fabric_port_handle_t hPort, zes_fabric_link_type_t *pLinkType)#

Get Fabric port link type.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPort – [in] Handle for the component.

  • pLinkType – [in,out] Will contain details about the link attached to the Fabric port.

Returns:

zesFabricPortGetConfig#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetConfig(zes_fabric_port_handle_t hPort, zes_fabric_port_config_t *pConfig)#

Get Fabric port configuration.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPort – [in] Handle for the component.

  • pConfig – [in,out] Will contain configuration of the Fabric Port.

Returns:

zesFabricPortSetConfig#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortSetConfig(zes_fabric_port_handle_t hPort, const zes_fabric_port_config_t *pConfig)#

Set Fabric port configuration.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPort – [in] Handle for the component.

  • pConfig – [in] Contains new configuration of the Fabric Port.

Returns:

zesFabricPortGetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetState(zes_fabric_port_handle_t hPort, zes_fabric_port_state_t *pState)#

Get Fabric port state - status (health/degraded/failed/disabled), reasons for link degradation or instability, current rx/tx speed.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPort – [in] Handle for the component.

  • pState – [in,out] Will contain the current state of the Fabric Port

Returns:

zesFabricPortGetThroughput#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetThroughput(zes_fabric_port_handle_t hPort, zes_fabric_port_throughput_t *pThroughput)#

Get Fabric port throughput.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPort – [in] Handle for the component.

  • pThroughput – [in,out] Will contain the Fabric port throughput counters.

Returns:

zesFabricPortGetFabricErrorCounters#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetFabricErrorCounters(zes_fabric_port_handle_t hPort, zes_fabric_port_error_counters_t *pErrors)#

Get Fabric Port Error Counters.

  • The application may call this function from simultaneous threads.

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

  • The memory backing the arrays for phPorts and ppThroughputs must be allocated in system memory by the user who is also responsible for releasing them when they are no longer needed.

Parameters:

  • hPort – [in] Handle for the component.

  • pErrors – [in,out] Will contain the Fabric port Error counters.

Returns:

zesFabricPortGetMultiPortThroughput#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetMultiPortThroughput(zes_device_handle_t hDevice, uint32_t numPorts, zes_fabric_port_handle_t *phPort, zes_fabric_port_throughput_t **pThroughput)#

Get Fabric port throughput from multiple ports in a single call.

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

  • numPorts – [in] Number of ports enumerated in function zesDeviceEnumFabricPorts

  • phPort – [in][range(0, numPorts)] array of fabric port handles provided by user to gather throughput values.

  • pThroughput – [out][range(0, numPorts)] array of fabric port throughput counters from multiple ports of type zes_fabric_port_throughput_t.

Returns:

Fabric Enums#

zes_fabric_port_status_t#

enum zes_fabric_port_status_t#

Fabric port status.

Values:

enumerator ZES_FABRIC_PORT_STATUS_UNKNOWN#

The port status cannot be determined.

enumerator ZES_FABRIC_PORT_STATUS_HEALTHY#

The port is up and operating as expected.

enumerator ZES_FABRIC_PORT_STATUS_DEGRADED#

The port is up but has quality and/or speed degradation.

enumerator ZES_FABRIC_PORT_STATUS_FAILED#

Port connection instabilities are preventing workloads making forward progress

enumerator ZES_FABRIC_PORT_STATUS_DISABLED#

The port is configured down.

enumerator ZES_FABRIC_PORT_STATUS_FORCE_UINT32#

zes_fabric_port_qual_issue_flags_t#

enum zes_fabric_port_qual_issue_flag_t#

Values:

enumerator ZES_FABRIC_PORT_QUAL_ISSUE_FLAG_LINK_ERRORS#

Excessive link errors are occurring.

enumerator ZES_FABRIC_PORT_QUAL_ISSUE_FLAG_SPEED#

There is a degradation in the bitrate and/or width of the link.

enumerator ZES_FABRIC_PORT_QUAL_ISSUE_FLAG_FORCE_UINT32#

zes_fabric_port_failure_flags_t#

enum zes_fabric_port_failure_flag_t#

Values:

enumerator ZES_FABRIC_PORT_FAILURE_FLAG_FAILED#

A previously operating link has failed. Hardware will automatically retrain this port. This state will persist until either the physical connection is removed or the link trains successfully.

enumerator ZES_FABRIC_PORT_FAILURE_FLAG_TRAINING_TIMEOUT#

A connection has not been established within an expected time. Hardware will continue to attempt port training. This status will persist until either the physical connection is removed or the link successfully trains.

enumerator ZES_FABRIC_PORT_FAILURE_FLAG_FLAPPING#

Port has excessively trained and then transitioned down for some period of time. Driver will allow port to continue to train, but will not enable the port for use until the port has been disabled and subsequently re-enabled using zesFabricPortSetConfig().

enumerator ZES_FABRIC_PORT_FAILURE_FLAG_FORCE_UINT32#

Fabric Structures#

zes_fabric_port_id_t#

struct zes_fabric_port_id_t#

Unique identifier for a fabric port.

  • This not a universal identifier. The identified is garanteed to be unique for the current hardware configuration of the system. Changes in the hardware may result in a different identifier for a given port.

  • The main purpose of this identifier to build up an instantaneous topology map of system connectivity. An application should enumerate all fabric ports and match the remotePortId member of zes_fabric_port_state_t to the portId member of zes_fabric_port_properties_t.

Public Members

uint32_t fabricId#

[out] Unique identifier for the fabric end-point

uint32_t attachId#

[out] Unique identifier for the device attachment point

uint8_t portNumber#

[out] The logical port number (this is typically marked somewhere on the physical device)

zes_fabric_port_speed_t#

struct zes_fabric_port_speed_t#

Fabric port speed in one direction.

Public Members

int64_t bitRate#

[out] Bits/sec that the link is operating at. A value of -1 means that this property is unknown.

int32_t width#

[out] The number of lanes. A value of -1 means that this property is unknown.

zes_fabric_port_properties_t#

struct zes_fabric_port_properties_t#

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

char model[ZES_MAX_FABRIC_PORT_MODEL_SIZE]#

[out] Description of port technology. Will be set to the string “unkown” if this cannot be determined for this port.

ze_bool_t onSubdevice#

[out] True if the port is located on a sub-device; false means that the port 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_fabric_port_id_t portId#

[out] The unique port identifier

zes_fabric_port_speed_t maxRxSpeed#

[out] Maximum speed supported by the receive side of the port (sum of all lanes)

zes_fabric_port_speed_t maxTxSpeed#

[out] Maximum speed supported by the transmit side of the port (sum of all lanes)

zes_fabric_port_config_t#

struct zes_fabric_port_config_t#

Fabric port configuration.

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

[in,out] Port is configured up/down

ze_bool_t beaconing#

[in,out] Beaconing is configured on/off

zes_fabric_port_state_t#

struct zes_fabric_port_state_t#

Fabric port state.

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_fabric_port_status_t status#

[out] The current status of the port

zes_fabric_port_qual_issue_flags_t qualityIssues#

[out] If status is ZES_FABRIC_PORT_STATUS_DEGRADED, then this gives a combination of zes_fabric_port_qual_issue_flag_t for quality issues that have been detected; otherwise, 0 indicates there are no quality issues with the link at this time.

zes_fabric_port_failure_flags_t failureReasons#

[out] If status is ZES_FABRIC_PORT_STATUS_FAILED, then this gives a combination of zes_fabric_port_failure_flag_t for reasons for the connection instability; otherwise, 0 indicates there are no connection stability issues at this time.

zes_fabric_port_id_t remotePortId#

[out] The unique port identifier for the remote connection point if status is ZES_FABRIC_PORT_STATUS_HEALTHY, ZES_FABRIC_PORT_STATUS_DEGRADED or ZES_FABRIC_PORT_STATUS_FAILED

zes_fabric_port_speed_t rxSpeed#

[out] Current maximum receive speed (sum of all lanes)

zes_fabric_port_speed_t txSpeed#

[out] Current maximum transmit speed (sum of all lanes)

zes_fabric_port_throughput_t#

struct zes_fabric_port_throughput_t#

Fabric port throughput.

Public Members

uint64_t timestamp#

[out] Monotonic timestamp counter in microseconds when the measurement was made. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

uint64_t rxCounter#

[out] Monotonic counter for the number of bytes received (sum of all lanes). This includes all protocol overhead, not only the GPU traffic.

uint64_t txCounter#

[out] Monotonic counter for the number of bytes transmitted (sum of all lanes). This includes all protocol overhead, not only the GPU traffic.

zes_fabric_port_error_counters_t#

struct zes_fabric_port_error_counters_t#

Fabric Port Error Counters.

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

uint64_t linkFailureCount#

[out] Link Failure Error Count reported per port

uint64_t fwCommErrorCount#

[out] Firmware Communication Error Count reported per device

uint64_t fwErrorCount#

[out] Firmware reported Error Count reported per device

uint64_t linkDegradeCount#

[out] Link Degrade Error Count reported per port

Fan#

Fan Functions#

zesDeviceEnumFans#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumFans(zes_device_handle_t hDevice, uint32_t *pCount, zes_fan_handle_t *phFan)#

Get handle of fans.

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

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

  • phFan – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesFanGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFanGetProperties(zes_fan_handle_t hFan, zes_fan_properties_t *pProperties)#

Get fan properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFan – [in] Handle for the component.

  • pProperties – [in,out] Will contain the properties of the fan.

Returns:

zesFanGetConfig#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFanGetConfig(zes_fan_handle_t hFan, zes_fan_config_t *pConfig)#

Get fan configurations and the current fan speed mode (default, fixed, temp-speed table)

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFan – [in] Handle for the component.

  • pConfig – [in,out] Will contain the current configuration of the fan.

Returns:

zesFanSetDefaultMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFanSetDefaultMode(zes_fan_handle_t hFan)#

Configure the fan to run with hardware factory settings (set mode to ZES_FAN_SPEED_MODE_DEFAULT)

  • The application may call this function from simultaneous threads.

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

Parameters:

hFan – [in] Handle for the component.

Returns:

zesFanSetFixedSpeedMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFanSetFixedSpeedMode(zes_fan_handle_t hFan, const zes_fan_speed_t *speed)#

Configure the fan to rotate at a fixed speed (set mode to ZES_FAN_SPEED_MODE_FIXED)

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFan – [in] Handle for the component.

  • speed – [in] The fixed fan speed setting

Returns:

zesFanSetSpeedTableMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFanSetSpeedTableMode(zes_fan_handle_t hFan, const zes_fan_speed_table_t *speedTable)#

Configure the fan to adjust speed based on a temperature/speed table (set mode to ZES_FAN_SPEED_MODE_TABLE)

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFan – [in] Handle for the component.

  • speedTable – [in] A table containing temperature/speed pairs.

Returns:

zesFanGetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFanGetState(zes_fan_handle_t hFan, zes_fan_speed_units_t units, int32_t *pSpeed)#

Get current state of a fan - current mode and speed.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFan – [in] Handle for the component.

  • units – [in] The units in which the fan speed should be returned.

  • pSpeed – [in,out] Will contain the current speed of the fan in the units requested. A value of -1 indicates that the fan speed cannot be measured.

Returns:

Fan Enums#

zes_fan_speed_mode_t#

enum zes_fan_speed_mode_t#

Fan resource speed mode.

Values:

enumerator ZES_FAN_SPEED_MODE_DEFAULT#

The fan speed is operating using the hardware default settings.

enumerator ZES_FAN_SPEED_MODE_FIXED#

The fan speed is currently set to a fixed value.

enumerator ZES_FAN_SPEED_MODE_TABLE#

The fan speed is currently controlled dynamically by hardware based on a temp/speed table

enumerator ZES_FAN_SPEED_MODE_FORCE_UINT32#

zes_fan_speed_units_t#

enum zes_fan_speed_units_t#

Fan speed units.

Values:

enumerator ZES_FAN_SPEED_UNITS_RPM#

The fan speed is in units of revolutions per minute (rpm)

enumerator ZES_FAN_SPEED_UNITS_PERCENT#

The fan speed is a percentage of the maximum speed of the fan.

enumerator ZES_FAN_SPEED_UNITS_FORCE_UINT32#

Fan Structures#

zes_fan_speed_t#

struct zes_fan_speed_t#

Fan speed.

Public Members

int32_t speed#

[in,out] The speed of the fan. On output, a value of -1 indicates that there is no fixed fan speed setting.

zes_fan_speed_units_t units#

[in,out] The units that the fan speed is expressed in. On output, if fan speed is -1 then units should be ignored.

zes_fan_temp_speed_t#

struct zes_fan_temp_speed_t#

Fan temperature/speed pair.

Public Members

uint32_t temperature#

[in,out] Temperature in degrees Celsius.

zes_fan_speed_t speed#

[in,out] The speed of the fan

zes_fan_speed_table_t#

struct zes_fan_speed_table_t#

Fan speed table.

Public Members

int32_t numPoints#

[in,out] The number of valid points in the fan speed table. 0 means that there is no fan speed table configured. -1 means that a fan speed table is not supported by the hardware.

zes_fan_temp_speed_t table[ZES_FAN_TEMP_SPEED_PAIR_COUNT]#

[in,out] Array of temperature/fan speed pairs. The table is ordered based on temperature from lowest to highest.

zes_fan_properties_t#

struct zes_fan_properties_t#

Fan 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

ze_bool_t canControl#

[out] Indicates if software can control the fan speed assuming the user has permissions

uint32_t supportedModes#

[out] Bitfield of supported fan configuration modes (1<<zes_fan_speed_mode_t)

uint32_t supportedUnits#

[out] Bitfield of supported fan speed units (1<<zes_fan_speed_units_t)

int32_t maxRPM#

[out] The maximum RPM of the fan. A value of -1 means that this property is unknown.

int32_t maxPoints#

[out] The maximum number of points in the fan temp/speed table. A value of -1 means that this fan doesn’t support providing a temp/speed table.

zes_fan_config_t#

struct zes_fan_config_t#

Fan configuration.

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_fan_speed_mode_t mode#

[in,out] The fan speed mode (fixed, temp-speed table)

zes_fan_speed_t speedFixed#

[in,out] The current fixed fan speed setting

zes_fan_speed_table_t speedTable#

[out] A table containing temperature/speed pairs

Firmware#

Firmware Functions#

zesDeviceEnumFirmwares#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumFirmwares(zes_device_handle_t hDevice, uint32_t *pCount, zes_firmware_handle_t *phFirmware)#

Get handle of firmwares.

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

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

  • phFirmware – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesFirmwareGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFirmwareGetProperties(zes_firmware_handle_t hFirmware, zes_firmware_properties_t *pProperties)#

Get firmware properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFirmware – [in] Handle for the component.

  • pProperties – [in,out] Pointer to an array that will hold the properties of the firmware

Returns:

zesFirmwareFlash#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFirmwareFlash(zes_firmware_handle_t hFirmware, void *pImage, uint32_t size)#

Flash a new firmware image.

  • Any running workload must be gracefully closed before invoking this function.

  • The application may call this function from simultaneous threads.

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

  • This is a non-blocking call. Application may call zesFirmwareGetFlashProgress to get completion status.

Parameters:

  • hFirmware – [in] Handle for the component.

  • pImage – [in] Image of the new firmware to flash.

  • size – [in] Size of the flash image.

Returns:

zesFirmwareGetFlashProgress#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFirmwareGetFlashProgress(zes_firmware_handle_t hFirmware, uint32_t *pCompletionPercent)#

Get Firmware Flash Progress.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFirmware – [in] Handle for the component.

  • pCompletionPercent – [in,out] Pointer to the Completion Percentage of Firmware Update

Returns:

zesFirmwareGetConsoleLogs#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFirmwareGetConsoleLogs(zes_firmware_handle_t hFirmware, size_t *pSize, char *pFirmwareLog)#

Get Firmware Console Logs.

  • The caller may pass nullptr for pFirmwareLog and set pSize to zero when querying only for size.

  • The caller must provide memory for Firmware log.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFirmware – [in] Handle for the component.

  • pSize – [in,out] size of firmware log

  • pFirmwareLog – [in,out][optional] pointer to null-terminated string of the log.

Returns:

Firmware Structures#

zes_firmware_properties_t#

struct zes_firmware_properties_t#

Firmware 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

ze_bool_t canControl#

[out] Indicates if software can flash the firmware assuming the user has permissions

char name[ZES_STRING_PROPERTY_SIZE]#

[out] NULL terminated string value. The string “unknown” will be returned if this property cannot be determined.

char version[ZES_STRING_PROPERTY_SIZE]#

[out] NULL terminated string value. The string “unknown” will be returned if this property cannot be determined.

Frequency#

Frequency Functions#

zesDeviceEnumFrequencyDomains#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumFrequencyDomains(zes_device_handle_t hDevice, uint32_t *pCount, zes_freq_handle_t *phFrequency)#

Get handle of frequency domains.

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

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

  • phFrequency – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesFrequencyGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyGetProperties(zes_freq_handle_t hFrequency, zes_freq_properties_t *pProperties)#

Get frequency properties - available frequencies.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Handle for the component.

  • pProperties – [in,out] The frequency properties for the specified domain.

Returns:

zesFrequencyGetAvailableClocks#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyGetAvailableClocks(zes_freq_handle_t hFrequency, uint32_t *pCount, double *phFrequency)#

Get available non-overclocked hardware clock frequencies for the frequency domain.

  • The list of available frequencies is returned in order of slowest to fastest.

  • The application may call this function from simultaneous threads.

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

Parameters:

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

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

  • phFrequency – [in,out][optional][range(0, *pCount)] array of frequencies in units of MHz and sorted from slowest to fastest. if count is less than the number of frequencies that are available, then the driver shall only retrieve that number of frequencies.

Returns:

zesFrequencyGetRange#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyGetRange(zes_freq_handle_t hFrequency, zes_freq_range_t *pLimits)#

Get current frequency limits.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Handle for the component.

  • pLimits – [in,out] The range between which the hardware can operate for the specified domain.

Returns:

zesFrequencySetRange#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencySetRange(zes_freq_handle_t hFrequency, const zes_freq_range_t *pLimits)#

Set frequency range between which the hardware can operate.

  • The application may call this function with the frequency range min and max values set to -1 to request the frequency be (re)set to the default values.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Handle for the component.

  • pLimits – [in] The limits between which the hardware can operate for the specified domain.

Returns:

zesFrequencyGetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyGetState(zes_freq_handle_t hFrequency, zes_freq_state_t *pState)#

Get current frequency state - frequency request, actual frequency, TDP limits.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Handle for the component.

  • pState – [in,out] Frequency state for the specified domain.

Returns:

zesFrequencyGetThrottleTime#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyGetThrottleTime(zes_freq_handle_t hFrequency, zes_freq_throttle_time_t *pThrottleTime)#

Get frequency throttle time.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Handle for the component.

  • pThrottleTime – [in,out] Will contain a snapshot of the throttle time counters for the specified domain.

Returns:

zesFrequencyOcGetCapabilities#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetCapabilities(zes_freq_handle_t hFrequency, zes_oc_capabilities_t *pOcCapabilities)#

Get the overclocking capabilities.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pOcCapabilities – [in,out] Pointer to the capabilities structure.

Returns:

zesFrequencyOcGetFrequencyTarget#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetFrequencyTarget(zes_freq_handle_t hFrequency, double *pCurrentOcFrequency)#

Get the current overclocking frequency target, if extended moded is supported, will returned in 1 Mhz granularity.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pCurrentOcFrequency – [out] Overclocking Frequency in MHz, if extended moded is supported, will returned in 1 Mhz granularity, else, in multiples of 50 Mhz. This cannot be greater than the maxOcFrequency member of zes_oc_capabilities_t.

Returns:

zesFrequencyOcSetFrequencyTarget#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcSetFrequencyTarget(zes_freq_handle_t hFrequency, double CurrentOcFrequency)#

Set the current overclocking frequency target, if extended moded is supported, can be set in 1 Mhz granularity.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • CurrentOcFrequency – [in] Overclocking Frequency in MHz, if extended moded is supported, it could be set in 1 Mhz granularity, else, in multiples of 50 Mhz. This cannot be greater than the maxOcFrequency member of zes_oc_capabilities_t.

Returns:

zesFrequencyOcGetVoltageTarget#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetVoltageTarget(zes_freq_handle_t hFrequency, double *pCurrentVoltageTarget, double *pCurrentVoltageOffset)#

Get the current overclocking voltage settings.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pCurrentVoltageTarget – [out] Overclock voltage in Volts. This cannot be greater than the maxOcVoltage member of zes_oc_capabilities_t.

  • pCurrentVoltageOffset – [out] This voltage offset is applied to all points on the voltage/frequency curve, including the new overclock voltageTarget. Valid range is between the minOcVoltageOffset and maxOcVoltageOffset members of zes_oc_capabilities_t.

Returns:

zesFrequencyOcSetVoltageTarget#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcSetVoltageTarget(zes_freq_handle_t hFrequency, double CurrentVoltageTarget, double CurrentVoltageOffset)#

Set the current overclocking voltage settings.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • CurrentVoltageTarget – [in] Overclock voltage in Volts. This cannot be greater than the maxOcVoltage member of zes_oc_capabilities_t.

  • CurrentVoltageOffset – [in] This voltage offset is applied to all points on the voltage/frequency curve, include the new overclock voltageTarget. Valid range is between the minOcVoltageOffset and maxOcVoltageOffset members of zes_oc_capabilities_t.

Returns:

zesFrequencyOcSetMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcSetMode(zes_freq_handle_t hFrequency, zes_oc_mode_t CurrentOcMode)#

Set the current overclocking mode.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • CurrentOcMode – [in] Current Overclocking Mode zes_oc_mode_t.

Returns:

zesFrequencyOcGetMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetMode(zes_freq_handle_t hFrequency, zes_oc_mode_t *pCurrentOcMode)#

Get the current overclocking mode.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pCurrentOcMode – [out] Current Overclocking Mode zes_oc_mode_t.

Returns:

zesFrequencyOcGetIccMax#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetIccMax(zes_freq_handle_t hFrequency, double *pOcIccMax)#

Get the maximum current limit setting.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pOcIccMax – [in,out] Will contain the maximum current limit in Amperes on successful return.

Returns:

zesFrequencyOcSetIccMax#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcSetIccMax(zes_freq_handle_t hFrequency, double ocIccMax)#

Change the maximum current limit setting.

  • Setting ocIccMax to 0.0 will return the value to the factory default.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • ocIccMax – [in] The new maximum current limit in Amperes.

Returns:

zesFrequencyOcGetTjMax#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetTjMax(zes_freq_handle_t hFrequency, double *pOcTjMax)#

Get the maximum temperature limit setting.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pOcTjMax – [in,out] Will contain the maximum temperature limit in degrees Celsius on successful return.

Returns:

zesFrequencyOcSetTjMax#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcSetTjMax(zes_freq_handle_t hFrequency, double ocTjMax)#

Change the maximum temperature limit setting.

  • Setting ocTjMax to 0.0 will return the value to the factory default.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • ocTjMax – [in] The new maximum temperature limit in degrees Celsius.

Returns:

Frequency Enums#

zes_freq_domain_t#

enum zes_freq_domain_t#

Frequency domains.

Values:

enumerator ZES_FREQ_DOMAIN_GPU#

GPU Core Domain.

enumerator ZES_FREQ_DOMAIN_MEMORY#

Local Memory Domain.

enumerator ZES_FREQ_DOMAIN_MEDIA#

GPU Media Domain.

enumerator ZES_FREQ_DOMAIN_FORCE_UINT32#

zes_freq_throttle_reason_flags_t#

enum zes_freq_throttle_reason_flag_t#

Values:

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_AVE_PWR_CAP#

frequency throttled due to average power excursion (PL1)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_BURST_PWR_CAP#

frequency throttled due to burst power excursion (PL2)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_CURRENT_LIMIT#

frequency throttled due to current excursion (PL4)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_THERMAL_LIMIT#

frequency throttled due to thermal excursion (T > TjMax)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_PSU_ALERT#

frequency throttled due to power supply assertion

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_SW_RANGE#

frequency throttled due to software supplied frequency range

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_HW_RANGE#

frequency throttled due to a sub block that has a lower frequency range when it receives clocks

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_FORCE_UINT32#

zes_oc_mode_t#

enum zes_oc_mode_t#

Overclocking modes.

  • [DEPRECATED] No longer supported.

Values:

enumerator ZES_OC_MODE_OFF#

Overclocking if off - hardware is running using factory default voltages/frequencies.

enumerator ZES_OC_MODE_OVERRIDE#

Overclock override mode - In this mode, a fixed user-supplied voltage is applied independent of the frequency request. The maximum permitted frequency can also be increased. This mode disables INTERPOLATIVE and FIXED modes.

enumerator ZES_OC_MODE_INTERPOLATIVE#

Overclock interpolative mode - In this mode, the voltage/frequency curve can be extended with a new voltage/frequency point that will be interpolated. The existing voltage/frequency points can also be offset (up or down) by a fixed voltage. This mode disables FIXED and OVERRIDE modes.

enumerator ZES_OC_MODE_FIXED#

Overclocking fixed Mode - In this mode, hardware will disable most frequency throttling and lock the frequency and voltage at the specified overclock values. This mode disables OVERRIDE and INTERPOLATIVE modes. This mode can damage the part, most of the protections are disabled on this mode.

enumerator ZES_OC_MODE_FORCE_UINT32#

Frequency Structures#

zes_freq_properties_t#

struct zes_freq_properties_t#

Frequency properties.

  • Indicates if this frequency domain can be overclocked (if true, functions such as zesFrequencyOcSetFrequencyTarget() are supported).

  • The min/max hardware frequencies are specified for non-overclock configurations. For overclock configurations, use zesFrequencyOcGetFrequencyTarget() to determine the maximum frequency that can be requested.

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_freq_domain_t type#

[out] The hardware block that this frequency domain controls (GPU, memory, …)

ze_bool_t onSubdevice#

[out] True if this 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

ze_bool_t canControl#

[out] Indicates if software can control the frequency of this domain assuming the user has permissions

ze_bool_t isThrottleEventSupported#

[out] Indicates if software can register to receive event ZES_EVENT_TYPE_FLAG_FREQ_THROTTLED

double min#

[out] The minimum hardware clock frequency in units of MHz.

double max#

[out] The maximum non-overclock hardware clock frequency in units of MHz.

zes_freq_range_t#

struct zes_freq_range_t#

Frequency range between which the hardware can operate.

  • When setting limits, they will be clamped to the hardware limits.

  • When setting limits, ensure that the max frequency is greater than or equal to the min frequency specified.

  • When setting limits to return to factory settings, specify -1 for both the min and max limit.

Public Members

double min#

[in,out] The min frequency in MHz below which hardware frequency management will not request frequencies. On input, setting to 0 will permit the frequency to go down to the hardware minimum while setting to -1 will return the min frequency limit to the factory value (can be larger than the hardware min). On output, a negative value indicates that no external minimum frequency limit is in effect.

double max#

[in,out] The max frequency in MHz above which hardware frequency management will not request frequencies. On input, setting to 0 or a very big number will permit the frequency to go all the way up to the hardware maximum while setting to -1 will return the max frequency to the factory value (which can be less than the hardware max). On output, a negative number indicates that no external maximum frequency limit is in effect.

zes_freq_state_t#

struct zes_freq_state_t#

Frequency state.

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

double currentVoltage#

[out] Current voltage in Volts. A negative value indicates that this property is not known.

double request#

[out] The current frequency request in MHz. A negative value indicates that this property is not known.

double tdp#

[out] The maximum frequency in MHz supported under the current TDP conditions. This fluctuates dynamically based on the power and thermal limits of the part. A negative value indicates that this property is not known.

double efficient#

[out] The efficient minimum frequency in MHz. A negative value indicates that this property is not known.

double actual#

[out] The resolved frequency in MHz. A negative value indicates that this property is not known.

zes_freq_throttle_reason_flags_t throttleReasons#

[out] The reasons that the frequency is being limited by the hardware. Returns 0 (frequency not throttled) or a combination of zes_freq_throttle_reason_flag_t.

zes_freq_throttle_time_t#

struct zes_freq_throttle_time_t#

Frequency throttle time snapshot.

  • Percent time throttled is calculated by taking two snapshots (s1, s2) and using the equation: throttled = (s2.throttleTime - s1.throttleTime) / (s2.timestamp - s1.timestamp)

Public Members

uint64_t throttleTime#

[out] The monotonic counter of time in microseconds that the frequency has been limited by the hardware.

uint64_t timestamp#

[out] Microsecond timestamp when throttleTime was captured. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

zes_oc_capabilities_t#

struct zes_oc_capabilities_t#

Overclocking properties.

  • Provides all the overclocking capabilities and properties supported by the device for the frequency domain.

  • [DEPRECATED] No longer supported.

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

[out] Indicates if any overclocking features are supported on this frequency domain.

double maxFactoryDefaultFrequency#

[out] Factory default non-overclock maximum frequency in Mhz.

double maxFactoryDefaultVoltage#

[out] Factory default voltage used for the non-overclock maximum frequency in MHz.

double maxOcFrequency#

[out] Maximum hardware overclocking frequency limit in Mhz.

double minOcVoltageOffset#

[out] The minimum voltage offset that can be applied to the voltage/frequency curve. Note that this number can be negative.

double maxOcVoltageOffset#

[out] The maximum voltage offset that can be applied to the voltage/frequency curve.

double maxOcVoltage#

[out] The maximum overclock voltage that hardware supports.

ze_bool_t isTjMaxSupported#

[out] Indicates if the maximum temperature limit (TjMax) can be changed for this frequency domain.

ze_bool_t isIccMaxSupported#

[out] Indicates if the maximum current (IccMax) can be changed for this frequency domain.

ze_bool_t isHighVoltModeCapable#

[out] Indicates if this frequency domains supports a feature to set very high voltages.

ze_bool_t isHighVoltModeEnabled#

[out] Indicates if very high voltages are permitted on this frequency domain.

ze_bool_t isExtendedModeSupported#

[out] Indicates if the extended overclocking features are supported. If this is supported, increments are on 1 Mhz basis.

ze_bool_t isFixedModeSupported#

[out] Indicates if the fixed mode is supported. In this mode, hardware will disable most frequency throttling and lock the frequency and voltage at the specified overclock values.

Led#

Led Functions#

zesDeviceEnumLeds#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumLeds(zes_device_handle_t hDevice, uint32_t *pCount, zes_led_handle_t *phLed)#

Get handle of LEDs.

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

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

  • phLed – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesLedGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesLedGetProperties(zes_led_handle_t hLed, zes_led_properties_t *pProperties)#

Get LED properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hLed – [in] Handle for the component.

  • pProperties – [in,out] Will contain the properties of the LED.

Returns:

zesLedGetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesLedGetState(zes_led_handle_t hLed, zes_led_state_t *pState)#

Get current state of a LED - on/off, color.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hLed – [in] Handle for the component.

  • pState – [in,out] Will contain the current state of the LED.

Returns:

zesLedSetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesLedSetState(zes_led_handle_t hLed, ze_bool_t enable)#

Turn the LED on/off.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hLed – [in] Handle for the component.

  • enable – [in] Set to TRUE to turn the LED on, FALSE to turn off.

Returns:

zesLedSetColor#

ZE_APIEXPORT ze_result_t ZE_APICALL zesLedSetColor(zes_led_handle_t hLed, const zes_led_color_t *pColor)#

Set the color of the LED.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hLed – [in] Handle for the component.

  • pColor – [in] New color of the LED.

Returns:

Led Structures#

zes_led_properties_t#

struct zes_led_properties_t#

LED 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

ze_bool_t canControl#

[out] Indicates if software can control the LED assuming the user has permissions

ze_bool_t haveRGB#

[out] Indicates if the LED is RGB capable

zes_led_color_t#

struct zes_led_color_t#

LED color.

Public Members

double red#

[in,out][range(0.0, 1.0)] The LED red value. On output, a value less than 0.0 indicates that the color is not known.

double green#

[in,out][range(0.0, 1.0)] The LED green value. On output, a value less than 0.0 indicates that the color is not known.

double blue#

[in,out][range(0.0, 1.0)] The LED blue value. On output, a value less than 0.0 indicates that the color is not known.

zes_led_state_t#

struct zes_led_state_t#

LED state.

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

[out] Indicates if the LED is on or off

zes_led_color_t color#

[out] Color of the LED

Memory#

Memory Functions#

zesDeviceEnumMemoryModules#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumMemoryModules(zes_device_handle_t hDevice, uint32_t *pCount, zes_mem_handle_t *phMemory)#

Get handle of memory modules.

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

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

  • phMemory – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesMemoryGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesMemoryGetProperties(zes_mem_handle_t hMemory, zes_mem_properties_t *pProperties)#

Get memory properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hMemory – [in] Handle for the component.

  • pProperties – [in,out] Will contain memory properties.

Returns:

zesMemoryGetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesMemoryGetState(zes_mem_handle_t hMemory, zes_mem_state_t *pState)#

Get memory state - health, allocated.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hMemory – [in] Handle for the component.

  • pState – [in,out] Will contain the current health and allocated memory.

Returns:

zesMemoryGetBandwidth#

ZE_APIEXPORT ze_result_t ZE_APICALL zesMemoryGetBandwidth(zes_mem_handle_t hMemory, zes_mem_bandwidth_t *pBandwidth)#

Get memory bandwidth.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hMemory – [in] Handle for the component.

  • pBandwidth – [in,out] Will contain the total number of bytes read from and written to memory, as well as the current maximum bandwidth.

Returns:

Memory Enums#

zes_mem_type_t#

enum zes_mem_type_t#

Memory module types.

Values:

enumerator ZES_MEM_TYPE_HBM#

HBM memory.

enumerator ZES_MEM_TYPE_DDR#

DDR memory.

enumerator ZES_MEM_TYPE_DDR3#

DDR3 memory.

enumerator ZES_MEM_TYPE_DDR4#

DDR4 memory.

enumerator ZES_MEM_TYPE_DDR5#

DDR5 memory.

enumerator ZES_MEM_TYPE_LPDDR#

LPDDR memory.

enumerator ZES_MEM_TYPE_LPDDR3#

LPDDR3 memory.

enumerator ZES_MEM_TYPE_LPDDR4#

LPDDR4 memory.

enumerator ZES_MEM_TYPE_LPDDR5#

LPDDR5 memory.

enumerator ZES_MEM_TYPE_SRAM#

SRAM memory.

enumerator ZES_MEM_TYPE_L1#

L1 cache.

enumerator ZES_MEM_TYPE_L3#

L3 cache.

enumerator ZES_MEM_TYPE_GRF#

Execution unit register file.

enumerator ZES_MEM_TYPE_SLM#

Execution unit shared local memory.

enumerator ZES_MEM_TYPE_GDDR4#

GDDR4 memory.

enumerator ZES_MEM_TYPE_GDDR5#

GDDR5 memory.

enumerator ZES_MEM_TYPE_GDDR5X#

GDDR5X memory.

enumerator ZES_MEM_TYPE_GDDR6#

GDDR6 memory.

enumerator ZES_MEM_TYPE_GDDR6X#

GDDR6X memory.

enumerator ZES_MEM_TYPE_GDDR7#

GDDR7 memory.

enumerator ZES_MEM_TYPE_FORCE_UINT32#

zes_mem_loc_t#

enum zes_mem_loc_t#

Memory module location.

Values:

enumerator ZES_MEM_LOC_SYSTEM#

System memory.

enumerator ZES_MEM_LOC_DEVICE#

On board local device memory.

enumerator ZES_MEM_LOC_FORCE_UINT32#

zes_mem_health_t#

enum zes_mem_health_t#

Memory health.

Values:

enumerator ZES_MEM_HEALTH_UNKNOWN#

The memory health cannot be determined.

enumerator ZES_MEM_HEALTH_OK#

All memory channels are healthy.

enumerator ZES_MEM_HEALTH_DEGRADED#

Excessive correctable errors have been detected on one or more channels. Device should be reset.

enumerator ZES_MEM_HEALTH_CRITICAL#

Operating with reduced memory to cover banks with too many uncorrectable errors.

enumerator ZES_MEM_HEALTH_REPLACE#

Device should be replaced due to excessive uncorrectable errors.

enumerator ZES_MEM_HEALTH_FORCE_UINT32#

Memory Structures#

zes_mem_properties_t#

struct zes_mem_properties_t#

Memory 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_mem_type_t type#

[out] The memory type

ze_bool_t onSubdevice#

[out] True if this 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_mem_loc_t location#

[out] Location of this memory (system, device)

uint64_t physicalSize#

[out] Physical memory size in bytes. A value of 0 indicates that this property is not known. However, a call to zesMemoryGetState() will correctly return the total size of usable memory.

int32_t busWidth#

[out] Width of the memory bus. A value of -1 means that this property is unknown.

int32_t numChannels#

[out] The number of memory channels. A value of -1 means that this property is unknown.

zes_mem_state_t#

struct zes_mem_state_t#

Memory state - health, allocated.

  • Percent allocation is given by 100 * (size - free / size.

  • Percent free is given by 100 * free / size.

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_mem_health_t health#

[out] Indicates the health of the memory

uint64_t free#

[out] The free memory in bytes

uint64_t size#

[out] The total allocatable memory in bytes (can be less than the physicalSize member of zes_mem_properties_t)

zes_mem_bandwidth_t#

struct zes_mem_bandwidth_t#

Memory bandwidth.

  • Percent bandwidth is calculated by taking two snapshots (s1, s2) and using the equation: bw = 10^6 * ((s2.readCounter - s1.readCounter) + (s2.writeCounter - s1.writeCounter)) / (s2.maxBandwidth * (s2.timestamp - s1.timestamp))

  • Counter can roll over and rollover needs to be handled by comparing the current read against the previous read

  • Counter is a 32 byte transaction count, which means the calculated delta (delta = current_value - previous_value or delta = 2^32 - previous_value + current_value in case of rollover) needs to be multiplied by 32 to get delta between samples in actual byte count

Public Members

uint64_t readCounter#

[out] Total bytes read from memory

uint64_t writeCounter#

[out] Total bytes written to memory

uint64_t maxBandwidth#

[out] Current maximum bandwidth in units of bytes/sec

uint64_t timestamp#

[out] The timestamp in microseconds when these measurements were sampled. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

zes_mem_ext_bandwidth_t#

struct zes_mem_ext_bandwidth_t#

Extension properties for Memory bandwidth.

  • Number of counter bits

  • [DEPRECATED] No longer supported.

Public Members

uint32_t memoryTimestampValidBits#

[out] Returns the number of valid bits in the timestamp values

Performance#

Performance Functions#

zesDeviceEnumPerformanceFactorDomains#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumPerformanceFactorDomains(zes_device_handle_t hDevice, uint32_t *pCount, zes_perf_handle_t *phPerf)#

Get handles to accelerator domains whose performance can be optimized via a Performance Factor.

  • A Performance Factor should be tuned for each workload.

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

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

  • phPerf – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesPerformanceFactorGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPerformanceFactorGetProperties(zes_perf_handle_t hPerf, zes_perf_properties_t *pProperties)#

Get properties about a Performance Factor domain.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPerf – [in] Handle for the Performance Factor domain.

  • pProperties – [in,out] Will contain information about the specified Performance Factor domain.

Returns:

zesPerformanceFactorGetConfig#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPerformanceFactorGetConfig(zes_perf_handle_t hPerf, double *pFactor)#

Get current Performance Factor for a given domain.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPerf – [in] Handle for the Performance Factor domain.

  • pFactor – [in,out] Will contain the actual Performance Factor being used by the hardware (may not be the same as the requested Performance Factor).

Returns:

zesPerformanceFactorSetConfig#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPerformanceFactorSetConfig(zes_perf_handle_t hPerf, double factor)#

Change the performance factor for a domain.

  • The Performance Factor is a number between 0 and 100.

  • A Performance Factor is a hint to the hardware. Depending on the hardware, the request may not be granted. Follow up this function with a call to zesPerformanceFactorGetConfig() to determine the actual factor being used by the hardware.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPerf – [in] Handle for the Performance Factor domain.

  • factor – [in] The new Performance Factor.

Returns:

Performance Structures#

zes_perf_properties_t#

struct zes_perf_properties_t#

Static information about a Performance Factor domain.

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 this Performance Factor affects accelerators located on a sub-device

uint32_t subdeviceId#

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

zes_engine_type_flags_t engines#

[out] Bitfield of accelerator engine types that are affected by this Performance Factor.

Power#

Power Functions#

zesDeviceEnumPowerDomains#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumPowerDomains(zes_device_handle_t hDevice, uint32_t *pCount, zes_pwr_handle_t *phPower)#

Get handle of power domains.

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

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

  • phPower – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesDeviceGetCardPowerDomain#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceGetCardPowerDomain(zes_device_handle_t hDevice, zes_pwr_handle_t *phPower)#

Get handle of the PCIe card-level power.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

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

  • phPower – [in,out] power domain handle for the entire PCIe card.

Returns:

zesPowerGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetProperties(zes_pwr_handle_t hPower, zes_power_properties_t *pProperties)#

Get properties related to a power domain.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPower – [in] Handle for the component.

  • pProperties – [in,out] Structure that will contain property data.

Returns:

zesPowerGetEnergyCounter#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetEnergyCounter(zes_pwr_handle_t hPower, zes_power_energy_counter_t *pEnergy)#

Get energy counter.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPower – [in] Handle for the component.

  • pEnergy – [in,out] Will contain the latest snapshot of the energy counter and timestamp when the last counter value was measured.

Returns:

zesPowerGetLimits#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetLimits(zes_pwr_handle_t hPower, zes_power_sustained_limit_t *pSustained, zes_power_burst_limit_t *pBurst, zes_power_peak_limit_t *pPeak)#

Get power limits.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] Use zesPowerGetLimitsExt.

Parameters:

  • hPower – [in] Handle for the component.

  • pSustained – [in,out][optional] The sustained power limit. If this is null, the current sustained power limits will not be returned.

  • pBurst – [in,out][optional] The burst power limit. If this is null, the current peak power limits will not be returned.

  • pPeak – [in,out][optional] The peak power limit. If this is null, the peak power limits will not be returned.

Returns:

zesPowerSetLimits#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerSetLimits(zes_pwr_handle_t hPower, const zes_power_sustained_limit_t *pSustained, const zes_power_burst_limit_t *pBurst, const zes_power_peak_limit_t *pPeak)#

Set power limits.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] Use zesPowerSetLimitsExt.

Parameters:

  • hPower – [in] Handle for the component.

  • pSustained – [in][optional] The sustained power limit. If this is null, no changes will be made to the sustained power limits.

  • pBurst – [in][optional] The burst power limit. If this is null, no changes will be made to the burst power limits.

  • pPeak – [in][optional] The peak power limit. If this is null, no changes will be made to the peak power limits.

Returns:

zesPowerGetEnergyThreshold#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetEnergyThreshold(zes_pwr_handle_t hPower, zes_energy_threshold_t *pThreshold)#

Get energy threshold.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPower – [in] Handle for the component.

  • pThreshold – [in,out] Returns information about the energy threshold setting - enabled/energy threshold/process ID.

Returns:

zesPowerSetEnergyThreshold#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerSetEnergyThreshold(zes_pwr_handle_t hPower, double threshold)#

Set energy threshold.

  • An event ZES_EVENT_TYPE_FLAG_ENERGY_THRESHOLD_CROSSED will be generated when the delta energy consumed starting from this call exceeds the specified threshold. Use the function zesDeviceEventRegister() to start receiving the event.

  • Only one running process can control the energy threshold at a given time. If another process attempts to change the energy threshold, the error ZE_RESULT_ERROR_NOT_AVAILABLE will be returned. The function zesPowerGetEnergyThreshold() to determine the process ID currently controlling this setting.

  • Calling this function will remove any pending energy thresholds and start counting from the time of this call.

  • Once the energy threshold has been reached and the event generated, the threshold is automatically removed. It is up to the application to request a new threshold.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPower – [in] Handle for the component.

  • threshold – [in] The energy threshold to be set in joules.

Returns:

Power Enums#

zes_power_domain_t#

enum zes_power_domain_t#

Power Domain.

Values:

enumerator ZES_POWER_DOMAIN_UNKNOWN#

The PUnit power domain level cannot be determined.

enumerator ZES_POWER_DOMAIN_CARD#

The PUnit power domain is a card-level power domain.

enumerator ZES_POWER_DOMAIN_PACKAGE#

The PUnit power domain is a package-level power domain.

enumerator ZES_POWER_DOMAIN_STACK#

The PUnit power domain is a stack-level power domain.

enumerator ZES_POWER_DOMAIN_MEMORY#

The PUnit power domain is a memory-level power domain.

enumerator ZES_POWER_DOMAIN_GPU#

The PUnit power domain is a GPU-level power domain.

enumerator ZES_POWER_DOMAIN_FORCE_UINT32#

zes_power_level_t#

enum zes_power_level_t#

Power Level Type.

Values:

enumerator ZES_POWER_LEVEL_UNKNOWN#

The PUnit power monitoring duration cannot be determined.

enumerator ZES_POWER_LEVEL_SUSTAINED#

The PUnit determines effective power draw by computing a moving average of the actual power draw over a time interval (longer than BURST).

enumerator ZES_POWER_LEVEL_BURST#

The PUnit determines effective power draw by computing a moving average of the actual power draw over a time interval (longer than PEAK).

enumerator ZES_POWER_LEVEL_PEAK#

The PUnit determines effective power draw by computing a moving average of the actual power draw over a very short time interval.

enumerator ZES_POWER_LEVEL_INSTANTANEOUS#

The PUnit predicts effective power draw using the current device configuration (frequency, voltage, etc…) & throttles proactively to stay within the specified limit.

enumerator ZES_POWER_LEVEL_FORCE_UINT32#

zes_power_source_t#

enum zes_power_source_t#

Power Source Type.

Values:

enumerator ZES_POWER_SOURCE_ANY#

Limit active no matter whether the power source is mains powered or battery powered.

enumerator ZES_POWER_SOURCE_MAINS#

Limit active only when the device is mains powered.

enumerator ZES_POWER_SOURCE_BATTERY#

Limit active only when the device is battery powered.

enumerator ZES_POWER_SOURCE_FORCE_UINT32#

zes_limit_unit_t#

enum zes_limit_unit_t#

Limit Unit.

Values:

enumerator ZES_LIMIT_UNIT_UNKNOWN#

The PUnit power monitoring unit cannot be determined.

enumerator ZES_LIMIT_UNIT_CURRENT#

The limit is specified in milliamperes of current drawn.

enumerator ZES_LIMIT_UNIT_POWER#

The limit is specified in milliwatts of power generated.

enumerator ZES_LIMIT_UNIT_FORCE_UINT32#

Power Structures#

zes_power_properties_t#

struct zes_power_properties_t#

Properties related to device power settings.

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 this 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

ze_bool_t canControl#

[out] Software can change the power limits of this domain assuming the user has permissions.

ze_bool_t isEnergyThresholdSupported#

[out] Indicates if this power domain supports the energy threshold event (ZES_EVENT_TYPE_FLAG_ENERGY_THRESHOLD_CROSSED).

int32_t defaultLimit#

[out] (Deprecated) The factory default TDP power limit of the part in milliwatts. A value of -1 means that this is not known.

int32_t minLimit#

[out] (Deprecated) The minimum power limit in milliwatts that can be requested. A value of -1 means that this is not known.

int32_t maxLimit#

[out] (Deprecated) The maximum power limit in milliwatts that can be requested. A value of -1 means that this is not known.

zes_power_energy_counter_t#

struct zes_power_energy_counter_t#

Energy counter snapshot.

  • Average power is calculated by taking two snapshots (s1, s2) and using the equation: PowerWatts = (s2.energy - s1.energy) / (s2.timestamp - s1.timestamp)

Public Members

uint64_t energy#

[out] The monotonic energy counter in microjoules.

uint64_t timestamp#

[out] Microsecond timestamp when energy was captured. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

zes_power_sustained_limit_t#

struct zes_power_sustained_limit_t#

Sustained power limits.

  • The power controller (Punit) will throttle the operating frequency if the power averaged over a window (typically seconds) exceeds this limit.

  • [DEPRECATED] No longer supported.

Public Members

ze_bool_t enabled#

[in,out] indicates if the limit is enabled (true) or ignored (false)

int32_t power#

[in,out] power limit in milliwatts

int32_t interval#

[in,out] power averaging window (Tau) in milliseconds

zes_power_burst_limit_t#

struct zes_power_burst_limit_t#

Burst power limit.

  • The power controller (Punit) will throttle the operating frequency of the device if the power averaged over a few milliseconds exceeds a limit known as PL2. Typically PL2 > PL1 so that it permits the frequency to burst higher for short periods than would be otherwise permitted by PL1.

  • [DEPRECATED] No longer supported.

Public Members

ze_bool_t enabled#

[in,out] indicates if the limit is enabled (true) or ignored (false)

int32_t power#

[in,out] power limit in milliwatts

zes_power_peak_limit_t#

struct zes_power_peak_limit_t#

Peak power limit.

  • The power controller (Punit) will reactively/proactively throttle the operating frequency of the device when the instantaneous/100usec power exceeds this limit. The limit is known as PL4 or Psys. It expresses the maximum power that can be drawn from the power supply.

  • If this power limit is removed or set too high, the power supply will generate an interrupt when it detects an overcurrent condition and the power controller will throttle the device frequencies down to min. It is thus better to tune the PL4 value in order to avoid such excursions.

  • [DEPRECATED] No longer supported.

Public Members

int32_t powerAC#

[in,out] power limit in milliwatts for the AC power source.

int32_t powerDC#

[in,out] power limit in milliwatts for the DC power source. On input, this is ignored if the product does not have a battery. On output, this will be -1 if the product does not have a battery.

zes_energy_threshold_t#

struct zes_energy_threshold_t#

Energy threshold.

  • .

Public Members

ze_bool_t enable#

[in,out] Indicates if the energy threshold is enabled.

double threshold#

[in,out] The energy threshold in Joules. Will be 0.0 if no threshold has been set.

uint32_t processId#

[in,out] The host process ID that set the energy threshold. Will be 0xFFFFFFFF if no threshold has been set.

Psu#

Psu Functions#

zesDeviceEnumPsus#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumPsus(zes_device_handle_t hDevice, uint32_t *pCount, zes_psu_handle_t *phPsu)#

Get handle of power supplies.

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

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

  • phPsu – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesPsuGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPsuGetProperties(zes_psu_handle_t hPsu, zes_psu_properties_t *pProperties)#

Get power supply properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPsu – [in] Handle for the component.

  • pProperties – [in,out] Will contain the properties of the power supply.

Returns:

zesPsuGetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPsuGetState(zes_psu_handle_t hPsu, zes_psu_state_t *pState)#

Get current power supply state.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPsu – [in] Handle for the component.

  • pState – [in,out] Will contain the current state of the power supply.

Returns:

Psu Enums#

zes_psu_voltage_status_t#

enum zes_psu_voltage_status_t#

PSU voltage status.

Values:

enumerator ZES_PSU_VOLTAGE_STATUS_UNKNOWN#

The status of the power supply voltage controllers cannot be determined

enumerator ZES_PSU_VOLTAGE_STATUS_NORMAL#

No unusual voltages have been detected.

enumerator ZES_PSU_VOLTAGE_STATUS_OVER#

Over-voltage has occurred.

enumerator ZES_PSU_VOLTAGE_STATUS_UNDER#

Under-voltage has occurred.

enumerator ZES_PSU_VOLTAGE_STATUS_FORCE_UINT32#

Psu Structures#

zes_psu_properties_t#

struct zes_psu_properties_t#

Static properties of the power supply.

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

ze_bool_t haveFan#

[out] True if the power supply has a fan

int32_t ampLimit#

[out] The maximum electrical current in milliamperes that can be drawn. A value of -1 indicates that this property cannot be determined.

zes_psu_state_t#

struct zes_psu_state_t#

Dynamic state of the power supply.

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_psu_voltage_status_t voltStatus#

[out] The current PSU voltage status

ze_bool_t fanFailed#

[out] Indicates if the fan has failed

int32_t temperature#

[out] Read the current heatsink temperature in degrees Celsius. A value of -1 indicates that this property cannot be determined.

int32_t current#

[out] The amps being drawn in milliamperes. A value of -1 indicates that this property cannot be determined.

Ras#

Ras Functions#

zesDeviceEnumRasErrorSets#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumRasErrorSets(zes_device_handle_t hDevice, uint32_t *pCount, zes_ras_handle_t *phRas)#

Get handle of all RAS error sets on a device.

  • A RAS error set is a collection of RAS error counters of a given type (correctable/uncorrectable) from hardware blocks contained within a sub-device or within the device.

  • A device without sub-devices will typically return two handles, one for correctable errors sets and one for uncorrectable error sets.

  • A device with sub-devices will return RAS error sets for each sub-device and possibly RAS error sets for hardware blocks outside the sub-devices.

  • If the function completes successfully but pCount is set to 0, RAS features are not available/enabled on this device.

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

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

  • phRas – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesRasGetProperties#

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#

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.

  • The driver maintains counters for all RAS error sets and error categories. Events are generated when errors occur. The configuration enables setting thresholds to limit when events are sent.

  • When a particular RAS correctable error counter exceeds the configured threshold, the event ZES_EVENT_TYPE_FLAG_RAS_CORRECTABLE_ERRORS will be triggered.

  • When a particular RAS uncorrectable error counter exceeds the configured threshold, the event ZES_EVENT_TYPE_FLAG_RAS_UNCORRECTABLE_ERRORS will be triggered.

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

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

Returns:

zesRasSetConfig#

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.

  • The driver maintains counters for all RAS error sets and error categories. Events are generated when errors occur. The configuration enables setting thresholds to limit when events are sent.

  • When a particular RAS correctable error counter exceeds the specified threshold, the event ZES_EVENT_TYPE_FLAG_RAS_CORRECTABLE_ERRORS will be generated.

  • When a particular RAS uncorrectable error counter exceeds the specified threshold, the event ZES_EVENT_TYPE_FLAG_RAS_UNCORRECTABLE_ERRORS will be generated.

  • Call zesRasGetState() and set the clear flag to true to restart event generation once counters have exceeded thresholds.

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

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

Returns:

zesRasGetState#

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#

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#

zes_ras_error_cat_t#

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#

Ras Structures#

zes_ras_properties_t#

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#

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#

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.

Scheduler#

Scheduler Functions#

zesDeviceEnumSchedulers#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumSchedulers(zes_device_handle_t hDevice, uint32_t *pCount, zes_sched_handle_t *phScheduler)#

Returns handles to scheduler components.

  • Each scheduler component manages the distribution of work across one or more accelerator engines.

  • If an application wishes to change the scheduler behavior for all accelerator engines of a specific type (e.g. compute), it should select all the handles where the engines member zes_sched_properties_t contains that type.

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

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

  • phScheduler – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesSchedulerGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesSchedulerGetProperties(zes_sched_handle_t hScheduler, zes_sched_properties_t *pProperties)#

Get properties related to a scheduler component.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hScheduler – [in] Handle for the component.

  • pProperties – [in,out] Structure that will contain property data.

Returns:

zesSchedulerGetCurrentMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesSchedulerGetCurrentMode(zes_sched_handle_t hScheduler, zes_sched_mode_t *pMode)#

Get current scheduling mode in effect on a scheduler component.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hScheduler – [in] Sysman handle for the component.

  • pMode – [in,out] Will contain the current scheduler mode.

Returns:

zesSchedulerGetTimeoutModeProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesSchedulerGetTimeoutModeProperties(zes_sched_handle_t hScheduler, ze_bool_t getDefaults, zes_sched_timeout_properties_t *pConfig)#

Get scheduler config for mode ZES_SCHED_MODE_TIMEOUT.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hScheduler – [in] Sysman handle for the component.

  • getDefaults – [in] If TRUE, the driver will return the system default properties for this mode, otherwise it will return the current properties.

  • pConfig – [in,out] Will contain the current parameters for this mode.

Returns:

zesSchedulerGetTimesliceModeProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesSchedulerGetTimesliceModeProperties(zes_sched_handle_t hScheduler, ze_bool_t getDefaults, zes_sched_timeslice_properties_t *pConfig)#

Get scheduler config for mode ZES_SCHED_MODE_TIMESLICE.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hScheduler – [in] Sysman handle for the component.

  • getDefaults – [in] If TRUE, the driver will return the system default properties for this mode, otherwise it will return the current properties.

  • pConfig – [in,out] Will contain the current parameters for this mode.

Returns:

zesSchedulerSetTimeoutMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesSchedulerSetTimeoutMode(zes_sched_handle_t hScheduler, zes_sched_timeout_properties_t *pProperties, ze_bool_t *pNeedReload)#

Change scheduler mode to ZES_SCHED_MODE_TIMEOUT or update scheduler mode parameters if already running in this mode.

  • This mode is optimized for multiple applications or contexts submitting work to the hardware. When higher priority work arrives, the scheduler attempts to pause the current executing work within some timeout interval, then submits the other work.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hScheduler – [in] Sysman handle for the component.

  • pProperties – [in] The properties to use when configurating this mode.

  • pNeedReload – [in,out] Will be set to TRUE if a device driver reload is needed to apply the new scheduler mode.

Returns:

zesSchedulerSetTimesliceMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesSchedulerSetTimesliceMode(zes_sched_handle_t hScheduler, zes_sched_timeslice_properties_t *pProperties, ze_bool_t *pNeedReload)#

Change scheduler mode to ZES_SCHED_MODE_TIMESLICE or update scheduler mode parameters if already running in this mode.

  • This mode is optimized to provide fair sharing of hardware execution time between multiple contexts submitting work to the hardware concurrently.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hScheduler – [in] Sysman handle for the component.

  • pProperties – [in] The properties to use when configurating this mode.

  • pNeedReload – [in,out] Will be set to TRUE if a device driver reload is needed to apply the new scheduler mode.

Returns:

zesSchedulerSetExclusiveMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesSchedulerSetExclusiveMode(zes_sched_handle_t hScheduler, ze_bool_t *pNeedReload)#

Change scheduler mode to ZES_SCHED_MODE_EXCLUSIVE.

  • This mode is optimized for single application/context use-cases. It permits a context to run indefinitely on the hardware without being preempted or terminated. All pending work for other contexts must wait until the running context completes with no further submitted work.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hScheduler – [in] Sysman handle for the component.

  • pNeedReload – [in,out] Will be set to TRUE if a device driver reload is needed to apply the new scheduler mode.

Returns:

zesSchedulerSetComputeUnitDebugMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesSchedulerSetComputeUnitDebugMode(zes_sched_handle_t hScheduler, ze_bool_t *pNeedReload)#

Change scheduler mode to ZES_SCHED_MODE_COMPUTE_UNIT_DEBUG.

  • This is a special mode that must ben enabled when debugging an application that uses this device e.g. using the Level0 Debug API.

  • It ensures that only one command queue can execute work on the hardware at a given time. Work is permitted to run as long as needed without enforcing any scheduler fairness policies.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hScheduler – [in] Sysman handle for the component.

  • pNeedReload – [in,out] Will be set to TRUE if a device driver reload is needed to apply the new scheduler mode.

Returns:

Scheduler Enums#

zes_sched_mode_t#

enum zes_sched_mode_t#

Scheduler mode.

Values:

enumerator ZES_SCHED_MODE_TIMEOUT#

Multiple applications or contexts are submitting work to the hardware. When higher priority work arrives, the scheduler attempts to pause the current executing work within some timeout interval, then submits the other work.

enumerator ZES_SCHED_MODE_TIMESLICE#

The scheduler attempts to fairly timeslice hardware execution time between multiple contexts submitting work to the hardware concurrently.

enumerator ZES_SCHED_MODE_EXCLUSIVE#

Any application or context can run indefinitely on the hardware without being preempted or terminated. All pending work for other contexts must wait until the running context completes with no further submitted work.

enumerator ZES_SCHED_MODE_COMPUTE_UNIT_DEBUG#

[DEPRECATED] No longer supported.

enumerator ZES_SCHED_MODE_FORCE_UINT32#

Scheduler Structures#

zes_sched_properties_t#

struct zes_sched_properties_t#

Properties related to scheduler component.

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 this 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

ze_bool_t canControl#

[out] Software can change the scheduler component configuration assuming the user has permissions.

zes_engine_type_flags_t engines#

[out] Bitfield of accelerator engine types that are managed by this scheduler component. Note that there can be more than one scheduler component for the same type of accelerator engine.

uint32_t supportedModes#

[out] Bitfield of scheduler modes that can be configured for this scheduler component (bitfield of 1<<zes_sched_mode_t).

zes_sched_timeout_properties_t#

struct zes_sched_timeout_properties_t#

Configuration for timeout scheduler mode (ZES_SCHED_MODE_TIMEOUT)

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

uint64_t watchdogTimeout#

[in,out] The maximum time in microseconds that the scheduler will wait for a batch of work submitted to a hardware engine to complete or to be preempted so as to run another context. If this time is exceeded, the hardware engine is reset and the context terminated. If set to ZES_SCHED_WATCHDOG_DISABLE, a running workload can run as long as it wants without being terminated, but preemption attempts to run other contexts are permitted but not enforced.

zes_sched_timeslice_properties_t#

struct zes_sched_timeslice_properties_t#

Configuration for timeslice scheduler mode (ZES_SCHED_MODE_TIMESLICE)

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

uint64_t interval#

[in,out] The average interval in microseconds that a submission for a context will run on a hardware engine before being preempted out to run a pending submission for another context.

uint64_t yieldTimeout#

[in,out] The maximum time in microseconds that the scheduler will wait to preempt a workload running on an engine before deciding to reset the hardware engine and terminating the associated context.

Standby#

Standby Functions#

zesDeviceEnumStandbyDomains#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumStandbyDomains(zes_device_handle_t hDevice, uint32_t *pCount, zes_standby_handle_t *phStandby)#

Get handle of standby controls.

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

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

  • phStandby – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesStandbyGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesStandbyGetProperties(zes_standby_handle_t hStandby, zes_standby_properties_t *pProperties)#

Get standby hardware component properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hStandby – [in] Handle for the component.

  • pProperties – [in,out] Will contain the standby hardware properties.

Returns:

zesStandbyGetMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesStandbyGetMode(zes_standby_handle_t hStandby, zes_standby_promo_mode_t *pMode)#

Get the current standby promotion mode.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hStandby – [in] Handle for the component.

  • pMode – [in,out] Will contain the current standby mode.

Returns:

zesStandbySetMode#

ZE_APIEXPORT ze_result_t ZE_APICALL zesStandbySetMode(zes_standby_handle_t hStandby, zes_standby_promo_mode_t mode)#

Set standby promotion mode.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hStandby – [in] Handle for the component.

  • mode – [in] New standby mode.

Returns:

Standby Enums#

zes_standby_type_t#

enum zes_standby_type_t#

Standby hardware components.

Values:

enumerator ZES_STANDBY_TYPE_GLOBAL#

Control the overall standby policy of the device/sub-device.

enumerator ZES_STANDBY_TYPE_FORCE_UINT32#

zes_standby_promo_mode_t#

enum zes_standby_promo_mode_t#

Standby promotion modes.

Values:

enumerator ZES_STANDBY_PROMO_MODE_DEFAULT#

Best compromise between performance and energy savings.

enumerator ZES_STANDBY_PROMO_MODE_NEVER#

The device/component will never shutdown. This can improve performance but uses more energy.

enumerator ZES_STANDBY_PROMO_MODE_FORCE_UINT32#

Standby Structures#

zes_standby_properties_t#

struct zes_standby_properties_t#

Standby hardware component 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_standby_type_t type#

[out] Which standby hardware component this controls

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

Temperature#

Temperature Functions#

zesDeviceEnumTemperatureSensors#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumTemperatureSensors(zes_device_handle_t hDevice, uint32_t *pCount, zes_temp_handle_t *phTemperature)#

Get handle of temperature sensors.

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

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

  • phTemperature – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesTemperatureGetProperties#

ZE_APIEXPORT ze_result_t ZE_APICALL zesTemperatureGetProperties(zes_temp_handle_t hTemperature, zes_temp_properties_t *pProperties)#

Get temperature sensor properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hTemperature – [in] Handle for the component.

  • pProperties – [in,out] Will contain the temperature sensor properties.

Returns:

zesTemperatureGetConfig#

ZE_APIEXPORT ze_result_t ZE_APICALL zesTemperatureGetConfig(zes_temp_handle_t hTemperature, zes_temp_config_t *pConfig)#

Get temperature configuration for this sensor - which events are triggered and the trigger conditions.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hTemperature – [in] Handle for the component.

  • pConfig – [in,out] Returns current configuration.

Returns:

zesTemperatureSetConfig#

ZE_APIEXPORT ze_result_t ZE_APICALL zesTemperatureSetConfig(zes_temp_handle_t hTemperature, const zes_temp_config_t *pConfig)#

Set temperature configuration for this sensor - indicates which events are triggered and the trigger conditions.

Parameters:

  • hTemperature – [in] Handle for the component.

  • pConfig – [in] New configuration.

Returns:

zesTemperatureGetState#

ZE_APIEXPORT ze_result_t ZE_APICALL zesTemperatureGetState(zes_temp_handle_t hTemperature, double *pTemperature)#

Get the temperature from a specified sensor.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hTemperature – [in] Handle for the component.

  • pTemperature – [in,out] Will contain the temperature read from the specified sensor in degrees Celsius.

Returns:

Temperature Enums#

zes_temp_sensors_t#

enum zes_temp_sensors_t#

Temperature sensors.

Values:

enumerator ZES_TEMP_SENSORS_GLOBAL#

The maximum temperature across all device sensors.

enumerator ZES_TEMP_SENSORS_GPU#

The maximum temperature across all sensors in the GPU.

enumerator ZES_TEMP_SENSORS_MEMORY#

The maximum temperature across all sensors in the local memory.

enumerator ZES_TEMP_SENSORS_GLOBAL_MIN#

The minimum temperature across all device sensors.

enumerator ZES_TEMP_SENSORS_GPU_MIN#

The minimum temperature across all sensors in the GPU.

enumerator ZES_TEMP_SENSORS_MEMORY_MIN#

The minimum temperature across all sensors in the local device memory.

enumerator ZES_TEMP_SENSORS_GPU_BOARD#

The maximum temperature across all sensors in the GPU Board.

enumerator ZES_TEMP_SENSORS_GPU_BOARD_MIN#

The minimum temperature across all sensors in the GPU Board.

enumerator ZES_TEMP_SENSORS_VOLTAGE_REGULATOR#

The maximum temperature across all sensors in the Voltage Regulator.

enumerator ZES_TEMP_SENSORS_FORCE_UINT32#

Temperature Structures#

zes_temp_properties_t#

struct zes_temp_properties_t#

Temperature sensor 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_temp_sensors_t type#

[out] Which part of the device the temperature sensor measures

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

double maxTemperature#

[out] Will contain the maximum temperature for the specific device in degrees Celsius.

ze_bool_t isCriticalTempSupported#

[out] Indicates if the critical temperature event ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL is supported

ze_bool_t isThreshold1Supported#

[out] Indicates if the temperature threshold 1 event ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1 is supported

ze_bool_t isThreshold2Supported#

[out] Indicates if the temperature threshold 2 event ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2 is supported

zes_temp_threshold_t#

struct zes_temp_threshold_t#

Temperature sensor threshold.

Public Members

ze_bool_t enableLowToHigh#

[in,out] Trigger an event when the temperature crosses from below the threshold to above.

ze_bool_t enableHighToLow#

[in,out] Trigger an event when the temperature crosses from above the threshold to below.

double threshold#

[in,out] The threshold in degrees Celsius.

zes_temp_config_t#

struct zes_temp_config_t#

Temperature configuration - which events should be triggered and the trigger conditions.

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

[in,out] Indicates if event ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL should be triggered by the driver.

zes_temp_threshold_t threshold1#

[in,out] Configuration controlling if and when event ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1 should be triggered by the driver.

zes_temp_threshold_t threshold2#

[in,out] Configuration controlling if and when event ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2 should be triggered by the driver.

Powerlimits#

Powerlimits Functions#

zesPowerGetLimitsExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetLimitsExt(zes_pwr_handle_t hPower, uint32_t *pCount, zes_power_limit_ext_desc_t *pSustained)#

Get power limits.

  • The application may call this function from simultaneous threads.

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

  • This function returns all the power limits associated with the supplied power domain.

Parameters:

  • hPower – [in] Power domain handle instance.

  • pCount – [in,out] Pointer to the number of power limit descriptors. If count is zero, then the driver shall update the value with the total number of components of this type that are available. If count is greater than the number of components of this type that are available, then the driver shall update the value with the correct number of components.

  • pSustained – [in,out][optional][range(0, *pCount)] Array of query results for power limit descriptors. If count is less than the number of components of this type that are available, then the driver shall only retrieve that number of components.

Returns:

zesPowerSetLimitsExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerSetLimitsExt(zes_pwr_handle_t hPower, uint32_t *pCount, zes_power_limit_ext_desc_t *pSustained)#

Set power limits.

  • The application can only modify unlocked members of the limit descriptors returned by zesPowerGetLimitsExt.

  • Not all the limits returned by zesPowerGetLimitsExt need to be supplied to this function.

  • Limits do not have to be supplied in the same order as returned by zesPowerGetLimitsExt.

  • The same limit can be supplied multiple times. Limits are applied in the order in which they are supplied.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hPower – [in] Handle for the component.

  • pCount – [in] Pointer to the number of power limit descriptors.

  • pSustained – [in][optional][range(0, *pCount)] Array of power limit descriptors.

Returns:

Powerlimits Enums#

zes_power_limits_ext_version_t#

enum zes_power_limits_ext_version_t#

Power Limits Extension Version(s)

Values:

enumerator ZES_POWER_LIMITS_EXT_VERSION_1_0#

version 1.0

enumerator ZES_POWER_LIMITS_EXT_VERSION_CURRENT#

latest known version

enumerator ZES_POWER_LIMITS_EXT_VERSION_FORCE_UINT32#

Powerlimits Structures#

zes_power_limit_ext_desc_t#

struct zes_power_limit_ext_desc_t#

Device power/current limit descriptor.

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_power_level_t level#

[in,out] duration type over which the power draw is measured, i.e. sustained, burst, peak, or critical.

zes_power_source_t source#

[out] source of power used by the system, i.e. AC or DC.

zes_limit_unit_t limitUnit#

[out] unit used for specifying limit, i.e. current units (milliamps) or power units (milliwatts).

ze_bool_t enabledStateLocked#

[out] indicates if the power limit state (enabled/ignored) can be set (false) or is locked (true).

ze_bool_t enabled#

[in,out] indicates if the limit is enabled (true) or ignored (false). If enabledStateIsLocked is True, this value is ignored.

ze_bool_t intervalValueLocked#

[out] indicates if the interval can be modified (false) or is fixed (true).

int32_t interval#

[in,out] power averaging window in milliseconds. If intervalValueLocked is true, this value is ignored.

ze_bool_t limitValueLocked#

[out] indicates if the limit can be set (false) or if the limit is fixed (true).

int32_t limit#

[in,out] limit value. If limitValueLocked is true, this value is ignored. The value should be provided in the unit specified by limitUnit.

zes_power_ext_properties_t#

struct zes_power_ext_properties_t#

Extension properties related to device power settings.

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_power_domain_t domain#

[out] domain that the power limit belongs to.

zes_power_limit_ext_desc_t *defaultLimit#

[out] the factory default limit of the part.

Engineactivity#

Engineactivity Functions#

zesEngineGetActivityExt#

ZE_APIEXPORT ze_result_t ZE_APICALL zesEngineGetActivityExt(zes_engine_handle_t hEngine, uint32_t *pCount, zes_engine_stats_t *pStats)#

Get activity stats for Physical Function (PF) and each Virtual Function (VF) associated with engine group.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEngine – [in] Handle for the component.

  • pCount – [in,out] Pointer to the number of VF engine stats descriptors.

    • if count is zero, the driver shall update the value with the total number of engine stats available.

    • if count is greater than the total number of engine stats available, the driver shall update the value with the correct number of engine stats available.

    • The count returned is the sum of number of VF instances currently available and the PF instance.

  • pStats – [in,out][optional][range(0, *pCount)] array of engine group activity counters.

    • if count is less than the total number of engine stats available, then driver shall only retrieve that number of stats.

    • the implementation shall populate the vector with engine stat for PF at index 0 of the vector followed by user provided pCount-1 number of VF engine stats.

Returns:

Engineactivity Enums#

zes_engine_activity_ext_version_t#

enum zes_engine_activity_ext_version_t#

Engine Activity Extension Version(s)

Values:

enumerator ZES_ENGINE_ACTIVITY_EXT_VERSION_1_0#

version 1.0

enumerator ZES_ENGINE_ACTIVITY_EXT_VERSION_CURRENT#

latest known version

enumerator ZES_ENGINE_ACTIVITY_EXT_VERSION_FORCE_UINT32#

Engineactivity Structures#

zes_engine_ext_properties_t#

struct zes_engine_ext_properties_t#

Extension properties related to Engine Groups.

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

[out] Number of Virtual Function(VF) instances associated with engine to monitor the utilization of hardware across all Virtual Function from a Physical Function (PF) instance. These VF-by-VF views should provide engine group and individual engine level granularity. This count represents the number of VF instances that are actively using the resource represented by the engine handle.

Rasstate#

Rasstate Functions#

zesRasGetStateExp#

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#

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:

Rasstate Enums#

zes_ras_state_exp_version_t#

enum zes_ras_state_exp_version_t#

RAS Get State Extension Version(s)

Values:

enumerator ZES_RAS_STATE_EXP_VERSION_1_0#

version 1.0

enumerator ZES_RAS_STATE_EXP_VERSION_CURRENT#

latest known version

enumerator ZES_RAS_STATE_EXP_VERSION_FORCE_UINT32#

zes_ras_error_category_exp_t#

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.

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

Rasstate Structures#

zes_ras_state_exp_t#

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.

Mempageofflinestate#

Mempageofflinestate Enums#

zes_mem_page_offline_state_exp_version_t#

enum zes_mem_page_offline_state_exp_version_t#

Memory State Extension Version(s)

Values:

enumerator ZES_MEM_PAGE_OFFLINE_STATE_EXP_VERSION_1_0#

version 1.0

enumerator ZES_MEM_PAGE_OFFLINE_STATE_EXP_VERSION_CURRENT#

latest known version

enumerator ZES_MEM_PAGE_OFFLINE_STATE_EXP_VERSION_FORCE_UINT32#

Mempageofflinestate Structures#

zes_mem_page_offline_state_exp_t#

struct zes_mem_page_offline_state_exp_t#

Extension properties for Memory State.

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

uint32_t memoryPageOffline#

[out] Returns the number of Memory Pages Offline

uint32_t maxMemoryPageOffline#

[out] Returns the Allowed Memory Pages Offline

Memorybwcountervalidbits#

Memorybwcountervalidbits Enums#

zes_mem_bandwidth_counter_bits_exp_version_t#

enum zes_mem_bandwidth_counter_bits_exp_version_t#

Memory Bandwidth Counter Valid Bits Extension Version(s)

Values:

enumerator ZES_MEM_BANDWIDTH_COUNTER_BITS_EXP_VERSION_1_0#

version 1.0

enumerator ZES_MEM_BANDWIDTH_COUNTER_BITS_EXP_VERSION_CURRENT#

latest known version

enumerator ZES_MEM_BANDWIDTH_COUNTER_BITS_EXP_VERSION_FORCE_UINT32#

Memorybwcountervalidbits Structures#

zes_mem_bandwidth_counter_bits_exp_properties_t#

struct zes_mem_bandwidth_counter_bits_exp_properties_t#

Extension properties for reporting valid bit count for memory bandwidth counter value.

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

[out] Returns the number of valid bits in the counter values

Powerdomainproperties#

Powerdomainproperties Enums#

zes_power_domain_properties_exp_version_t#

enum zes_power_domain_properties_exp_version_t#

Power Domain Properties Extension Version(s)

Values:

enumerator ZES_POWER_DOMAIN_PROPERTIES_EXP_VERSION_1_0#

version 1.0

enumerator ZES_POWER_DOMAIN_PROPERTIES_EXP_VERSION_CURRENT#

latest known version

enumerator ZES_POWER_DOMAIN_PROPERTIES_EXP_VERSION_FORCE_UINT32#

Powerdomainproperties Structures#

zes_power_domain_exp_properties_t#

struct zes_power_domain_exp_properties_t#

Extension structure for providing power domain information associated with a power handle.

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_power_domain_t powerDomain#

[out] Power domain associated with the power handle.

Firmwaresecurityversion#

Firmwaresecurityversion Functions#

zesFirmwareGetSecurityVersionExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFirmwareGetSecurityVersionExp(zes_firmware_handle_t hFirmware, char *pVersion)#

Get the firmware security version number of the currently running firmware.

  • The application should create a character array of size ZES_STRING_PROPERTY_SIZE and reference it for the pVersion parameter.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFirmware – [in] Handle for the component.

  • pVersion – [in,out] NULL terminated string value. The string “unknown” will be returned if this property cannot be determined.

Returns:

zesFirmwareSetSecurityVersionExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesFirmwareSetSecurityVersionExp(zes_firmware_handle_t hFirmware)#

Set the firmware security version number.

  • The application may call this function from simultaneous threads.

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

Parameters:

hFirmware – [in] Handle for the component.

Returns:

Firmwaresecurityversion Enums#

zes_firmware_security_exp_version_t#

enum zes_firmware_security_exp_version_t#

Firmware security version Extension Version(s)

Values:

enumerator ZES_FIRMWARE_SECURITY_EXP_VERSION_1_0#

version 1.0

enumerator ZES_FIRMWARE_SECURITY_EXP_VERSION_CURRENT#

latest known version

enumerator ZES_FIRMWARE_SECURITY_EXP_VERSION_FORCE_UINT32#

Sysmandevicemapping#

Sysmandevicemapping Functions#

zesDeviceGetSubDevicePropertiesExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceGetSubDevicePropertiesExp(zes_device_handle_t hDevice, uint32_t *pCount, zes_subdevice_exp_properties_t *pSubdeviceProps)#

Retrieves sub device properties for the given sysman device handle.

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

  • pCount – [in,out] pointer to the number of sub devices. if count is zero, then the driver shall update the value with the total number of sub devices currently attached to the device. if count is greater than the number of sub devices currently attached to the device, then the driver shall update the value with the correct number of sub devices.

  • pSubdeviceProps – [in,out][optional][range(0, *pCount)] array of sub device property structures. if count is less than the number of sysman sub devices available, then the driver shall only retrieve that number of sub device property structures.

Returns:

zesDriverGetDeviceByUuidExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverGetDeviceByUuidExp(zes_driver_handle_t hDriver, zes_uuid_t uuid, zes_device_handle_t *phDevice, ze_bool_t *onSubdevice, uint32_t *subdeviceId)#

Retrieves sysman device and subdevice index for the given UUID and sysman driver.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the sysman driver instance

  • uuid – [in] universal unique identifier.

  • phDevice – [out] Sysman handle of the device.

  • onSubdevice – [out] True if the UUID belongs to the sub-device; false means that UUID belongs to the root device.

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

Returns:

Sysmandevicemapping Enums#

zes_sysman_device_mapping_exp_version_t#

enum zes_sysman_device_mapping_exp_version_t#

Sysman Device Mapping Extension Version(s)

Values:

enumerator ZES_SYSMAN_DEVICE_MAPPING_EXP_VERSION_1_0#

version 1.0

enumerator ZES_SYSMAN_DEVICE_MAPPING_EXP_VERSION_CURRENT#

latest known version

enumerator ZES_SYSMAN_DEVICE_MAPPING_EXP_VERSION_FORCE_UINT32#

Sysmandevicemapping Structures#

zes_subdevice_exp_properties_t#

struct zes_subdevice_exp_properties_t#

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

uint32_t subdeviceId#

[out] this gives the ID of the sub device

zes_uuid_t uuid#

[out] universal unique identifier of the sub device.

Virtualfunctionmanagement#

Virtualfunctionmanagement Functions#

zesDeviceEnumActiveVFExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumActiveVFExp(zes_device_handle_t hDevice, uint32_t *pCount, zes_vf_handle_t *phVFhandle)#

Get handle of virtual function modules.

  • [DEPRECATED] No longer supported. Use zesDeviceEnumEnabledVFExp.

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

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

  • phVFhandle – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesVFManagementGetVFPropertiesExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFPropertiesExp(zes_vf_handle_t hVFhandle, zes_vf_exp_properties_t *pProperties)#

Get virtual function management properties.

  • [DEPRECATED] No longer supported. Use zesVFManagementGetVFCapabilitiesExp.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hVFhandle – [in] Sysman handle for the VF component.

  • pProperties – [in,out] Will contain VF properties.

Returns:

zesVFManagementGetVFMemoryUtilizationExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFMemoryUtilizationExp(zes_vf_handle_t hVFhandle, uint32_t *pCount, zes_vf_util_mem_exp_t *pMemUtil)#

Get memory activity stats for each available memory types associated with Virtual Function (VF)

  • [DEPRECATED] No longer supported. Use zesVFManagementGetVFMemoryUtilizationExp2.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hVFhandle – [in] Sysman handle for the component.

  • pCount – [in,out] Pointer to the number of VF memory stats descriptors.

    • if count is zero, the driver shall update the value with the total number of memory stats available.

    • if count is greater than the total number of memory stats available, the driver shall update the value with the correct number of memory stats available.

    • The count returned is the sum of number of VF instances currently available and the PF instance.

  • pMemUtil – [in,out][optional][range(0, *pCount)] array of memory group activity counters.

    • if count is less than the total number of memory stats available, then driver shall only retrieve that number of stats.

    • the implementation shall populate the vector pCount-1 number of VF memory stats.

Returns:

zesVFManagementGetVFEngineUtilizationExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFEngineUtilizationExp(zes_vf_handle_t hVFhandle, uint32_t *pCount, zes_vf_util_engine_exp_t *pEngineUtil)#

Get engine activity stats for each available engine group associated with Virtual Function (VF)

  • [DEPRECATED] No longer supported. Use zesVFManagementGetVFEngineUtilizationExp2.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hVFhandle – [in] Sysman handle for the component.

  • pCount – [in,out] Pointer to the number of VF engine stats descriptors.

    • if count is zero, the driver shall update the value with the total number of engine stats available.

    • if count is greater than the total number of engine stats available, the driver shall update the value with the correct number of engine stats available.

    • The count returned is the sum of number of VF instances currently available and the PF instance.

  • pEngineUtil – [in,out][optional][range(0, *pCount)] array of engine group activity counters.

    • if count is less than the total number of engine stats available, then driver shall only retrieve that number of stats.

    • the implementation shall populate the vector pCount-1 number of VF engine stats.

Returns:

zesVFManagementSetVFTelemetryModeExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementSetVFTelemetryModeExp(zes_vf_handle_t hVFhandle, zes_vf_info_util_exp_flags_t flags, ze_bool_t enable)#

Configure utilization telemetry enabled or disabled associated with Virtual Function (VF)

  • [DEPRECATED] No longer supported.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hVFhandle – [in] Sysman handle for the component.

  • flags – [in] utilization flags to enable or disable. May be 0 or a valid combination of zes_vf_info_util_exp_flag_t.

  • enable – [in] Enable utilization telemetry.

Returns:

zesVFManagementSetVFTelemetrySamplingIntervalExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementSetVFTelemetrySamplingIntervalExp(zes_vf_handle_t hVFhandle, zes_vf_info_util_exp_flags_t flag, uint64_t samplingInterval)#

Set sampling interval to monitor for a particular utilization telemetry associated with Virtual Function (VF)

  • [DEPRECATED] No longer supported.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hVFhandle – [in] Sysman handle for the component.

  • flag – [in] utilization flags to set sampling interval. May be 0 or a valid combination of zes_vf_info_util_exp_flag_t.

  • samplingInterval – [in] Sampling interval value.

Returns:

zesDeviceEnumEnabledVFExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesDeviceEnumEnabledVFExp(zes_device_handle_t hDevice, uint32_t *pCount, zes_vf_handle_t *phVFhandle)#

Get handle of virtual function modules.

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

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

  • phVFhandle – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

zesVFManagementGetVFCapabilitiesExp#

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFCapabilitiesExp(zes_vf_handle_t hVFhandle, zes_vf_exp_capabilities_t *pCapability)#

Get virtual function management capabilities.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hVFhandle – [in] Sysman handle for the VF component.

  • pCapability – [in,out] Will contain VF capability.

Returns:

zesVFManagementGetVFMemoryUtilizationExp2#

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFMemoryUtilizationExp2(zes_vf_handle_t hVFhandle, uint32_t *pCount, zes_vf_util_mem_exp2_t *pMemUtil)#

Get memory activity stats for each available memory types associated with Virtual Function (VF)

  • The application may call this function from simultaneous threads.

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

  • If VF is disable/pause/not active, utilization will give zero value.

Parameters:

  • hVFhandle – [in] Sysman handle for the component.

  • pCount – [in,out] Pointer to the number of VF memory stats descriptors.

    • if count is zero, the driver shall update the value with the total number of memory stats available.

    • if count is greater than the total number of memory stats available, the driver shall update the value with the correct number of memory stats available.

  • pMemUtil – [in,out][optional][range(0, *pCount)] array of memory group activity counters.

    • if count is less than the total number of memory stats available, then driver shall only retrieve that number of stats.

    • the implementation shall populate the vector pCount-1 number of VF memory stats.

Returns:

zesVFManagementGetVFEngineUtilizationExp2#

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFEngineUtilizationExp2(zes_vf_handle_t hVFhandle, uint32_t *pCount, zes_vf_util_engine_exp2_t *pEngineUtil)#

Get engine activity stats for each available engine group associated with Virtual Function (VF)

  • The application may call this function from simultaneous threads.

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

  • If VF is disable/pause/not active, utilization will give zero value.

Parameters:

  • hVFhandle – [in] Sysman handle for the component.

  • pCount – [in,out] Pointer to the number of VF engine stats descriptors.

    • if count is zero, the driver shall update the value with the total number of engine stats available.

    • if count is greater than the total number of engine stats available, the driver shall update the value with the correct number of engine stats available.

  • pEngineUtil – [in,out][optional][range(0, *pCount)] array of engine group activity counters.

    • if count is less than the total number of engine stats available, then driver shall only retrieve that number of stats.

    • the implementation shall populate the vector pCount-1 number of VF engine stats.

Returns:

Virtualfunctionmanagement Enums#

zes_vf_management_exp_version_t#

enum zes_vf_management_exp_version_t#

Virtual Function Management Extension Version(s)

Values:

enumerator ZES_VF_MANAGEMENT_EXP_VERSION_1_0#

version 1.0 (deprecated)

enumerator ZES_VF_MANAGEMENT_EXP_VERSION_1_1#

version 1.1 (deprecated)

enumerator ZES_VF_MANAGEMENT_EXP_VERSION_1_2#

version 1.2

enumerator ZES_VF_MANAGEMENT_EXP_VERSION_CURRENT#

latest known version

enumerator ZES_VF_MANAGEMENT_EXP_VERSION_FORCE_UINT32#

zes_vf_info_mem_type_exp_flags_t#

enum zes_vf_info_mem_type_exp_flag_t#

Values:

enumerator ZES_VF_INFO_MEM_TYPE_EXP_FLAG_MEM_TYPE_SYSTEM#

System memory.

enumerator ZES_VF_INFO_MEM_TYPE_EXP_FLAG_MEM_TYPE_DEVICE#

Device local memory.

enumerator ZES_VF_INFO_MEM_TYPE_EXP_FLAG_FORCE_UINT32#

zes_vf_info_util_exp_flags_t#

enum zes_vf_info_util_exp_flag_t#

Values:

enumerator ZES_VF_INFO_UTIL_EXP_FLAG_INFO_NONE#

No info associated with virtual function.

enumerator ZES_VF_INFO_UTIL_EXP_FLAG_INFO_MEM_CPU#

System memory utilization associated with virtual function.

enumerator ZES_VF_INFO_UTIL_EXP_FLAG_INFO_MEM_GPU#

Device memory utilization associated with virtual function.

enumerator ZES_VF_INFO_UTIL_EXP_FLAG_INFO_ENGINE#

Engine utilization associated with virtual function.

enumerator ZES_VF_INFO_UTIL_EXP_FLAG_FORCE_UINT32#

Virtualfunctionmanagement Structures#

zes_vf_exp_properties_t#

struct zes_vf_exp_properties_t#

Virtual function management properties (deprecated)

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_pci_address_t address#

[out] Virtual function BDF address

zes_uuid_t uuid#

[out] universal unique identifier of the device

zes_vf_info_util_exp_flags_t flags#

[out] utilization flags available. May be 0 or a valid combination of zes_vf_info_util_exp_flag_t.

zes_vf_util_mem_exp_t#

struct zes_vf_util_mem_exp_t#

Provides memory utilization values for a virtual function (deprecated)

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_vf_info_mem_type_exp_flags_t memTypeFlags#

[out] Memory type flags.

uint64_t free#

[out] Free memory size in bytes.

uint64_t size#

[out] Total allocatable memory in bytes.

uint64_t timestamp#

[out] Wall clock time from VF when value was sampled.

zes_vf_util_engine_exp_t#

struct zes_vf_util_engine_exp_t#

Provides engine utilization values for a virtual function (deprecated)

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_engine_group_t type#

[out] The engine group.

uint64_t activeCounterValue#

[out] Represents active counter.

uint64_t samplingCounterValue#

[out] Represents counter value when activeCounterValue was sampled.

uint64_t timestamp#

[out] Wall clock time when the activeCounterValue was sampled.

zes_vf_exp_capabilities_t#

struct zes_vf_exp_capabilities_t#

Virtual function management capabilities.

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_pci_address_t address#

[out] Virtual function BDF address

uint32_t vfDeviceMemSize#

[out] Virtual function memory size in bytes

uint32_t vfID#

[out] Virtual Function ID

zes_vf_util_mem_exp2_t#

struct zes_vf_util_mem_exp2_t#

Provides memory utilization values for a virtual function.

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_mem_loc_t vfMemLocation#

[out] Location of this memory (system, device)

uint64_t vfMemUtilized#

[out] Free memory size in bytes.

zes_vf_util_engine_exp2_t#

struct zes_vf_util_engine_exp2_t#

Provides engine utilization values for a virtual function.

  • Percent utilization is calculated by taking two snapshots (s1, s2) and using the equation: util = (s2.activeCounterValue - s1.activeCounterValue) / (s2.samplingCounterValue - s1.samplingCounterValue)

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_engine_group_t vfEngineType#

[out] The engine group.

uint64_t activeCounterValue#

[out] Represents active counter.

uint64_t samplingCounterValue#

[out] Represents counter value when activeCounterValue was sampled. Refer to the formulae above for calculating the utilization percent

Contents