Device

Device#

oneAPI Level Zero Specification - Version 1.18.31

Device Functions#

zesDeviceGetProperties#

Added in version 1.0

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#

Added in version 1.0

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#

Added in version 1.0

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:

zesDeviceProcessesGetState#

Added in version 1.0

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#

Added in version 1.0

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#

Added in version 1.0

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#

Added in version 1.0

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#

Added in version 1.0

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:

zesDeviceEnumDiagnosticTestSuites#

Added in version 1.0

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:

zesDeviceEnumEngineGroups#

Added in version 1.0

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:

zesDeviceEventRegister#

Added in version 1.0

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:

zesDeviceEnumFabricPorts#

Added in version 1.0

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:

zesDeviceEnumFans#

Added in version 1.0

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:

zesDeviceEnumFirmwares#

Added in version 1.0

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:

zesDeviceEnumFrequencyDomains#

Added in version 1.0

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:

zesDeviceEnumLeds#

Added in version 1.0

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:

zesDeviceEnumMemoryModules#

Added in version 1.0

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:

zesDeviceEnumPerformanceFactorDomains#

Added in version 1.0

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:

zesDeviceEnumPowerDomains#

Added in version 1.0

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#

Added in version 1.0

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:

zesDeviceEnumPsus#

Added in version 1.0

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:

zesDeviceEnumRasErrorSets#

Added in version 1.0

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:

zesDeviceEnumSchedulers#

Added in version 1.0

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:

zesDeviceEnumStandbyDomains#

Added in version 1.0

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:

zesDeviceEnumTemperatureSensors#

Added in version 1.0

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: