1 /* 2 * 3 * Copyright (C) 2019-2021 Intel Corporation 4 * 5 * SPDX-License-Identifier: MIT 6 * 7 * @file zes_api.h 8 * @version v1.3-r1.3.7 9 * 10 */ 11 #ifndef _ZES_API_H 12 #define _ZES_API_H 13 #if defined(__cplusplus) 14 #pragma once 15 #endif 16 17 // 'core' API headers 18 #include "ze_api.h" 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 // Intel 'oneAPI' Level-Zero Sysman API common types 25 #if !defined(__GNUC__) 26 #pragma region common 27 #endif 28 /////////////////////////////////////////////////////////////////////////////// 29 /// @brief Handle to a driver instance 30 typedef ze_driver_handle_t zes_driver_handle_t; 31 32 /////////////////////////////////////////////////////////////////////////////// 33 /// @brief Handle of device object 34 typedef ze_device_handle_t zes_device_handle_t; 35 36 /////////////////////////////////////////////////////////////////////////////// 37 /// @brief Handle for a Sysman device scheduler queue 38 typedef struct _zes_sched_handle_t *zes_sched_handle_t; 39 40 /////////////////////////////////////////////////////////////////////////////// 41 /// @brief Handle for a Sysman device performance factors 42 typedef struct _zes_perf_handle_t *zes_perf_handle_t; 43 44 /////////////////////////////////////////////////////////////////////////////// 45 /// @brief Handle for a Sysman device power domain 46 typedef struct _zes_pwr_handle_t *zes_pwr_handle_t; 47 48 /////////////////////////////////////////////////////////////////////////////// 49 /// @brief Handle for a Sysman device frequency domain 50 typedef struct _zes_freq_handle_t *zes_freq_handle_t; 51 52 /////////////////////////////////////////////////////////////////////////////// 53 /// @brief Handle for a Sysman device engine group 54 typedef struct _zes_engine_handle_t *zes_engine_handle_t; 55 56 /////////////////////////////////////////////////////////////////////////////// 57 /// @brief Handle for a Sysman device standby control 58 typedef struct _zes_standby_handle_t *zes_standby_handle_t; 59 60 /////////////////////////////////////////////////////////////////////////////// 61 /// @brief Handle for a Sysman device firmware 62 typedef struct _zes_firmware_handle_t *zes_firmware_handle_t; 63 64 /////////////////////////////////////////////////////////////////////////////// 65 /// @brief Handle for a Sysman device memory module 66 typedef struct _zes_mem_handle_t *zes_mem_handle_t; 67 68 /////////////////////////////////////////////////////////////////////////////// 69 /// @brief Handle for a Sysman fabric port 70 typedef struct _zes_fabric_port_handle_t *zes_fabric_port_handle_t; 71 72 /////////////////////////////////////////////////////////////////////////////// 73 /// @brief Handle for a Sysman device temperature sensor 74 typedef struct _zes_temp_handle_t *zes_temp_handle_t; 75 76 /////////////////////////////////////////////////////////////////////////////// 77 /// @brief Handle for a Sysman device power supply 78 typedef struct _zes_psu_handle_t *zes_psu_handle_t; 79 80 /////////////////////////////////////////////////////////////////////////////// 81 /// @brief Handle for a Sysman device fan 82 typedef struct _zes_fan_handle_t *zes_fan_handle_t; 83 84 /////////////////////////////////////////////////////////////////////////////// 85 /// @brief Handle for a Sysman device LED 86 typedef struct _zes_led_handle_t *zes_led_handle_t; 87 88 /////////////////////////////////////////////////////////////////////////////// 89 /// @brief Handle for a Sysman device RAS error set 90 typedef struct _zes_ras_handle_t *zes_ras_handle_t; 91 92 /////////////////////////////////////////////////////////////////////////////// 93 /// @brief Handle for a Sysman device diagnostics test suite 94 typedef struct _zes_diag_handle_t *zes_diag_handle_t; 95 96 /////////////////////////////////////////////////////////////////////////////// 97 /// @brief Defines structure types 98 typedef enum _zes_structure_type_t 99 { 100 ZES_STRUCTURE_TYPE_DEVICE_PROPERTIES = 0x1, ///< ::zes_device_properties_t 101 ZES_STRUCTURE_TYPE_PCI_PROPERTIES = 0x2, ///< ::zes_pci_properties_t 102 ZES_STRUCTURE_TYPE_PCI_BAR_PROPERTIES = 0x3, ///< ::zes_pci_bar_properties_t 103 ZES_STRUCTURE_TYPE_DIAG_PROPERTIES = 0x4, ///< ::zes_diag_properties_t 104 ZES_STRUCTURE_TYPE_ENGINE_PROPERTIES = 0x5, ///< ::zes_engine_properties_t 105 ZES_STRUCTURE_TYPE_FABRIC_PORT_PROPERTIES = 0x6,///< ::zes_fabric_port_properties_t 106 ZES_STRUCTURE_TYPE_FAN_PROPERTIES = 0x7, ///< ::zes_fan_properties_t 107 ZES_STRUCTURE_TYPE_FIRMWARE_PROPERTIES = 0x8, ///< ::zes_firmware_properties_t 108 ZES_STRUCTURE_TYPE_FREQ_PROPERTIES = 0x9, ///< ::zes_freq_properties_t 109 ZES_STRUCTURE_TYPE_LED_PROPERTIES = 0xa, ///< ::zes_led_properties_t 110 ZES_STRUCTURE_TYPE_MEM_PROPERTIES = 0xb, ///< ::zes_mem_properties_t 111 ZES_STRUCTURE_TYPE_PERF_PROPERTIES = 0xc, ///< ::zes_perf_properties_t 112 ZES_STRUCTURE_TYPE_POWER_PROPERTIES = 0xd, ///< ::zes_power_properties_t 113 ZES_STRUCTURE_TYPE_PSU_PROPERTIES = 0xe, ///< ::zes_psu_properties_t 114 ZES_STRUCTURE_TYPE_RAS_PROPERTIES = 0xf, ///< ::zes_ras_properties_t 115 ZES_STRUCTURE_TYPE_SCHED_PROPERTIES = 0x10, ///< ::zes_sched_properties_t 116 ZES_STRUCTURE_TYPE_SCHED_TIMEOUT_PROPERTIES = 0x11, ///< ::zes_sched_timeout_properties_t 117 ZES_STRUCTURE_TYPE_SCHED_TIMESLICE_PROPERTIES = 0x12, ///< ::zes_sched_timeslice_properties_t 118 ZES_STRUCTURE_TYPE_STANDBY_PROPERTIES = 0x13, ///< ::zes_standby_properties_t 119 ZES_STRUCTURE_TYPE_TEMP_PROPERTIES = 0x14, ///< ::zes_temp_properties_t 120 ZES_STRUCTURE_TYPE_DEVICE_STATE = 0x15, ///< ::zes_device_state_t 121 ZES_STRUCTURE_TYPE_PROCESS_STATE = 0x16, ///< ::zes_process_state_t 122 ZES_STRUCTURE_TYPE_PCI_STATE = 0x17, ///< ::zes_pci_state_t 123 ZES_STRUCTURE_TYPE_FABRIC_PORT_CONFIG = 0x18, ///< ::zes_fabric_port_config_t 124 ZES_STRUCTURE_TYPE_FABRIC_PORT_STATE = 0x19, ///< ::zes_fabric_port_state_t 125 ZES_STRUCTURE_TYPE_FAN_CONFIG = 0x1a, ///< ::zes_fan_config_t 126 ZES_STRUCTURE_TYPE_FREQ_STATE = 0x1b, ///< ::zes_freq_state_t 127 ZES_STRUCTURE_TYPE_OC_CAPABILITIES = 0x1c, ///< ::zes_oc_capabilities_t 128 ZES_STRUCTURE_TYPE_LED_STATE = 0x1d, ///< ::zes_led_state_t 129 ZES_STRUCTURE_TYPE_MEM_STATE = 0x1e, ///< ::zes_mem_state_t 130 ZES_STRUCTURE_TYPE_PSU_STATE = 0x1f, ///< ::zes_psu_state_t 131 ZES_STRUCTURE_TYPE_BASE_STATE = 0x20, ///< ::zes_base_state_t 132 ZES_STRUCTURE_TYPE_RAS_CONFIG = 0x21, ///< ::zes_ras_config_t 133 ZES_STRUCTURE_TYPE_RAS_STATE = 0x22, ///< ::zes_ras_state_t 134 ZES_STRUCTURE_TYPE_TEMP_CONFIG = 0x23, ///< ::zes_temp_config_t 135 ZES_STRUCTURE_TYPE_PCI_BAR_PROPERTIES_1_2 = 0x24, ///< ::zes_pci_bar_properties_1_2_t 136 ZES_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff 137 138 } zes_structure_type_t; 139 140 /////////////////////////////////////////////////////////////////////////////// 141 /// @brief Base for all properties types 142 typedef struct _zes_base_properties_t 143 { 144 zes_structure_type_t stype; ///< [in] type of this structure 145 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 146 147 } zes_base_properties_t; 148 149 /////////////////////////////////////////////////////////////////////////////// 150 /// @brief Base for all descriptor types 151 typedef struct _zes_base_desc_t 152 { 153 zes_structure_type_t stype; ///< [in] type of this structure 154 const void* pNext; ///< [in][optional] pointer to extension-specific structure 155 156 } zes_base_desc_t; 157 158 /////////////////////////////////////////////////////////////////////////////// 159 /// @brief Base for all state types 160 typedef struct _zes_base_state_t 161 { 162 zes_structure_type_t stype; ///< [in] type of this structure 163 const void* pNext; ///< [in][optional] pointer to extension-specific structure 164 165 } zes_base_state_t; 166 167 /////////////////////////////////////////////////////////////////////////////// 168 /// @brief Base for all config types 169 typedef struct _zes_base_config_t 170 { 171 zes_structure_type_t stype; ///< [in] type of this structure 172 const void* pNext; ///< [in][optional] pointer to extension-specific structure 173 174 } zes_base_config_t; 175 176 /////////////////////////////////////////////////////////////////////////////// 177 /// @brief Base for all capability types 178 typedef struct _zes_base_capability_t 179 { 180 zes_structure_type_t stype; ///< [in] type of this structure 181 const void* pNext; ///< [in][optional] pointer to extension-specific structure 182 183 } zes_base_capability_t; 184 185 /////////////////////////////////////////////////////////////////////////////// 186 /// @brief Forward-declare zes_base_properties_t 187 typedef struct _zes_base_properties_t zes_base_properties_t; 188 189 /////////////////////////////////////////////////////////////////////////////// 190 /// @brief Forward-declare zes_base_desc_t 191 typedef struct _zes_base_desc_t zes_base_desc_t; 192 193 /////////////////////////////////////////////////////////////////////////////// 194 /// @brief Forward-declare zes_base_state_t 195 typedef struct _zes_base_state_t zes_base_state_t; 196 197 /////////////////////////////////////////////////////////////////////////////// 198 /// @brief Forward-declare zes_base_config_t 199 typedef struct _zes_base_config_t zes_base_config_t; 200 201 /////////////////////////////////////////////////////////////////////////////// 202 /// @brief Forward-declare zes_base_capability_t 203 typedef struct _zes_base_capability_t zes_base_capability_t; 204 205 /////////////////////////////////////////////////////////////////////////////// 206 /// @brief Forward-declare zes_device_state_t 207 typedef struct _zes_device_state_t zes_device_state_t; 208 209 /////////////////////////////////////////////////////////////////////////////// 210 /// @brief Forward-declare zes_device_properties_t 211 typedef struct _zes_device_properties_t zes_device_properties_t; 212 213 /////////////////////////////////////////////////////////////////////////////// 214 /// @brief Forward-declare zes_process_state_t 215 typedef struct _zes_process_state_t zes_process_state_t; 216 217 /////////////////////////////////////////////////////////////////////////////// 218 /// @brief Forward-declare zes_pci_address_t 219 typedef struct _zes_pci_address_t zes_pci_address_t; 220 221 /////////////////////////////////////////////////////////////////////////////// 222 /// @brief Forward-declare zes_pci_speed_t 223 typedef struct _zes_pci_speed_t zes_pci_speed_t; 224 225 /////////////////////////////////////////////////////////////////////////////// 226 /// @brief Forward-declare zes_pci_properties_t 227 typedef struct _zes_pci_properties_t zes_pci_properties_t; 228 229 /////////////////////////////////////////////////////////////////////////////// 230 /// @brief Forward-declare zes_pci_state_t 231 typedef struct _zes_pci_state_t zes_pci_state_t; 232 233 /////////////////////////////////////////////////////////////////////////////// 234 /// @brief Forward-declare zes_pci_bar_properties_t 235 typedef struct _zes_pci_bar_properties_t zes_pci_bar_properties_t; 236 237 /////////////////////////////////////////////////////////////////////////////// 238 /// @brief Forward-declare zes_pci_bar_properties_1_2_t 239 typedef struct _zes_pci_bar_properties_1_2_t zes_pci_bar_properties_1_2_t; 240 241 /////////////////////////////////////////////////////////////////////////////// 242 /// @brief Forward-declare zes_pci_stats_t 243 typedef struct _zes_pci_stats_t zes_pci_stats_t; 244 245 /////////////////////////////////////////////////////////////////////////////// 246 /// @brief Forward-declare zes_diag_test_t 247 typedef struct _zes_diag_test_t zes_diag_test_t; 248 249 /////////////////////////////////////////////////////////////////////////////// 250 /// @brief Forward-declare zes_diag_properties_t 251 typedef struct _zes_diag_properties_t zes_diag_properties_t; 252 253 /////////////////////////////////////////////////////////////////////////////// 254 /// @brief Forward-declare zes_engine_properties_t 255 typedef struct _zes_engine_properties_t zes_engine_properties_t; 256 257 /////////////////////////////////////////////////////////////////////////////// 258 /// @brief Forward-declare zes_engine_stats_t 259 typedef struct _zes_engine_stats_t zes_engine_stats_t; 260 261 /////////////////////////////////////////////////////////////////////////////// 262 /// @brief Forward-declare zes_fabric_port_id_t 263 typedef struct _zes_fabric_port_id_t zes_fabric_port_id_t; 264 265 /////////////////////////////////////////////////////////////////////////////// 266 /// @brief Forward-declare zes_fabric_port_speed_t 267 typedef struct _zes_fabric_port_speed_t zes_fabric_port_speed_t; 268 269 /////////////////////////////////////////////////////////////////////////////// 270 /// @brief Forward-declare zes_fabric_port_properties_t 271 typedef struct _zes_fabric_port_properties_t zes_fabric_port_properties_t; 272 273 /////////////////////////////////////////////////////////////////////////////// 274 /// @brief Forward-declare zes_fabric_link_type_t 275 typedef struct _zes_fabric_link_type_t zes_fabric_link_type_t; 276 277 /////////////////////////////////////////////////////////////////////////////// 278 /// @brief Forward-declare zes_fabric_port_config_t 279 typedef struct _zes_fabric_port_config_t zes_fabric_port_config_t; 280 281 /////////////////////////////////////////////////////////////////////////////// 282 /// @brief Forward-declare zes_fabric_port_state_t 283 typedef struct _zes_fabric_port_state_t zes_fabric_port_state_t; 284 285 /////////////////////////////////////////////////////////////////////////////// 286 /// @brief Forward-declare zes_fabric_port_throughput_t 287 typedef struct _zes_fabric_port_throughput_t zes_fabric_port_throughput_t; 288 289 /////////////////////////////////////////////////////////////////////////////// 290 /// @brief Forward-declare zes_fan_speed_t 291 typedef struct _zes_fan_speed_t zes_fan_speed_t; 292 293 /////////////////////////////////////////////////////////////////////////////// 294 /// @brief Forward-declare zes_fan_temp_speed_t 295 typedef struct _zes_fan_temp_speed_t zes_fan_temp_speed_t; 296 297 /////////////////////////////////////////////////////////////////////////////// 298 /// @brief Forward-declare zes_fan_speed_table_t 299 typedef struct _zes_fan_speed_table_t zes_fan_speed_table_t; 300 301 /////////////////////////////////////////////////////////////////////////////// 302 /// @brief Forward-declare zes_fan_properties_t 303 typedef struct _zes_fan_properties_t zes_fan_properties_t; 304 305 /////////////////////////////////////////////////////////////////////////////// 306 /// @brief Forward-declare zes_fan_config_t 307 typedef struct _zes_fan_config_t zes_fan_config_t; 308 309 /////////////////////////////////////////////////////////////////////////////// 310 /// @brief Forward-declare zes_firmware_properties_t 311 typedef struct _zes_firmware_properties_t zes_firmware_properties_t; 312 313 /////////////////////////////////////////////////////////////////////////////// 314 /// @brief Forward-declare zes_freq_properties_t 315 typedef struct _zes_freq_properties_t zes_freq_properties_t; 316 317 /////////////////////////////////////////////////////////////////////////////// 318 /// @brief Forward-declare zes_freq_range_t 319 typedef struct _zes_freq_range_t zes_freq_range_t; 320 321 /////////////////////////////////////////////////////////////////////////////// 322 /// @brief Forward-declare zes_freq_state_t 323 typedef struct _zes_freq_state_t zes_freq_state_t; 324 325 /////////////////////////////////////////////////////////////////////////////// 326 /// @brief Forward-declare zes_freq_throttle_time_t 327 typedef struct _zes_freq_throttle_time_t zes_freq_throttle_time_t; 328 329 /////////////////////////////////////////////////////////////////////////////// 330 /// @brief Forward-declare zes_oc_capabilities_t 331 typedef struct _zes_oc_capabilities_t zes_oc_capabilities_t; 332 333 /////////////////////////////////////////////////////////////////////////////// 334 /// @brief Forward-declare zes_led_properties_t 335 typedef struct _zes_led_properties_t zes_led_properties_t; 336 337 /////////////////////////////////////////////////////////////////////////////// 338 /// @brief Forward-declare zes_led_color_t 339 typedef struct _zes_led_color_t zes_led_color_t; 340 341 /////////////////////////////////////////////////////////////////////////////// 342 /// @brief Forward-declare zes_led_state_t 343 typedef struct _zes_led_state_t zes_led_state_t; 344 345 /////////////////////////////////////////////////////////////////////////////// 346 /// @brief Forward-declare zes_mem_properties_t 347 typedef struct _zes_mem_properties_t zes_mem_properties_t; 348 349 /////////////////////////////////////////////////////////////////////////////// 350 /// @brief Forward-declare zes_mem_state_t 351 typedef struct _zes_mem_state_t zes_mem_state_t; 352 353 /////////////////////////////////////////////////////////////////////////////// 354 /// @brief Forward-declare zes_mem_bandwidth_t 355 typedef struct _zes_mem_bandwidth_t zes_mem_bandwidth_t; 356 357 /////////////////////////////////////////////////////////////////////////////// 358 /// @brief Forward-declare zes_perf_properties_t 359 typedef struct _zes_perf_properties_t zes_perf_properties_t; 360 361 /////////////////////////////////////////////////////////////////////////////// 362 /// @brief Forward-declare zes_power_properties_t 363 typedef struct _zes_power_properties_t zes_power_properties_t; 364 365 /////////////////////////////////////////////////////////////////////////////// 366 /// @brief Forward-declare zes_power_energy_counter_t 367 typedef struct _zes_power_energy_counter_t zes_power_energy_counter_t; 368 369 /////////////////////////////////////////////////////////////////////////////// 370 /// @brief Forward-declare zes_power_sustained_limit_t 371 typedef struct _zes_power_sustained_limit_t zes_power_sustained_limit_t; 372 373 /////////////////////////////////////////////////////////////////////////////// 374 /// @brief Forward-declare zes_power_burst_limit_t 375 typedef struct _zes_power_burst_limit_t zes_power_burst_limit_t; 376 377 /////////////////////////////////////////////////////////////////////////////// 378 /// @brief Forward-declare zes_power_peak_limit_t 379 typedef struct _zes_power_peak_limit_t zes_power_peak_limit_t; 380 381 /////////////////////////////////////////////////////////////////////////////// 382 /// @brief Forward-declare zes_energy_threshold_t 383 typedef struct _zes_energy_threshold_t zes_energy_threshold_t; 384 385 /////////////////////////////////////////////////////////////////////////////// 386 /// @brief Forward-declare zes_psu_properties_t 387 typedef struct _zes_psu_properties_t zes_psu_properties_t; 388 389 /////////////////////////////////////////////////////////////////////////////// 390 /// @brief Forward-declare zes_psu_state_t 391 typedef struct _zes_psu_state_t zes_psu_state_t; 392 393 /////////////////////////////////////////////////////////////////////////////// 394 /// @brief Forward-declare zes_ras_properties_t 395 typedef struct _zes_ras_properties_t zes_ras_properties_t; 396 397 /////////////////////////////////////////////////////////////////////////////// 398 /// @brief Forward-declare zes_ras_state_t 399 typedef struct _zes_ras_state_t zes_ras_state_t; 400 401 /////////////////////////////////////////////////////////////////////////////// 402 /// @brief Forward-declare zes_ras_config_t 403 typedef struct _zes_ras_config_t zes_ras_config_t; 404 405 /////////////////////////////////////////////////////////////////////////////// 406 /// @brief Forward-declare zes_sched_properties_t 407 typedef struct _zes_sched_properties_t zes_sched_properties_t; 408 409 /////////////////////////////////////////////////////////////////////////////// 410 /// @brief Forward-declare zes_sched_timeout_properties_t 411 typedef struct _zes_sched_timeout_properties_t zes_sched_timeout_properties_t; 412 413 /////////////////////////////////////////////////////////////////////////////// 414 /// @brief Forward-declare zes_sched_timeslice_properties_t 415 typedef struct _zes_sched_timeslice_properties_t zes_sched_timeslice_properties_t; 416 417 /////////////////////////////////////////////////////////////////////////////// 418 /// @brief Forward-declare zes_standby_properties_t 419 typedef struct _zes_standby_properties_t zes_standby_properties_t; 420 421 /////////////////////////////////////////////////////////////////////////////// 422 /// @brief Forward-declare zes_temp_properties_t 423 typedef struct _zes_temp_properties_t zes_temp_properties_t; 424 425 /////////////////////////////////////////////////////////////////////////////// 426 /// @brief Forward-declare zes_temp_threshold_t 427 typedef struct _zes_temp_threshold_t zes_temp_threshold_t; 428 429 /////////////////////////////////////////////////////////////////////////////// 430 /// @brief Forward-declare zes_temp_config_t 431 typedef struct _zes_temp_config_t zes_temp_config_t; 432 433 434 #if !defined(__GNUC__) 435 #pragma endregion 436 #endif 437 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Device management 438 #if !defined(__GNUC__) 439 #pragma region device 440 #endif 441 /////////////////////////////////////////////////////////////////////////////// 442 #ifndef ZES_STRING_PROPERTY_SIZE 443 /// @brief Maximum number of characters in string properties. 444 #define ZES_STRING_PROPERTY_SIZE 64 445 #endif // ZES_STRING_PROPERTY_SIZE 446 447 /////////////////////////////////////////////////////////////////////////////// 448 /// @brief Types of accelerator engines 449 typedef uint32_t zes_engine_type_flags_t; 450 typedef enum _zes_engine_type_flag_t 451 { 452 ZES_ENGINE_TYPE_FLAG_OTHER = ZE_BIT(0), ///< Undefined types of accelerators. 453 ZES_ENGINE_TYPE_FLAG_COMPUTE = ZE_BIT(1), ///< Engines that process compute kernels only (no 3D content). 454 ZES_ENGINE_TYPE_FLAG_3D = ZE_BIT(2), ///< Engines that process 3D content only (no compute kernels). 455 ZES_ENGINE_TYPE_FLAG_MEDIA = ZE_BIT(3), ///< Engines that process media workloads. 456 ZES_ENGINE_TYPE_FLAG_DMA = ZE_BIT(4), ///< Engines that copy blocks of data. 457 ZES_ENGINE_TYPE_FLAG_RENDER = ZE_BIT(5), ///< Engines that can process both 3D content and compute kernels. 458 ZES_ENGINE_TYPE_FLAG_FORCE_UINT32 = 0x7fffffff 459 460 } zes_engine_type_flag_t; 461 462 /////////////////////////////////////////////////////////////////////////////// 463 /// @brief Device repair status 464 typedef enum _zes_repair_status_t 465 { 466 ZES_REPAIR_STATUS_UNSUPPORTED = 0, ///< The device does not support in-field repairs. 467 ZES_REPAIR_STATUS_NOT_PERFORMED = 1, ///< The device has never been repaired. 468 ZES_REPAIR_STATUS_PERFORMED = 2, ///< The device has been repaired. 469 ZES_REPAIR_STATUS_FORCE_UINT32 = 0x7fffffff 470 471 } zes_repair_status_t; 472 473 /////////////////////////////////////////////////////////////////////////////// 474 /// @brief Device reset reasons 475 typedef uint32_t zes_reset_reason_flags_t; 476 typedef enum _zes_reset_reason_flag_t 477 { 478 ZES_RESET_REASON_FLAG_WEDGED = ZE_BIT(0), ///< The device needs to be reset because one or more parts of the hardware 479 ///< is wedged 480 ZES_RESET_REASON_FLAG_REPAIR = ZE_BIT(1), ///< The device needs to be reset in order to complete in-field repairs 481 ZES_RESET_REASON_FLAG_FORCE_UINT32 = 0x7fffffff 482 483 } zes_reset_reason_flag_t; 484 485 /////////////////////////////////////////////////////////////////////////////// 486 /// @brief Device state 487 typedef struct _zes_device_state_t 488 { 489 zes_structure_type_t stype; ///< [in] type of this structure 490 const void* pNext; ///< [in][optional] pointer to extension-specific structure 491 zes_reset_reason_flags_t reset; ///< [out] Indicates if the device needs to be reset and for what reasons. 492 ///< returns 0 (none) or combination of ::zes_reset_reason_flag_t 493 zes_repair_status_t repaired; ///< [out] Indicates if the device has been repaired 494 495 } zes_device_state_t; 496 497 /////////////////////////////////////////////////////////////////////////////// 498 /// @brief Device properties 499 typedef struct _zes_device_properties_t 500 { 501 zes_structure_type_t stype; ///< [in] type of this structure 502 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 503 ze_device_properties_t core; ///< [out] Core device properties 504 uint32_t numSubdevices; ///< [out] Number of sub-devices. A value of 0 indicates that this device 505 ///< doesn't have sub-devices. 506 char serialNumber[ZES_STRING_PROPERTY_SIZE]; ///< [out] Manufacturing serial number (NULL terminated string value). Will 507 ///< be set to the string "unkown" if this cannot be determined for the 508 ///< device. 509 char boardNumber[ZES_STRING_PROPERTY_SIZE]; ///< [out] Manufacturing board number (NULL terminated string value). Will 510 ///< be set to the string "unkown" if this cannot be determined for the 511 ///< device. 512 char brandName[ZES_STRING_PROPERTY_SIZE]; ///< [out] Brand name of the device (NULL terminated string value). Will be 513 ///< set to the string "unkown" if this cannot be determined for the 514 ///< device. 515 char modelName[ZES_STRING_PROPERTY_SIZE]; ///< [out] Model name of the device (NULL terminated string value). Will be 516 ///< set to the string "unkown" if this cannot be determined for the 517 ///< device. 518 char vendorName[ZES_STRING_PROPERTY_SIZE]; ///< [out] Vendor name of the device (NULL terminated string value). Will 519 ///< be set to the string "unkown" if this cannot be determined for the 520 ///< device. 521 char driverVersion[ZES_STRING_PROPERTY_SIZE]; ///< [out] Installed driver version (NULL terminated string value). Will be 522 ///< set to the string "unkown" if this cannot be determined for the 523 ///< device. 524 525 } zes_device_properties_t; 526 527 /////////////////////////////////////////////////////////////////////////////// 528 /// @brief Get properties about the device 529 /// 530 /// @details 531 /// - The application may call this function from simultaneous threads. 532 /// - The implementation of this function should be lock-free. 533 /// 534 /// @returns 535 /// - ::ZE_RESULT_SUCCESS 536 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 537 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 538 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 539 /// + `nullptr == hDevice` 540 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 541 /// + `nullptr == pProperties` 542 ZE_APIEXPORT ze_result_t ZE_APICALL 543 zesDeviceGetProperties( 544 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 545 zes_device_properties_t* pProperties ///< [in,out] Structure that will contain information about the device. 546 ); 547 548 /////////////////////////////////////////////////////////////////////////////// 549 /// @brief Get information about the state of the device - if a reset is 550 /// required, reasons for the reset and if the device has been repaired 551 /// 552 /// @details 553 /// - The application may call this function from simultaneous threads. 554 /// - The implementation of this function should be lock-free. 555 /// 556 /// @returns 557 /// - ::ZE_RESULT_SUCCESS 558 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 559 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 560 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 561 /// + `nullptr == hDevice` 562 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 563 /// + `nullptr == pState` 564 ZE_APIEXPORT ze_result_t ZE_APICALL 565 zesDeviceGetState( 566 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 567 zes_device_state_t* pState ///< [in,out] Structure that will contain information about the device. 568 ); 569 570 /////////////////////////////////////////////////////////////////////////////// 571 /// @brief Reset device 572 /// 573 /// @details 574 /// - Performs a PCI bus reset of the device. This will result in all 575 /// current device state being lost. 576 /// - All applications using the device should be stopped before calling 577 /// this function. 578 /// - If the force argument is specified, all applications using the device 579 /// will be forcibly killed. 580 /// - The function will block until the device has restarted or a timeout 581 /// occurred waiting for the reset to complete. 582 /// 583 /// @returns 584 /// - ::ZE_RESULT_SUCCESS 585 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 586 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 587 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 588 /// + `nullptr == hDevice` 589 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 590 /// + User does not have permissions to perform this operation. 591 /// - ::ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE - "Reset cannot be performed because applications are using this device." 592 /// - ::ZE_RESULT_ERROR_UNKNOWN - "There were problems unloading the device driver, performing a bus reset or reloading the device driver." 593 ZE_APIEXPORT ze_result_t ZE_APICALL 594 zesDeviceReset( 595 zes_device_handle_t hDevice, ///< [in] Sysman handle for the device 596 ze_bool_t force ///< [in] If set to true, all applications that are currently using the 597 ///< device will be forcibly killed. 598 ); 599 600 /////////////////////////////////////////////////////////////////////////////// 601 /// @brief Contains information about a process that has an open connection with 602 /// this device 603 /// 604 /// @details 605 /// - The application can use the process ID to query the OS for the owner 606 /// and the path to the executable. 607 typedef struct _zes_process_state_t 608 { 609 zes_structure_type_t stype; ///< [in] type of this structure 610 const void* pNext; ///< [in][optional] pointer to extension-specific structure 611 uint32_t processId; ///< [out] Host OS process ID. 612 uint64_t memSize; ///< [out] Device memory size in bytes allocated by this process (may not 613 ///< necessarily be resident on the device at the time of reading). 614 uint64_t sharedSize; ///< [out] The size of shared device memory mapped into this process (may 615 ///< not necessarily be resident on the device at the time of reading). 616 zes_engine_type_flags_t engines; ///< [out] Bitfield of accelerator engine types being used by this process. 617 618 } zes_process_state_t; 619 620 /////////////////////////////////////////////////////////////////////////////// 621 /// @brief Get information about host processes using the device 622 /// 623 /// @details 624 /// - The number of processes connected to the device is dynamic. This means 625 /// that between a call to determine the value of pCount and the 626 /// subsequent call, the number of processes may have increased or 627 /// decreased. It is recommended that a large array be passed in so as to 628 /// avoid receiving the error ::ZE_RESULT_ERROR_INVALID_SIZE. Also, always 629 /// check the returned value in pCount since it may be less than the 630 /// earlier call to get the required array size. 631 /// - The application may call this function from simultaneous threads. 632 /// - The implementation of this function should be lock-free. 633 /// 634 /// @returns 635 /// - ::ZE_RESULT_SUCCESS 636 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 637 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 638 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 639 /// + `nullptr == hDevice` 640 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 641 /// + `nullptr == pCount` 642 /// - ::ZE_RESULT_ERROR_INVALID_SIZE 643 /// + The provided value of pCount is not big enough to store information about all the processes currently attached to the device. 644 ZE_APIEXPORT ze_result_t ZE_APICALL 645 zesDeviceProcessesGetState( 646 zes_device_handle_t hDevice, ///< [in] Sysman handle for the device 647 uint32_t* pCount, ///< [in,out] pointer to the number of processes. 648 ///< if count is zero, then the driver shall update the value with the 649 ///< total number of processes currently attached to the device. 650 ///< if count is greater than the number of processes currently attached to 651 ///< the device, then the driver shall update the value with the correct 652 ///< number of processes. 653 zes_process_state_t* pProcesses ///< [in,out][optional][range(0, *pCount)] array of process information. 654 ///< if count is less than the number of processes currently attached to 655 ///< the device, then the driver shall only retrieve information about that 656 ///< number of processes. In this case, the return code will ::ZE_RESULT_ERROR_INVALID_SIZE. 657 ); 658 659 /////////////////////////////////////////////////////////////////////////////// 660 /// @brief PCI address 661 typedef struct _zes_pci_address_t 662 { 663 uint32_t domain; ///< [out] BDF domain 664 uint32_t bus; ///< [out] BDF bus 665 uint32_t device; ///< [out] BDF device 666 uint32_t function; ///< [out] BDF function 667 668 } zes_pci_address_t; 669 670 /////////////////////////////////////////////////////////////////////////////// 671 /// @brief PCI speed 672 typedef struct _zes_pci_speed_t 673 { 674 int32_t gen; ///< [out] The link generation. A value of -1 means that this property is 675 ///< unknown. 676 int32_t width; ///< [out] The number of lanes. A value of -1 means that this property is 677 ///< unknown. 678 int64_t maxBandwidth; ///< [out] The maximum bandwidth in bytes/sec (sum of all lanes). A value 679 ///< of -1 means that this property is unknown. 680 681 } zes_pci_speed_t; 682 683 /////////////////////////////////////////////////////////////////////////////// 684 /// @brief Static PCI properties 685 typedef struct _zes_pci_properties_t 686 { 687 zes_structure_type_t stype; ///< [in] type of this structure 688 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 689 zes_pci_address_t address; ///< [out] The BDF address 690 zes_pci_speed_t maxSpeed; ///< [out] Fastest port configuration supported by the device (sum of all 691 ///< lanes) 692 ze_bool_t haveBandwidthCounters; ///< [out] Indicates if ::zes_pci_stats_t.rxCounter and 693 ///< ::zes_pci_stats_t.txCounter will have valid values 694 ze_bool_t havePacketCounters; ///< [out] Indicates if ::zes_pci_stats_t.packetCounter will have valid 695 ///< values 696 ze_bool_t haveReplayCounters; ///< [out] Indicates if ::zes_pci_stats_t.replayCounter will have valid 697 ///< values 698 699 } zes_pci_properties_t; 700 701 /////////////////////////////////////////////////////////////////////////////// 702 /// @brief PCI link status 703 typedef enum _zes_pci_link_status_t 704 { 705 ZES_PCI_LINK_STATUS_UNKNOWN = 0, ///< The link status could not be determined 706 ZES_PCI_LINK_STATUS_GOOD = 1, ///< The link is up and operating as expected 707 ZES_PCI_LINK_STATUS_QUALITY_ISSUES = 2, ///< The link is up but has quality and/or bandwidth degradation 708 ZES_PCI_LINK_STATUS_STABILITY_ISSUES = 3, ///< The link has stability issues and preventing workloads making forward 709 ///< progress 710 ZES_PCI_LINK_STATUS_FORCE_UINT32 = 0x7fffffff 711 712 } zes_pci_link_status_t; 713 714 /////////////////////////////////////////////////////////////////////////////// 715 /// @brief PCI link quality degradation reasons 716 typedef uint32_t zes_pci_link_qual_issue_flags_t; 717 typedef enum _zes_pci_link_qual_issue_flag_t 718 { 719 ZES_PCI_LINK_QUAL_ISSUE_FLAG_REPLAYS = ZE_BIT(0), ///< A significant number of replays are occurring 720 ZES_PCI_LINK_QUAL_ISSUE_FLAG_SPEED = ZE_BIT(1), ///< There is a degradation in the maximum bandwidth of the link 721 ZES_PCI_LINK_QUAL_ISSUE_FLAG_FORCE_UINT32 = 0x7fffffff 722 723 } zes_pci_link_qual_issue_flag_t; 724 725 /////////////////////////////////////////////////////////////////////////////// 726 /// @brief PCI link stability issues 727 typedef uint32_t zes_pci_link_stab_issue_flags_t; 728 typedef enum _zes_pci_link_stab_issue_flag_t 729 { 730 ZES_PCI_LINK_STAB_ISSUE_FLAG_RETRAINING = ZE_BIT(0),///< Link retraining has occurred to deal with quality issues 731 ZES_PCI_LINK_STAB_ISSUE_FLAG_FORCE_UINT32 = 0x7fffffff 732 733 } zes_pci_link_stab_issue_flag_t; 734 735 /////////////////////////////////////////////////////////////////////////////// 736 /// @brief Dynamic PCI state 737 typedef struct _zes_pci_state_t 738 { 739 zes_structure_type_t stype; ///< [in] type of this structure 740 const void* pNext; ///< [in][optional] pointer to extension-specific structure 741 zes_pci_link_status_t status; ///< [out] The current status of the port 742 zes_pci_link_qual_issue_flags_t qualityIssues; ///< [out] If status is ::ZES_PCI_LINK_STATUS_QUALITY_ISSUES, 743 ///< then this gives a combination of ::zes_pci_link_qual_issue_flag_t for 744 ///< quality issues that have been detected; 745 ///< otherwise, 0 indicates there are no quality issues with the link at 746 ///< this time." 747 zes_pci_link_stab_issue_flags_t stabilityIssues;///< [out] If status is ::ZES_PCI_LINK_STATUS_STABILITY_ISSUES, 748 ///< then this gives a combination of ::zes_pci_link_stab_issue_flag_t for 749 ///< reasons for the connection instability; 750 ///< otherwise, 0 indicates there are no connection stability issues at 751 ///< this time." 752 zes_pci_speed_t speed; ///< [out] The current port configure speed 753 754 } zes_pci_state_t; 755 756 /////////////////////////////////////////////////////////////////////////////// 757 /// @brief PCI bar types 758 typedef enum _zes_pci_bar_type_t 759 { 760 ZES_PCI_BAR_TYPE_MMIO = 0, ///< MMIO registers 761 ZES_PCI_BAR_TYPE_ROM = 1, ///< ROM aperture 762 ZES_PCI_BAR_TYPE_MEM = 2, ///< Device memory 763 ZES_PCI_BAR_TYPE_FORCE_UINT32 = 0x7fffffff 764 765 } zes_pci_bar_type_t; 766 767 /////////////////////////////////////////////////////////////////////////////// 768 /// @brief Properties of a pci bar 769 typedef struct _zes_pci_bar_properties_t 770 { 771 zes_structure_type_t stype; ///< [in] type of this structure 772 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 773 zes_pci_bar_type_t type; ///< [out] The type of bar 774 uint32_t index; ///< [out] The index of the bar 775 uint64_t base; ///< [out] Base address of the bar. 776 uint64_t size; ///< [out] Size of the bar. 777 778 } zes_pci_bar_properties_t; 779 780 /////////////////////////////////////////////////////////////////////////////// 781 /// @brief Properties of a pci bar, including the resizable bar. 782 typedef struct _zes_pci_bar_properties_1_2_t 783 { 784 zes_structure_type_t stype; ///< [in] type of this structure 785 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 786 zes_pci_bar_type_t type; ///< [out] The type of bar 787 uint32_t index; ///< [out] The index of the bar 788 uint64_t base; ///< [out] Base address of the bar. 789 uint64_t size; ///< [out] Size of the bar. 790 ze_bool_t resizableBarSupported; ///< [out] Support for Resizable Bar on this device. 791 ze_bool_t resizableBarEnabled; ///< [out] Resizable Bar enabled on this device 792 793 } zes_pci_bar_properties_1_2_t; 794 795 /////////////////////////////////////////////////////////////////////////////// 796 /// @brief PCI stats counters 797 /// 798 /// @details 799 /// - Percent replays is calculated by taking two snapshots (s1, s2) and 800 /// using the equation: %replay = 10^6 * (s2.replayCounter - 801 /// s1.replayCounter) / (s2.maxBandwidth * (s2.timestamp - s1.timestamp)) 802 /// - Percent throughput is calculated by taking two snapshots (s1, s2) and 803 /// using the equation: %bw = 10^6 * ((s2.rxCounter - s1.rxCounter) + 804 /// (s2.txCounter - s1.txCounter)) / (s2.maxBandwidth * (s2.timestamp - 805 /// s1.timestamp)) 806 typedef struct _zes_pci_stats_t 807 { 808 uint64_t timestamp; ///< [out] Monotonic timestamp counter in microseconds when the measurement 809 ///< was made. 810 ///< This timestamp should only be used to calculate delta time between 811 ///< snapshots of this structure. 812 ///< Never take the delta of this timestamp with the timestamp from a 813 ///< different structure since they are not guaranteed to have the same base. 814 ///< The absolute value of the timestamp is only valid during within the 815 ///< application and may be different on the next execution. 816 uint64_t replayCounter; ///< [out] Monotonic counter for the number of replay packets (sum of all 817 ///< lanes). Will always be 0 if ::zes_pci_properties_t.haveReplayCounters 818 ///< is FALSE. 819 uint64_t packetCounter; ///< [out] Monotonic counter for the number of packets (sum of all lanes). 820 ///< Will always be 0 if ::zes_pci_properties_t.havePacketCounters is 821 ///< FALSE. 822 uint64_t rxCounter; ///< [out] Monotonic counter for the number of bytes received (sum of all 823 ///< lanes). Will always be 0 if 824 ///< ::zes_pci_properties_t.haveBandwidthCounters is FALSE. 825 uint64_t txCounter; ///< [out] Monotonic counter for the number of bytes transmitted (including 826 ///< replays) (sum of all lanes). Will always be 0 if 827 ///< ::zes_pci_properties_t.haveBandwidthCounters is FALSE. 828 zes_pci_speed_t speed; ///< [out] The current speed of the link (sum of all lanes) 829 830 } zes_pci_stats_t; 831 832 /////////////////////////////////////////////////////////////////////////////// 833 /// @brief Get PCI properties - address, max speed 834 /// 835 /// @details 836 /// - The application may call this function from simultaneous threads. 837 /// - The implementation of this function should be lock-free. 838 /// 839 /// @returns 840 /// - ::ZE_RESULT_SUCCESS 841 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 842 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 843 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 844 /// + `nullptr == hDevice` 845 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 846 /// + `nullptr == pProperties` 847 ZE_APIEXPORT ze_result_t ZE_APICALL 848 zesDevicePciGetProperties( 849 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 850 zes_pci_properties_t* pProperties ///< [in,out] Will contain the PCI properties. 851 ); 852 853 /////////////////////////////////////////////////////////////////////////////// 854 /// @brief Get current PCI state - current speed 855 /// 856 /// @details 857 /// - The application may call this function from simultaneous threads. 858 /// - The implementation of this function should be lock-free. 859 /// 860 /// @returns 861 /// - ::ZE_RESULT_SUCCESS 862 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 863 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 864 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 865 /// + `nullptr == hDevice` 866 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 867 /// + `nullptr == pState` 868 ZE_APIEXPORT ze_result_t ZE_APICALL 869 zesDevicePciGetState( 870 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 871 zes_pci_state_t* pState ///< [in,out] Will contain the PCI properties. 872 ); 873 874 /////////////////////////////////////////////////////////////////////////////// 875 /// @brief Get information about each configured bar 876 /// 877 /// @details 878 /// - The application may call this function from simultaneous threads. 879 /// - The implementation of this function should be lock-free. 880 /// 881 /// @returns 882 /// - ::ZE_RESULT_SUCCESS 883 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 884 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 885 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 886 /// + `nullptr == hDevice` 887 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 888 /// + `nullptr == pCount` 889 ZE_APIEXPORT ze_result_t ZE_APICALL 890 zesDevicePciGetBars( 891 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 892 uint32_t* pCount, ///< [in,out] pointer to the number of PCI bars. 893 ///< if count is zero, then the driver shall update the value with the 894 ///< total number of PCI bars that are setup. 895 ///< if count is greater than the number of PCI bars that are setup, then 896 ///< the driver shall update the value with the correct number of PCI bars. 897 zes_pci_bar_properties_t* pProperties ///< [in,out][optional][range(0, *pCount)] array of information about setup 898 ///< PCI bars. 899 ///< if count is less than the number of PCI bars that are setup, then the 900 ///< driver shall only retrieve information about that number of PCI bars. 901 ); 902 903 /////////////////////////////////////////////////////////////////////////////// 904 /// @brief Get PCI stats - bandwidth, number of packets, number of replays 905 /// 906 /// @details 907 /// - The application may call this function from simultaneous threads. 908 /// - The implementation of this function should be lock-free. 909 /// 910 /// @returns 911 /// - ::ZE_RESULT_SUCCESS 912 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 913 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 914 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 915 /// + `nullptr == hDevice` 916 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 917 /// + `nullptr == pStats` 918 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 919 /// + User does not have permissions to query this telemetry. 920 ZE_APIEXPORT ze_result_t ZE_APICALL 921 zesDevicePciGetStats( 922 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 923 zes_pci_stats_t* pStats ///< [in,out] Will contain a snapshot of the latest stats. 924 ); 925 926 #if !defined(__GNUC__) 927 #pragma endregion 928 #endif 929 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Firmware management 930 #if !defined(__GNUC__) 931 #pragma region diagnostics 932 #endif 933 /////////////////////////////////////////////////////////////////////////////// 934 /// @brief Diagnostic results 935 typedef enum _zes_diag_result_t 936 { 937 ZES_DIAG_RESULT_NO_ERRORS = 0, ///< Diagnostic completed without finding errors to repair 938 ZES_DIAG_RESULT_ABORT = 1, ///< Diagnostic had problems running tests 939 ZES_DIAG_RESULT_FAIL_CANT_REPAIR = 2, ///< Diagnostic had problems setting up repairs 940 ZES_DIAG_RESULT_REBOOT_FOR_REPAIR = 3, ///< Diagnostics found errors, setup for repair and reboot is required to 941 ///< complete the process 942 ZES_DIAG_RESULT_FORCE_UINT32 = 0x7fffffff 943 944 } zes_diag_result_t; 945 946 /////////////////////////////////////////////////////////////////////////////// 947 #ifndef ZES_DIAG_FIRST_TEST_INDEX 948 /// @brief Diagnostic test index to use for the very first test. 949 #define ZES_DIAG_FIRST_TEST_INDEX 0x0 950 #endif // ZES_DIAG_FIRST_TEST_INDEX 951 952 /////////////////////////////////////////////////////////////////////////////// 953 #ifndef ZES_DIAG_LAST_TEST_INDEX 954 /// @brief Diagnostic test index to use for the very last test. 955 #define ZES_DIAG_LAST_TEST_INDEX 0xFFFFFFFF 956 #endif // ZES_DIAG_LAST_TEST_INDEX 957 958 /////////////////////////////////////////////////////////////////////////////// 959 /// @brief Diagnostic test 960 typedef struct _zes_diag_test_t 961 { 962 uint32_t index; ///< [out] Index of the test 963 char name[ZES_STRING_PROPERTY_SIZE]; ///< [out] Name of the test 964 965 } zes_diag_test_t; 966 967 /////////////////////////////////////////////////////////////////////////////// 968 /// @brief Diagnostics test suite properties 969 typedef struct _zes_diag_properties_t 970 { 971 zes_structure_type_t stype; ///< [in] type of this structure 972 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 973 ze_bool_t onSubdevice; ///< [out] True if the resource is located on a sub-device; false means 974 ///< that the resource is on the device of the calling Sysman handle 975 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 976 char name[ZES_STRING_PROPERTY_SIZE]; ///< [out] Name of the diagnostics test suite 977 ze_bool_t haveTests; ///< [out] Indicates if this test suite has individual tests which can be 978 ///< run separately (use the function ::zesDiagnosticsGetTests() to get the 979 ///< list of these tests) 980 981 } zes_diag_properties_t; 982 983 /////////////////////////////////////////////////////////////////////////////// 984 /// @brief Get handle of diagnostics test suites 985 /// 986 /// @details 987 /// - The application may call this function from simultaneous threads. 988 /// - The implementation of this function should be lock-free. 989 /// 990 /// @returns 991 /// - ::ZE_RESULT_SUCCESS 992 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 993 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 994 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 995 /// + `nullptr == hDevice` 996 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 997 /// + `nullptr == pCount` 998 ZE_APIEXPORT ze_result_t ZE_APICALL 999 zesDeviceEnumDiagnosticTestSuites( 1000 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 1001 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 1002 ///< if count is zero, then the driver shall update the value with the 1003 ///< total number of components of this type that are available. 1004 ///< if count is greater than the number of components of this type that 1005 ///< are available, then the driver shall update the value with the correct 1006 ///< number of components. 1007 zes_diag_handle_t* phDiagnostics ///< [in,out][optional][range(0, *pCount)] array of handle of components of 1008 ///< this type. 1009 ///< if count is less than the number of components of this type that are 1010 ///< available, then the driver shall only retrieve that number of 1011 ///< component handles. 1012 ); 1013 1014 /////////////////////////////////////////////////////////////////////////////// 1015 /// @brief Get properties of a diagnostics test suite 1016 /// 1017 /// @details 1018 /// - The application may call this function from simultaneous threads. 1019 /// - The implementation of this function should be lock-free. 1020 /// 1021 /// @returns 1022 /// - ::ZE_RESULT_SUCCESS 1023 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1024 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1025 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1026 /// + `nullptr == hDiagnostics` 1027 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1028 /// + `nullptr == pProperties` 1029 ZE_APIEXPORT ze_result_t ZE_APICALL 1030 zesDiagnosticsGetProperties( 1031 zes_diag_handle_t hDiagnostics, ///< [in] Handle for the component. 1032 zes_diag_properties_t* pProperties ///< [in,out] Structure describing the properties of a diagnostics test 1033 ///< suite 1034 ); 1035 1036 /////////////////////////////////////////////////////////////////////////////// 1037 /// @brief Get individual tests that can be run separately. Not all test suites 1038 /// permit running individual tests - check 1039 /// ::zes_diag_properties_t.haveTests 1040 /// 1041 /// @details 1042 /// - The list of available tests is returned in order of increasing test 1043 /// index ::zes_diag_test_t.index. 1044 /// - The application may call this function from simultaneous threads. 1045 /// - The implementation of this function should be lock-free. 1046 /// 1047 /// @returns 1048 /// - ::ZE_RESULT_SUCCESS 1049 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1050 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1051 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1052 /// + `nullptr == hDiagnostics` 1053 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1054 /// + `nullptr == pCount` 1055 ZE_APIEXPORT ze_result_t ZE_APICALL 1056 zesDiagnosticsGetTests( 1057 zes_diag_handle_t hDiagnostics, ///< [in] Handle for the component. 1058 uint32_t* pCount, ///< [in,out] pointer to the number of tests. 1059 ///< if count is zero, then the driver shall update the value with the 1060 ///< total number of tests that are available. 1061 ///< if count is greater than the number of tests that are available, then 1062 ///< the driver shall update the value with the correct number of tests. 1063 zes_diag_test_t* pTests ///< [in,out][optional][range(0, *pCount)] array of information about 1064 ///< individual tests sorted by increasing value of ::zes_diag_test_t.index. 1065 ///< if count is less than the number of tests that are available, then the 1066 ///< driver shall only retrieve that number of tests. 1067 ); 1068 1069 /////////////////////////////////////////////////////////////////////////////// 1070 /// @brief Run a diagnostics test suite, either all tests or a subset of tests. 1071 /// 1072 /// @details 1073 /// - WARNING: Running diagnostics may destroy current device state 1074 /// information. Gracefully close any running workloads before initiating. 1075 /// - To run all tests in a test suite, set start = 1076 /// ::ZES_DIAG_FIRST_TEST_INDEX and end = ::ZES_DIAG_LAST_TEST_INDEX. 1077 /// - If the test suite permits running individual tests, 1078 /// ::zes_diag_properties_t.haveTests will be true. In this case, the 1079 /// function ::zesDiagnosticsGetTests() can be called to get the list of 1080 /// tests and corresponding indices that can be supplied to the arguments 1081 /// start and end in this function. 1082 /// - This function will block until the diagnostics have completed and 1083 /// force reset based on result 1084 /// 1085 /// @returns 1086 /// - ::ZE_RESULT_SUCCESS 1087 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1088 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1089 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1090 /// + `nullptr == hDiagnostics` 1091 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1092 /// + `nullptr == pResult` 1093 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 1094 /// + User does not have permissions to perform diagnostics. 1095 ZE_APIEXPORT ze_result_t ZE_APICALL 1096 zesDiagnosticsRunTests( 1097 zes_diag_handle_t hDiagnostics, ///< [in] Handle for the component. 1098 uint32_t startIndex, ///< [in] The index of the first test to run. Set to 1099 ///< ::ZES_DIAG_FIRST_TEST_INDEX to start from the beginning. 1100 uint32_t endIndex, ///< [in] The index of the last test to run. Set to 1101 ///< ::ZES_DIAG_LAST_TEST_INDEX to complete all tests after the start test. 1102 zes_diag_result_t* pResult ///< [in,out] The result of the diagnostics 1103 ); 1104 1105 #if !defined(__GNUC__) 1106 #pragma endregion 1107 #endif 1108 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Engine groups 1109 #if !defined(__GNUC__) 1110 #pragma region engine 1111 #endif 1112 /////////////////////////////////////////////////////////////////////////////// 1113 /// @brief Accelerator engine groups 1114 typedef enum _zes_engine_group_t 1115 { 1116 ZES_ENGINE_GROUP_ALL = 0, ///< Access information about all engines combined. 1117 ZES_ENGINE_GROUP_COMPUTE_ALL = 1, ///< Access information about all compute engines combined. Compute engines 1118 ///< can only process compute kernels (no 3D content). 1119 ZES_ENGINE_GROUP_MEDIA_ALL = 2, ///< Access information about all media engines combined. 1120 ZES_ENGINE_GROUP_COPY_ALL = 3, ///< Access information about all copy (blitter) engines combined. 1121 ZES_ENGINE_GROUP_COMPUTE_SINGLE = 4, ///< Access information about a single compute engine - this is an engine 1122 ///< that can process compute kernels. Note that single engines may share 1123 ///< the same underlying accelerator resources as other engines so activity 1124 ///< of such an engine may not be indicative of the underlying resource 1125 ///< utilization - use ::ZES_ENGINE_GROUP_3D_RENDER_COMPUTE_ALL for that. 1126 ZES_ENGINE_GROUP_RENDER_SINGLE = 5, ///< Access information about a single render engine - this is an engine 1127 ///< that can process both 3D content and compute kernels. Note that single 1128 ///< engines may share the same underlying accelerator resources as other 1129 ///< engines so activity of such an engine may not be indicative of the 1130 ///< underlying resource utilization - use 1131 ///< ::ZES_ENGINE_GROUP_3D_RENDER_COMPUTE_ALL for that. 1132 ZES_ENGINE_GROUP_MEDIA_DECODE_SINGLE = 6, ///< Access information about a single media decode engine. Note that 1133 ///< single engines may share the same underlying accelerator resources as 1134 ///< other engines so activity of such an engine may not be indicative of 1135 ///< the underlying resource utilization - use ::ZES_ENGINE_GROUP_MEDIA_ALL 1136 ///< for that. 1137 ZES_ENGINE_GROUP_MEDIA_ENCODE_SINGLE = 7, ///< Access information about a single media encode engine. Note that 1138 ///< single engines may share the same underlying accelerator resources as 1139 ///< other engines so activity of such an engine may not be indicative of 1140 ///< the underlying resource utilization - use ::ZES_ENGINE_GROUP_MEDIA_ALL 1141 ///< for that. 1142 ZES_ENGINE_GROUP_COPY_SINGLE = 8, ///< Access information about a single media encode engine. Note that 1143 ///< single engines may share the same underlying accelerator resources as 1144 ///< other engines so activity of such an engine may not be indicative of 1145 ///< the underlying resource utilization - use ::ZES_ENGINE_GROUP_COPY_ALL 1146 ///< for that. 1147 ZES_ENGINE_GROUP_MEDIA_ENHANCEMENT_SINGLE = 9, ///< Access information about a single media enhancement engine. Note that 1148 ///< single engines may share the same underlying accelerator resources as 1149 ///< other engines so activity of such an engine may not be indicative of 1150 ///< the underlying resource utilization - use ::ZES_ENGINE_GROUP_MEDIA_ALL 1151 ///< for that. 1152 ZES_ENGINE_GROUP_3D_SINGLE = 10, ///< Access information about a single 3D engine - this is an engine that 1153 ///< can process 3D content only. Note that single engines may share the 1154 ///< same underlying accelerator resources as other engines so activity of 1155 ///< such an engine may not be indicative of the underlying resource 1156 ///< utilization - use ::ZES_ENGINE_GROUP_3D_RENDER_COMPUTE_ALL for that. 1157 ZES_ENGINE_GROUP_3D_RENDER_COMPUTE_ALL = 11, ///< Access information about all 3D/render/compute engines combined. 1158 ZES_ENGINE_GROUP_RENDER_ALL = 12, ///< Access information about all render engines combined. Render engines 1159 ///< are those than process both 3D content and compute kernels. 1160 ZES_ENGINE_GROUP_3D_ALL = 13, ///< Access information about all 3D engines combined. 3D engines can 1161 ///< process 3D content only (no compute kernels). 1162 ZES_ENGINE_GROUP_FORCE_UINT32 = 0x7fffffff 1163 1164 } zes_engine_group_t; 1165 1166 /////////////////////////////////////////////////////////////////////////////// 1167 /// @brief Engine group properties 1168 typedef struct _zes_engine_properties_t 1169 { 1170 zes_structure_type_t stype; ///< [in] type of this structure 1171 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 1172 zes_engine_group_t type; ///< [out] The engine group 1173 ze_bool_t onSubdevice; ///< [out] True if this resource is located on a sub-device; false means 1174 ///< that the resource is on the device of the calling Sysman handle 1175 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 1176 1177 } zes_engine_properties_t; 1178 1179 /////////////////////////////////////////////////////////////////////////////// 1180 /// @brief Engine activity counters 1181 /// 1182 /// @details 1183 /// - Percent utilization is calculated by taking two snapshots (s1, s2) and 1184 /// using the equation: %util = (s2.activeTime - s1.activeTime) / 1185 /// (s2.timestamp - s1.timestamp) 1186 typedef struct _zes_engine_stats_t 1187 { 1188 uint64_t activeTime; ///< [out] Monotonic counter for time in microseconds that this resource is 1189 ///< actively running workloads. 1190 uint64_t timestamp; ///< [out] Monotonic timestamp counter in microseconds when activeTime 1191 ///< counter was sampled. 1192 ///< This timestamp should only be used to calculate delta time between 1193 ///< snapshots of this structure. 1194 ///< Never take the delta of this timestamp with the timestamp from a 1195 ///< different structure since they are not guaranteed to have the same base. 1196 ///< The absolute value of the timestamp is only valid during within the 1197 ///< application and may be different on the next execution. 1198 1199 } zes_engine_stats_t; 1200 1201 /////////////////////////////////////////////////////////////////////////////// 1202 /// @brief Get handle of engine groups 1203 /// 1204 /// @details 1205 /// - The application may call this function from simultaneous threads. 1206 /// - The implementation of this function should be lock-free. 1207 /// 1208 /// @returns 1209 /// - ::ZE_RESULT_SUCCESS 1210 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1211 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1212 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1213 /// + `nullptr == hDevice` 1214 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1215 /// + `nullptr == pCount` 1216 ZE_APIEXPORT ze_result_t ZE_APICALL 1217 zesDeviceEnumEngineGroups( 1218 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 1219 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 1220 ///< if count is zero, then the driver shall update the value with the 1221 ///< total number of components of this type that are available. 1222 ///< if count is greater than the number of components of this type that 1223 ///< are available, then the driver shall update the value with the correct 1224 ///< number of components. 1225 zes_engine_handle_t* phEngine ///< [in,out][optional][range(0, *pCount)] array of handle of components of 1226 ///< this type. 1227 ///< if count is less than the number of components of this type that are 1228 ///< available, then the driver shall only retrieve that number of 1229 ///< component handles. 1230 ); 1231 1232 /////////////////////////////////////////////////////////////////////////////// 1233 /// @brief Get engine group properties 1234 /// 1235 /// @details 1236 /// - The application may call this function from simultaneous threads. 1237 /// - The implementation of this function should be lock-free. 1238 /// 1239 /// @returns 1240 /// - ::ZE_RESULT_SUCCESS 1241 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1242 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1243 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1244 /// + `nullptr == hEngine` 1245 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1246 /// + `nullptr == pProperties` 1247 ZE_APIEXPORT ze_result_t ZE_APICALL 1248 zesEngineGetProperties( 1249 zes_engine_handle_t hEngine, ///< [in] Handle for the component. 1250 zes_engine_properties_t* pProperties ///< [in,out] The properties for the specified engine group. 1251 ); 1252 1253 /////////////////////////////////////////////////////////////////////////////// 1254 /// @brief Get the activity stats for an engine group 1255 /// 1256 /// @details 1257 /// - The application may call this function from simultaneous threads. 1258 /// - The implementation of this function should be lock-free. 1259 /// 1260 /// @returns 1261 /// - ::ZE_RESULT_SUCCESS 1262 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1263 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1264 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1265 /// + `nullptr == hEngine` 1266 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1267 /// + `nullptr == pStats` 1268 ZE_APIEXPORT ze_result_t ZE_APICALL 1269 zesEngineGetActivity( 1270 zes_engine_handle_t hEngine, ///< [in] Handle for the component. 1271 zes_engine_stats_t* pStats ///< [in,out] Will contain a snapshot of the engine group activity 1272 ///< counters. 1273 ); 1274 1275 #if !defined(__GNUC__) 1276 #pragma endregion 1277 #endif 1278 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Event management 1279 #if !defined(__GNUC__) 1280 #pragma region events 1281 #endif 1282 /////////////////////////////////////////////////////////////////////////////// 1283 /// @brief Event types 1284 typedef uint32_t zes_event_type_flags_t; 1285 typedef enum _zes_event_type_flag_t 1286 { 1287 ZES_EVENT_TYPE_FLAG_DEVICE_DETACH = ZE_BIT(0), ///< Event is triggered when the device is no longer available (due to a 1288 ///< reset or being disabled). 1289 ZES_EVENT_TYPE_FLAG_DEVICE_ATTACH = ZE_BIT(1), ///< Event is triggered after the device is available again. 1290 ZES_EVENT_TYPE_FLAG_DEVICE_SLEEP_STATE_ENTER = ZE_BIT(2), ///< Event is triggered when the driver is about to put the device into a 1291 ///< deep sleep state 1292 ZES_EVENT_TYPE_FLAG_DEVICE_SLEEP_STATE_EXIT = ZE_BIT(3),///< Event is triggered when the driver is waking the device up from a deep 1293 ///< sleep state 1294 ZES_EVENT_TYPE_FLAG_FREQ_THROTTLED = ZE_BIT(4), ///< Event is triggered when the frequency starts being throttled 1295 ZES_EVENT_TYPE_FLAG_ENERGY_THRESHOLD_CROSSED = ZE_BIT(5), ///< Event is triggered when the energy consumption threshold is reached 1296 ///< (use ::zesPowerSetEnergyThreshold() to configure). 1297 ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL = ZE_BIT(6), ///< Event is triggered when the critical temperature is reached (use 1298 ///< ::zesTemperatureSetConfig() to configure - disabled by default). 1299 ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1 = ZE_BIT(7),///< Event is triggered when the temperature crosses threshold 1 (use 1300 ///< ::zesTemperatureSetConfig() to configure - disabled by default). 1301 ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2 = ZE_BIT(8),///< Event is triggered when the temperature crosses threshold 2 (use 1302 ///< ::zesTemperatureSetConfig() to configure - disabled by default). 1303 ZES_EVENT_TYPE_FLAG_MEM_HEALTH = ZE_BIT(9), ///< Event is triggered when the health of device memory changes. 1304 ZES_EVENT_TYPE_FLAG_FABRIC_PORT_HEALTH = ZE_BIT(10),///< Event is triggered when the health of fabric ports change. 1305 ZES_EVENT_TYPE_FLAG_PCI_LINK_HEALTH = ZE_BIT(11), ///< Event is triggered when the health of the PCI link changes. 1306 ZES_EVENT_TYPE_FLAG_RAS_CORRECTABLE_ERRORS = ZE_BIT(12),///< Event is triggered when accelerator RAS correctable errors cross 1307 ///< thresholds (use ::zesRasSetConfig() to configure - disabled by 1308 ///< default). 1309 ZES_EVENT_TYPE_FLAG_RAS_UNCORRECTABLE_ERRORS = ZE_BIT(13), ///< Event is triggered when accelerator RAS uncorrectable errors cross 1310 ///< thresholds (use ::zesRasSetConfig() to configure - disabled by 1311 ///< default). 1312 ZES_EVENT_TYPE_FLAG_DEVICE_RESET_REQUIRED = ZE_BIT(14), ///< Event is triggered when the device needs to be reset (use 1313 ///< ::zesDeviceGetState() to determine the reasons for the reset). 1314 ZES_EVENT_TYPE_FLAG_FORCE_UINT32 = 0x7fffffff 1315 1316 } zes_event_type_flag_t; 1317 1318 /////////////////////////////////////////////////////////////////////////////// 1319 /// @brief Specify the list of events to listen to for a given device 1320 /// 1321 /// @details 1322 /// - The application may call this function from simultaneous threads. 1323 /// - The implementation of this function should be lock-free. 1324 /// 1325 /// @returns 1326 /// - ::ZE_RESULT_SUCCESS 1327 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1328 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1329 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1330 /// + `nullptr == hDevice` 1331 /// - ::ZE_RESULT_ERROR_INVALID_ENUMERATION 1332 /// + `0x7fff < events` 1333 ZE_APIEXPORT ze_result_t ZE_APICALL 1334 zesDeviceEventRegister( 1335 zes_device_handle_t hDevice, ///< [in] The device handle. 1336 zes_event_type_flags_t events ///< [in] List of events to listen to. 1337 ); 1338 1339 /////////////////////////////////////////////////////////////////////////////// 1340 /// @brief Wait for events to be received from a one or more devices. 1341 /// 1342 /// @details 1343 /// - The application may call this function from simultaneous threads. 1344 /// - The implementation of this function should be lock-free. 1345 /// 1346 /// @returns 1347 /// - ::ZE_RESULT_SUCCESS 1348 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1349 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1350 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1351 /// + `nullptr == hDriver` 1352 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1353 /// + `nullptr == phDevices` 1354 /// + `nullptr == pNumDeviceEvents` 1355 /// + `nullptr == pEvents` 1356 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 1357 /// + User does not have permissions to listen to events. 1358 /// - ::ZE_RESULT_ERROR_INVALID_ARGUMENT 1359 /// + One or more of the supplied device handles belongs to a different driver. 1360 ZE_APIEXPORT ze_result_t ZE_APICALL 1361 zesDriverEventListen( 1362 ze_driver_handle_t hDriver, ///< [in] handle of the driver instance 1363 uint32_t timeout, ///< [in] if non-zero, then indicates the maximum time (in milliseconds) to 1364 ///< yield before returning ::ZE_RESULT_SUCCESS or ::ZE_RESULT_NOT_READY; 1365 ///< if zero, then will check status and return immediately; 1366 ///< if UINT32_MAX, then function will not return until events arrive. 1367 uint32_t count, ///< [in] Number of device handles in phDevices. 1368 zes_device_handle_t* phDevices, ///< [in][range(0, count)] Device handles to listen to for events. Only 1369 ///< devices from the provided driver handle can be specified in this list. 1370 uint32_t* pNumDeviceEvents, ///< [in,out] Will contain the actual number of devices in phDevices that 1371 ///< generated events. If non-zero, check pEvents to determine the devices 1372 ///< and events that were received. 1373 zes_event_type_flags_t* pEvents ///< [in,out] An array that will continue the list of events for each 1374 ///< device listened in phDevices. 1375 ///< This array must be at least as big as count. 1376 ///< For every device handle in phDevices, this will provide the events 1377 ///< that occurred for that device at the same position in this array. If 1378 ///< no event was received for a given device, the corresponding array 1379 ///< entry will be zero. 1380 ); 1381 1382 /////////////////////////////////////////////////////////////////////////////// 1383 /// @brief Wait for events to be received from a one or more devices. 1384 /// 1385 /// @details 1386 /// - The application may call this function from simultaneous threads. 1387 /// - The implementation of this function should be lock-free. 1388 /// 1389 /// @returns 1390 /// - ::ZE_RESULT_SUCCESS 1391 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1392 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1393 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1394 /// + `nullptr == hDriver` 1395 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1396 /// + `nullptr == phDevices` 1397 /// + `nullptr == pNumDeviceEvents` 1398 /// + `nullptr == pEvents` 1399 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 1400 /// + User does not have permissions to listen to events. 1401 /// - ::ZE_RESULT_ERROR_INVALID_ARGUMENT 1402 /// + One or more of the supplied device handles belongs to a different driver. 1403 ZE_APIEXPORT ze_result_t ZE_APICALL 1404 zesDriverEventListenEx( 1405 ze_driver_handle_t hDriver, ///< [in] handle of the driver instance 1406 uint64_t timeout, ///< [in] if non-zero, then indicates the maximum time (in milliseconds) to 1407 ///< yield before returning ::ZE_RESULT_SUCCESS or ::ZE_RESULT_NOT_READY; 1408 ///< if zero, then will check status and return immediately; 1409 ///< if UINT64_MAX, then function will not return until events arrive. 1410 uint32_t count, ///< [in] Number of device handles in phDevices. 1411 zes_device_handle_t* phDevices, ///< [in][range(0, count)] Device handles to listen to for events. Only 1412 ///< devices from the provided driver handle can be specified in this list. 1413 uint32_t* pNumDeviceEvents, ///< [in,out] Will contain the actual number of devices in phDevices that 1414 ///< generated events. If non-zero, check pEvents to determine the devices 1415 ///< and events that were received. 1416 zes_event_type_flags_t* pEvents ///< [in,out] An array that will continue the list of events for each 1417 ///< device listened in phDevices. 1418 ///< This array must be at least as big as count. 1419 ///< For every device handle in phDevices, this will provide the events 1420 ///< that occurred for that device at the same position in this array. If 1421 ///< no event was received for a given device, the corresponding array 1422 ///< entry will be zero. 1423 ); 1424 1425 #if !defined(__GNUC__) 1426 #pragma endregion 1427 #endif 1428 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Firmware management 1429 #if !defined(__GNUC__) 1430 #pragma region fabric 1431 #endif 1432 /////////////////////////////////////////////////////////////////////////////// 1433 #ifndef ZES_MAX_FABRIC_PORT_MODEL_SIZE 1434 /// @brief Maximum Fabric port model string size 1435 #define ZES_MAX_FABRIC_PORT_MODEL_SIZE 256 1436 #endif // ZES_MAX_FABRIC_PORT_MODEL_SIZE 1437 1438 /////////////////////////////////////////////////////////////////////////////// 1439 #ifndef ZES_MAX_FABRIC_LINK_TYPE_SIZE 1440 /// @brief Maximum size of the buffer that will return information about link 1441 /// types 1442 #define ZES_MAX_FABRIC_LINK_TYPE_SIZE 256 1443 #endif // ZES_MAX_FABRIC_LINK_TYPE_SIZE 1444 1445 /////////////////////////////////////////////////////////////////////////////// 1446 /// @brief Fabric port status 1447 typedef enum _zes_fabric_port_status_t 1448 { 1449 ZES_FABRIC_PORT_STATUS_UNKNOWN = 0, ///< The port status cannot be determined 1450 ZES_FABRIC_PORT_STATUS_HEALTHY = 1, ///< The port is up and operating as expected 1451 ZES_FABRIC_PORT_STATUS_DEGRADED = 2, ///< The port is up but has quality and/or speed degradation 1452 ZES_FABRIC_PORT_STATUS_FAILED = 3, ///< Port connection instabilities are preventing workloads making forward 1453 ///< progress 1454 ZES_FABRIC_PORT_STATUS_DISABLED = 4, ///< The port is configured down 1455 ZES_FABRIC_PORT_STATUS_FORCE_UINT32 = 0x7fffffff 1456 1457 } zes_fabric_port_status_t; 1458 1459 /////////////////////////////////////////////////////////////////////////////// 1460 /// @brief Fabric port quality degradation reasons 1461 typedef uint32_t zes_fabric_port_qual_issue_flags_t; 1462 typedef enum _zes_fabric_port_qual_issue_flag_t 1463 { 1464 ZES_FABRIC_PORT_QUAL_ISSUE_FLAG_LINK_ERRORS = ZE_BIT(0),///< Excessive link errors are occurring 1465 ZES_FABRIC_PORT_QUAL_ISSUE_FLAG_SPEED = ZE_BIT(1), ///< There is a degradation in the bitrate and/or width of the link 1466 ZES_FABRIC_PORT_QUAL_ISSUE_FLAG_FORCE_UINT32 = 0x7fffffff 1467 1468 } zes_fabric_port_qual_issue_flag_t; 1469 1470 /////////////////////////////////////////////////////////////////////////////// 1471 /// @brief Fabric port failure reasons 1472 typedef uint32_t zes_fabric_port_failure_flags_t; 1473 typedef enum _zes_fabric_port_failure_flag_t 1474 { 1475 ZES_FABRIC_PORT_FAILURE_FLAG_FAILED = ZE_BIT(0),///< A previously operating link has failed. Hardware will automatically 1476 ///< retrain this port. This state will persist until either the physical 1477 ///< connection is removed or the link trains successfully. 1478 ZES_FABRIC_PORT_FAILURE_FLAG_TRAINING_TIMEOUT = ZE_BIT(1), ///< A connection has not been established within an expected time. 1479 ///< Hardware will continue to attempt port training. This status will 1480 ///< persist until either the physical connection is removed or the link 1481 ///< successfully trains. 1482 ZES_FABRIC_PORT_FAILURE_FLAG_FLAPPING = ZE_BIT(2), ///< Port has excessively trained and then transitioned down for some 1483 ///< period of time. Driver will allow port to continue to train, but will 1484 ///< not enable the port for use until the port has been disabled and 1485 ///< subsequently re-enabled using ::zesFabricPortSetConfig(). 1486 ZES_FABRIC_PORT_FAILURE_FLAG_FORCE_UINT32 = 0x7fffffff 1487 1488 } zes_fabric_port_failure_flag_t; 1489 1490 /////////////////////////////////////////////////////////////////////////////// 1491 /// @brief Unique identifier for a fabric port 1492 /// 1493 /// @details 1494 /// - This not a universal identifier. The identified is garanteed to be 1495 /// unique for the current hardware configuration of the system. Changes 1496 /// in the hardware may result in a different identifier for a given port. 1497 /// - The main purpose of this identifier to build up an instantaneous 1498 /// topology map of system connectivity. An application should enumerate 1499 /// all fabric ports and match ::zes_fabric_port_state_t.remotePortId to 1500 /// ::zes_fabric_port_properties_t.portId. 1501 typedef struct _zes_fabric_port_id_t 1502 { 1503 uint32_t fabricId; ///< [out] Unique identifier for the fabric end-point 1504 uint32_t attachId; ///< [out] Unique identifier for the device attachment point 1505 uint8_t portNumber; ///< [out] The logical port number (this is typically marked somewhere on 1506 ///< the physical device) 1507 1508 } zes_fabric_port_id_t; 1509 1510 /////////////////////////////////////////////////////////////////////////////// 1511 /// @brief Fabric port speed in one direction 1512 typedef struct _zes_fabric_port_speed_t 1513 { 1514 int64_t bitRate; ///< [out] Bits/sec that the link is operating at. A value of -1 means that 1515 ///< this property is unknown. 1516 int32_t width; ///< [out] The number of lanes. A value of -1 means that this property is 1517 ///< unknown. 1518 1519 } zes_fabric_port_speed_t; 1520 1521 /////////////////////////////////////////////////////////////////////////////// 1522 /// @brief Fabric port properties 1523 typedef struct _zes_fabric_port_properties_t 1524 { 1525 zes_structure_type_t stype; ///< [in] type of this structure 1526 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 1527 char model[ZES_MAX_FABRIC_PORT_MODEL_SIZE]; ///< [out] Description of port technology. Will be set to the string 1528 ///< "unkown" if this cannot be determined for this port. 1529 ze_bool_t onSubdevice; ///< [out] True if the port is located on a sub-device; false means that 1530 ///< the port is on the device of the calling Sysman handle 1531 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 1532 zes_fabric_port_id_t portId; ///< [out] The unique port identifier 1533 zes_fabric_port_speed_t maxRxSpeed; ///< [out] Maximum speed supported by the receive side of the port (sum of 1534 ///< all lanes) 1535 zes_fabric_port_speed_t maxTxSpeed; ///< [out] Maximum speed supported by the transmit side of the port (sum of 1536 ///< all lanes) 1537 1538 } zes_fabric_port_properties_t; 1539 1540 /////////////////////////////////////////////////////////////////////////////// 1541 /// @brief Provides information about the fabric link attached to a port 1542 typedef struct _zes_fabric_link_type_t 1543 { 1544 char desc[ZES_MAX_FABRIC_LINK_TYPE_SIZE]; ///< [out] This provides a static textural description of the physic 1545 ///< attachment type. Will be set to the string "unkown" if this cannot be 1546 ///< determined for this port. 1547 1548 } zes_fabric_link_type_t; 1549 1550 /////////////////////////////////////////////////////////////////////////////// 1551 /// @brief Fabric port configuration 1552 typedef struct _zes_fabric_port_config_t 1553 { 1554 zes_structure_type_t stype; ///< [in] type of this structure 1555 const void* pNext; ///< [in][optional] pointer to extension-specific structure 1556 ze_bool_t enabled; ///< [in,out] Port is configured up/down 1557 ze_bool_t beaconing; ///< [in,out] Beaconing is configured on/off 1558 1559 } zes_fabric_port_config_t; 1560 1561 /////////////////////////////////////////////////////////////////////////////// 1562 /// @brief Fabric port state 1563 typedef struct _zes_fabric_port_state_t 1564 { 1565 zes_structure_type_t stype; ///< [in] type of this structure 1566 const void* pNext; ///< [in][optional] pointer to extension-specific structure 1567 zes_fabric_port_status_t status; ///< [out] The current status of the port 1568 zes_fabric_port_qual_issue_flags_t qualityIssues; ///< [out] If status is ::ZES_FABRIC_PORT_STATUS_DEGRADED, 1569 ///< then this gives a combination of ::zes_fabric_port_qual_issue_flag_t 1570 ///< for quality issues that have been detected; 1571 ///< otherwise, 0 indicates there are no quality issues with the link at 1572 ///< this time. 1573 zes_fabric_port_failure_flags_t failureReasons; ///< [out] If status is ::ZES_FABRIC_PORT_STATUS_FAILED, 1574 ///< then this gives a combination of ::zes_fabric_port_failure_flag_t for 1575 ///< reasons for the connection instability; 1576 ///< otherwise, 0 indicates there are no connection stability issues at 1577 ///< this time. 1578 zes_fabric_port_id_t remotePortId; ///< [out] The unique port identifier for the remote connection point if 1579 ///< status is ::ZES_FABRIC_PORT_STATUS_HEALTHY, 1580 ///< ::ZES_FABRIC_PORT_STATUS_DEGRADED or ::ZES_FABRIC_PORT_STATUS_FAILED 1581 zes_fabric_port_speed_t rxSpeed; ///< [out] Current maximum receive speed (sum of all lanes) 1582 zes_fabric_port_speed_t txSpeed; ///< [out] Current maximum transmit speed (sum of all lanes) 1583 1584 } zes_fabric_port_state_t; 1585 1586 /////////////////////////////////////////////////////////////////////////////// 1587 /// @brief Fabric port throughput. 1588 typedef struct _zes_fabric_port_throughput_t 1589 { 1590 uint64_t timestamp; ///< [out] Monotonic timestamp counter in microseconds when the measurement 1591 ///< was made. 1592 ///< This timestamp should only be used to calculate delta time between 1593 ///< snapshots of this structure. 1594 ///< Never take the delta of this timestamp with the timestamp from a 1595 ///< different structure since they are not guaranteed to have the same base. 1596 ///< The absolute value of the timestamp is only valid during within the 1597 ///< application and may be different on the next execution. 1598 uint64_t rxCounter; ///< [out] Monotonic counter for the number of bytes received (sum of all 1599 ///< lanes). This includes all protocol overhead, not only the GPU traffic. 1600 uint64_t txCounter; ///< [out] Monotonic counter for the number of bytes transmitted (sum of 1601 ///< all lanes). This includes all protocol overhead, not only the GPU 1602 ///< traffic. 1603 1604 } zes_fabric_port_throughput_t; 1605 1606 /////////////////////////////////////////////////////////////////////////////// 1607 /// @brief Get handle of Fabric ports in a device 1608 /// 1609 /// @details 1610 /// - The application may call this function from simultaneous threads. 1611 /// - The implementation of this function should be lock-free. 1612 /// 1613 /// @returns 1614 /// - ::ZE_RESULT_SUCCESS 1615 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1616 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1617 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1618 /// + `nullptr == hDevice` 1619 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1620 /// + `nullptr == pCount` 1621 ZE_APIEXPORT ze_result_t ZE_APICALL 1622 zesDeviceEnumFabricPorts( 1623 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 1624 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 1625 ///< if count is zero, then the driver shall update the value with the 1626 ///< total number of components of this type that are available. 1627 ///< if count is greater than the number of components of this type that 1628 ///< are available, then the driver shall update the value with the correct 1629 ///< number of components. 1630 zes_fabric_port_handle_t* phPort ///< [in,out][optional][range(0, *pCount)] array of handle of components of 1631 ///< this type. 1632 ///< if count is less than the number of components of this type that are 1633 ///< available, then the driver shall only retrieve that number of 1634 ///< component handles. 1635 ); 1636 1637 /////////////////////////////////////////////////////////////////////////////// 1638 /// @brief Get Fabric port properties 1639 /// 1640 /// @details 1641 /// - The application may call this function from simultaneous threads. 1642 /// - The implementation of this function should be lock-free. 1643 /// 1644 /// @returns 1645 /// - ::ZE_RESULT_SUCCESS 1646 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1647 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1648 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1649 /// + `nullptr == hPort` 1650 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1651 /// + `nullptr == pProperties` 1652 ZE_APIEXPORT ze_result_t ZE_APICALL 1653 zesFabricPortGetProperties( 1654 zes_fabric_port_handle_t hPort, ///< [in] Handle for the component. 1655 zes_fabric_port_properties_t* pProperties ///< [in,out] Will contain properties of the Fabric Port. 1656 ); 1657 1658 /////////////////////////////////////////////////////////////////////////////// 1659 /// @brief Get Fabric port link type 1660 /// 1661 /// @details 1662 /// - The application may call this function from simultaneous threads. 1663 /// - The implementation of this function should be lock-free. 1664 /// 1665 /// @returns 1666 /// - ::ZE_RESULT_SUCCESS 1667 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1668 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1669 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1670 /// + `nullptr == hPort` 1671 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1672 /// + `nullptr == pLinkType` 1673 ZE_APIEXPORT ze_result_t ZE_APICALL 1674 zesFabricPortGetLinkType( 1675 zes_fabric_port_handle_t hPort, ///< [in] Handle for the component. 1676 zes_fabric_link_type_t* pLinkType ///< [in,out] Will contain details about the link attached to the Fabric 1677 ///< port. 1678 ); 1679 1680 /////////////////////////////////////////////////////////////////////////////// 1681 /// @brief Get Fabric port configuration 1682 /// 1683 /// @details 1684 /// - The application may call this function from simultaneous threads. 1685 /// - The implementation of this function should be lock-free. 1686 /// 1687 /// @returns 1688 /// - ::ZE_RESULT_SUCCESS 1689 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1690 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1691 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1692 /// + `nullptr == hPort` 1693 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1694 /// + `nullptr == pConfig` 1695 ZE_APIEXPORT ze_result_t ZE_APICALL 1696 zesFabricPortGetConfig( 1697 zes_fabric_port_handle_t hPort, ///< [in] Handle for the component. 1698 zes_fabric_port_config_t* pConfig ///< [in,out] Will contain configuration of the Fabric Port. 1699 ); 1700 1701 /////////////////////////////////////////////////////////////////////////////// 1702 /// @brief Set Fabric port configuration 1703 /// 1704 /// @details 1705 /// - The application may call this function from simultaneous threads. 1706 /// - The implementation of this function should be lock-free. 1707 /// 1708 /// @returns 1709 /// - ::ZE_RESULT_SUCCESS 1710 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1711 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1712 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1713 /// + `nullptr == hPort` 1714 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1715 /// + `nullptr == pConfig` 1716 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 1717 /// + User does not have permissions to make these modifications. 1718 ZE_APIEXPORT ze_result_t ZE_APICALL 1719 zesFabricPortSetConfig( 1720 zes_fabric_port_handle_t hPort, ///< [in] Handle for the component. 1721 const zes_fabric_port_config_t* pConfig ///< [in] Contains new configuration of the Fabric Port. 1722 ); 1723 1724 /////////////////////////////////////////////////////////////////////////////// 1725 /// @brief Get Fabric port state - status (health/degraded/failed/disabled), 1726 /// reasons for link degradation or instability, current rx/tx speed 1727 /// 1728 /// @details 1729 /// - The application may call this function from simultaneous threads. 1730 /// - The implementation of this function should be lock-free. 1731 /// 1732 /// @returns 1733 /// - ::ZE_RESULT_SUCCESS 1734 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1735 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1736 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1737 /// + `nullptr == hPort` 1738 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1739 /// + `nullptr == pState` 1740 ZE_APIEXPORT ze_result_t ZE_APICALL 1741 zesFabricPortGetState( 1742 zes_fabric_port_handle_t hPort, ///< [in] Handle for the component. 1743 zes_fabric_port_state_t* pState ///< [in,out] Will contain the current state of the Fabric Port 1744 ); 1745 1746 /////////////////////////////////////////////////////////////////////////////// 1747 /// @brief Get Fabric port throughput 1748 /// 1749 /// @details 1750 /// - The application may call this function from simultaneous threads. 1751 /// - The implementation of this function should be lock-free. 1752 /// 1753 /// @returns 1754 /// - ::ZE_RESULT_SUCCESS 1755 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1756 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1757 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1758 /// + `nullptr == hPort` 1759 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1760 /// + `nullptr == pThroughput` 1761 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 1762 /// + User does not have permissions to query this telemetry. 1763 ZE_APIEXPORT ze_result_t ZE_APICALL 1764 zesFabricPortGetThroughput( 1765 zes_fabric_port_handle_t hPort, ///< [in] Handle for the component. 1766 zes_fabric_port_throughput_t* pThroughput ///< [in,out] Will contain the Fabric port throughput counters. 1767 ); 1768 1769 #if !defined(__GNUC__) 1770 #pragma endregion 1771 #endif 1772 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Firmware management 1773 #if !defined(__GNUC__) 1774 #pragma region fan 1775 #endif 1776 /////////////////////////////////////////////////////////////////////////////// 1777 /// @brief Fan resource speed mode 1778 typedef enum _zes_fan_speed_mode_t 1779 { 1780 ZES_FAN_SPEED_MODE_DEFAULT = 0, ///< The fan speed is operating using the hardware default settings 1781 ZES_FAN_SPEED_MODE_FIXED = 1, ///< The fan speed is currently set to a fixed value 1782 ZES_FAN_SPEED_MODE_TABLE = 2, ///< The fan speed is currently controlled dynamically by hardware based on 1783 ///< a temp/speed table 1784 ZES_FAN_SPEED_MODE_FORCE_UINT32 = 0x7fffffff 1785 1786 } zes_fan_speed_mode_t; 1787 1788 /////////////////////////////////////////////////////////////////////////////// 1789 /// @brief Fan speed units 1790 typedef enum _zes_fan_speed_units_t 1791 { 1792 ZES_FAN_SPEED_UNITS_RPM = 0, ///< The fan speed is in units of revolutions per minute (rpm) 1793 ZES_FAN_SPEED_UNITS_PERCENT = 1, ///< The fan speed is a percentage of the maximum speed of the fan 1794 ZES_FAN_SPEED_UNITS_FORCE_UINT32 = 0x7fffffff 1795 1796 } zes_fan_speed_units_t; 1797 1798 /////////////////////////////////////////////////////////////////////////////// 1799 /// @brief Fan speed 1800 typedef struct _zes_fan_speed_t 1801 { 1802 int32_t speed; ///< [in,out] The speed of the fan. On output, a value of -1 indicates that 1803 ///< there is no fixed fan speed setting. 1804 zes_fan_speed_units_t units; ///< [in,out] The units that the fan speed is expressed in. On output, if 1805 ///< fan speed is -1 then units should be ignored. 1806 1807 } zes_fan_speed_t; 1808 1809 /////////////////////////////////////////////////////////////////////////////// 1810 /// @brief Fan temperature/speed pair 1811 typedef struct _zes_fan_temp_speed_t 1812 { 1813 uint32_t temperature; ///< [in,out] Temperature in degrees Celsius. 1814 zes_fan_speed_t speed; ///< [in,out] The speed of the fan 1815 1816 } zes_fan_temp_speed_t; 1817 1818 /////////////////////////////////////////////////////////////////////////////// 1819 #ifndef ZES_FAN_TEMP_SPEED_PAIR_COUNT 1820 /// @brief Maximum number of fan temperature/speed pairs in the fan speed table. 1821 #define ZES_FAN_TEMP_SPEED_PAIR_COUNT 32 1822 #endif // ZES_FAN_TEMP_SPEED_PAIR_COUNT 1823 1824 /////////////////////////////////////////////////////////////////////////////// 1825 /// @brief Fan speed table 1826 typedef struct _zes_fan_speed_table_t 1827 { 1828 int32_t numPoints; ///< [in,out] The number of valid points in the fan speed table. 0 means 1829 ///< that there is no fan speed table configured. -1 means that a fan speed 1830 ///< table is not supported by the hardware. 1831 zes_fan_temp_speed_t table[ZES_FAN_TEMP_SPEED_PAIR_COUNT]; ///< [in,out] Array of temperature/fan speed pairs. The table is ordered 1832 ///< based on temperature from lowest to highest. 1833 1834 } zes_fan_speed_table_t; 1835 1836 /////////////////////////////////////////////////////////////////////////////// 1837 /// @brief Fan properties 1838 typedef struct _zes_fan_properties_t 1839 { 1840 zes_structure_type_t stype; ///< [in] type of this structure 1841 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 1842 ze_bool_t onSubdevice; ///< [out] True if the resource is located on a sub-device; false means 1843 ///< that the resource is on the device of the calling Sysman handle 1844 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 1845 ze_bool_t canControl; ///< [out] Indicates if software can control the fan speed assuming the 1846 ///< user has permissions 1847 uint32_t supportedModes; ///< [out] Bitfield of supported fan configuration modes 1848 ///< (1<<::zes_fan_speed_mode_t) 1849 uint32_t supportedUnits; ///< [out] Bitfield of supported fan speed units 1850 ///< (1<<::zes_fan_speed_units_t) 1851 int32_t maxRPM; ///< [out] The maximum RPM of the fan. A value of -1 means that this 1852 ///< property is unknown. 1853 int32_t maxPoints; ///< [out] The maximum number of points in the fan temp/speed table. A 1854 ///< value of -1 means that this fan doesn't support providing a temp/speed 1855 ///< table. 1856 1857 } zes_fan_properties_t; 1858 1859 /////////////////////////////////////////////////////////////////////////////// 1860 /// @brief Fan configuration 1861 typedef struct _zes_fan_config_t 1862 { 1863 zes_structure_type_t stype; ///< [in] type of this structure 1864 const void* pNext; ///< [in][optional] pointer to extension-specific structure 1865 zes_fan_speed_mode_t mode; ///< [in,out] The fan speed mode (fixed, temp-speed table) 1866 zes_fan_speed_t speedFixed; ///< [in,out] The current fixed fan speed setting 1867 zes_fan_speed_table_t speedTable; ///< [out] A table containing temperature/speed pairs 1868 1869 } zes_fan_config_t; 1870 1871 /////////////////////////////////////////////////////////////////////////////// 1872 /// @brief Get handle of fans 1873 /// 1874 /// @details 1875 /// - The application may call this function from simultaneous threads. 1876 /// - The implementation of this function should be lock-free. 1877 /// 1878 /// @returns 1879 /// - ::ZE_RESULT_SUCCESS 1880 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1881 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1882 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1883 /// + `nullptr == hDevice` 1884 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1885 /// + `nullptr == pCount` 1886 ZE_APIEXPORT ze_result_t ZE_APICALL 1887 zesDeviceEnumFans( 1888 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 1889 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 1890 ///< if count is zero, then the driver shall update the value with the 1891 ///< total number of components of this type that are available. 1892 ///< if count is greater than the number of components of this type that 1893 ///< are available, then the driver shall update the value with the correct 1894 ///< number of components. 1895 zes_fan_handle_t* phFan ///< [in,out][optional][range(0, *pCount)] array of handle of components of 1896 ///< this type. 1897 ///< if count is less than the number of components of this type that are 1898 ///< available, then the driver shall only retrieve that number of 1899 ///< component handles. 1900 ); 1901 1902 /////////////////////////////////////////////////////////////////////////////// 1903 /// @brief Get fan properties 1904 /// 1905 /// @details 1906 /// - The application may call this function from simultaneous threads. 1907 /// - The implementation of this function should be lock-free. 1908 /// 1909 /// @returns 1910 /// - ::ZE_RESULT_SUCCESS 1911 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1912 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1913 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1914 /// + `nullptr == hFan` 1915 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1916 /// + `nullptr == pProperties` 1917 ZE_APIEXPORT ze_result_t ZE_APICALL 1918 zesFanGetProperties( 1919 zes_fan_handle_t hFan, ///< [in] Handle for the component. 1920 zes_fan_properties_t* pProperties ///< [in,out] Will contain the properties of the fan. 1921 ); 1922 1923 /////////////////////////////////////////////////////////////////////////////// 1924 /// @brief Get fan configurations and the current fan speed mode (default, fixed, 1925 /// temp-speed table) 1926 /// 1927 /// @details 1928 /// - The application may call this function from simultaneous threads. 1929 /// - The implementation of this function should be lock-free. 1930 /// 1931 /// @returns 1932 /// - ::ZE_RESULT_SUCCESS 1933 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1934 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1935 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1936 /// + `nullptr == hFan` 1937 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1938 /// + `nullptr == pConfig` 1939 ZE_APIEXPORT ze_result_t ZE_APICALL 1940 zesFanGetConfig( 1941 zes_fan_handle_t hFan, ///< [in] Handle for the component. 1942 zes_fan_config_t* pConfig ///< [in,out] Will contain the current configuration of the fan. 1943 ); 1944 1945 /////////////////////////////////////////////////////////////////////////////// 1946 /// @brief Configure the fan to run with hardware factory settings (set mode to 1947 /// ::ZES_FAN_SPEED_MODE_DEFAULT) 1948 /// 1949 /// @details 1950 /// - The application may call this function from simultaneous threads. 1951 /// - The implementation of this function should be lock-free. 1952 /// 1953 /// @returns 1954 /// - ::ZE_RESULT_SUCCESS 1955 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1956 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1957 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1958 /// + `nullptr == hFan` 1959 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 1960 /// + User does not have permissions to make these modifications. 1961 ZE_APIEXPORT ze_result_t ZE_APICALL 1962 zesFanSetDefaultMode( 1963 zes_fan_handle_t hFan ///< [in] Handle for the component. 1964 ); 1965 1966 /////////////////////////////////////////////////////////////////////////////// 1967 /// @brief Configure the fan to rotate at a fixed speed (set mode to 1968 /// ::ZES_FAN_SPEED_MODE_FIXED) 1969 /// 1970 /// @details 1971 /// - The application may call this function from simultaneous threads. 1972 /// - The implementation of this function should be lock-free. 1973 /// 1974 /// @returns 1975 /// - ::ZE_RESULT_SUCCESS 1976 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 1977 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 1978 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 1979 /// + `nullptr == hFan` 1980 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 1981 /// + `nullptr == speed` 1982 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 1983 /// + User does not have permissions to make these modifications. 1984 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 1985 /// + Fixing the fan speed not supported by the hardware or the fan speed units are not supported. See ::zes_fan_properties_t.supportedModes and ::zes_fan_properties_t.supportedUnits. 1986 ZE_APIEXPORT ze_result_t ZE_APICALL 1987 zesFanSetFixedSpeedMode( 1988 zes_fan_handle_t hFan, ///< [in] Handle for the component. 1989 const zes_fan_speed_t* speed ///< [in] The fixed fan speed setting 1990 ); 1991 1992 /////////////////////////////////////////////////////////////////////////////// 1993 /// @brief Configure the fan to adjust speed based on a temperature/speed table 1994 /// (set mode to ::ZES_FAN_SPEED_MODE_TABLE) 1995 /// 1996 /// @details 1997 /// - The application may call this function from simultaneous threads. 1998 /// - The implementation of this function should be lock-free. 1999 /// 2000 /// @returns 2001 /// - ::ZE_RESULT_SUCCESS 2002 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2003 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2004 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2005 /// + `nullptr == hFan` 2006 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2007 /// + `nullptr == speedTable` 2008 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2009 /// + User does not have permissions to make these modifications. 2010 /// - ::ZE_RESULT_ERROR_INVALID_ARGUMENT 2011 /// + The temperature/speed pairs in the array are not sorted on temperature from lowest to highest. 2012 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2013 /// + Fan speed table not supported by the hardware or the fan speed units are not supported. See ::zes_fan_properties_t.supportedModes and ::zes_fan_properties_t.supportedUnits. 2014 ZE_APIEXPORT ze_result_t ZE_APICALL 2015 zesFanSetSpeedTableMode( 2016 zes_fan_handle_t hFan, ///< [in] Handle for the component. 2017 const zes_fan_speed_table_t* speedTable ///< [in] A table containing temperature/speed pairs. 2018 ); 2019 2020 /////////////////////////////////////////////////////////////////////////////// 2021 /// @brief Get current state of a fan - current mode and speed 2022 /// 2023 /// @details 2024 /// - The application may call this function from simultaneous threads. 2025 /// - The implementation of this function should be lock-free. 2026 /// 2027 /// @returns 2028 /// - ::ZE_RESULT_SUCCESS 2029 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2030 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2031 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2032 /// + `nullptr == hFan` 2033 /// - ::ZE_RESULT_ERROR_INVALID_ENUMERATION 2034 /// + `::ZES_FAN_SPEED_UNITS_PERCENT < units` 2035 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2036 /// + `nullptr == pSpeed` 2037 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2038 /// + The requested fan speed units are not supported. See ::zes_fan_properties_t.supportedUnits. 2039 ZE_APIEXPORT ze_result_t ZE_APICALL 2040 zesFanGetState( 2041 zes_fan_handle_t hFan, ///< [in] Handle for the component. 2042 zes_fan_speed_units_t units, ///< [in] The units in which the fan speed should be returned. 2043 int32_t* pSpeed ///< [in,out] Will contain the current speed of the fan in the units 2044 ///< requested. A value of -1 indicates that the fan speed cannot be 2045 ///< measured. 2046 ); 2047 2048 #if !defined(__GNUC__) 2049 #pragma endregion 2050 #endif 2051 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Firmware management 2052 #if !defined(__GNUC__) 2053 #pragma region firmware 2054 #endif 2055 /////////////////////////////////////////////////////////////////////////////// 2056 /// @brief Firmware properties 2057 typedef struct _zes_firmware_properties_t 2058 { 2059 zes_structure_type_t stype; ///< [in] type of this structure 2060 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 2061 ze_bool_t onSubdevice; ///< [out] True if the resource is located on a sub-device; false means 2062 ///< that the resource is on the device of the calling Sysman handle 2063 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 2064 ze_bool_t canControl; ///< [out] Indicates if software can flash the firmware assuming the user 2065 ///< has permissions 2066 char name[ZES_STRING_PROPERTY_SIZE]; ///< [out] NULL terminated string value. The string "unknown" will be 2067 ///< returned if this property cannot be determined. 2068 char version[ZES_STRING_PROPERTY_SIZE]; ///< [out] NULL terminated string value. The string "unknown" will be 2069 ///< returned if this property cannot be determined. 2070 2071 } zes_firmware_properties_t; 2072 2073 /////////////////////////////////////////////////////////////////////////////// 2074 /// @brief Get handle of firmwares 2075 /// 2076 /// @details 2077 /// - The application may call this function from simultaneous threads. 2078 /// - The implementation of this function should be lock-free. 2079 /// 2080 /// @returns 2081 /// - ::ZE_RESULT_SUCCESS 2082 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2083 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2084 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2085 /// + `nullptr == hDevice` 2086 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2087 /// + `nullptr == pCount` 2088 ZE_APIEXPORT ze_result_t ZE_APICALL 2089 zesDeviceEnumFirmwares( 2090 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 2091 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 2092 ///< if count is zero, then the driver shall update the value with the 2093 ///< total number of components of this type that are available. 2094 ///< if count is greater than the number of components of this type that 2095 ///< are available, then the driver shall update the value with the correct 2096 ///< number of components. 2097 zes_firmware_handle_t* phFirmware ///< [in,out][optional][range(0, *pCount)] array of handle of components of 2098 ///< this type. 2099 ///< if count is less than the number of components of this type that are 2100 ///< available, then the driver shall only retrieve that number of 2101 ///< component handles. 2102 ); 2103 2104 /////////////////////////////////////////////////////////////////////////////// 2105 /// @brief Get firmware properties 2106 /// 2107 /// @details 2108 /// - The application may call this function from simultaneous threads. 2109 /// - The implementation of this function should be lock-free. 2110 /// 2111 /// @returns 2112 /// - ::ZE_RESULT_SUCCESS 2113 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2114 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2115 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2116 /// + `nullptr == hFirmware` 2117 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2118 /// + `nullptr == pProperties` 2119 ZE_APIEXPORT ze_result_t ZE_APICALL 2120 zesFirmwareGetProperties( 2121 zes_firmware_handle_t hFirmware, ///< [in] Handle for the component. 2122 zes_firmware_properties_t* pProperties ///< [in,out] Pointer to an array that will hold the properties of the 2123 ///< firmware 2124 ); 2125 2126 /////////////////////////////////////////////////////////////////////////////// 2127 /// @brief Flash a new firmware image 2128 /// 2129 /// @details 2130 /// - The application may call this function from simultaneous threads. 2131 /// - The implementation of this function should be lock-free. 2132 /// 2133 /// @returns 2134 /// - ::ZE_RESULT_SUCCESS 2135 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2136 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2137 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2138 /// + `nullptr == hFirmware` 2139 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2140 /// + `nullptr == pImage` 2141 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2142 /// + User does not have permissions to perform this operation. 2143 ZE_APIEXPORT ze_result_t ZE_APICALL 2144 zesFirmwareFlash( 2145 zes_firmware_handle_t hFirmware, ///< [in] Handle for the component. 2146 void* pImage, ///< [in] Image of the new firmware to flash. 2147 uint32_t size ///< [in] Size of the flash image. 2148 ); 2149 2150 #if !defined(__GNUC__) 2151 #pragma endregion 2152 #endif 2153 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Frequency domains 2154 #if !defined(__GNUC__) 2155 #pragma region frequency 2156 #endif 2157 /////////////////////////////////////////////////////////////////////////////// 2158 /// @brief Frequency domains. 2159 typedef enum _zes_freq_domain_t 2160 { 2161 ZES_FREQ_DOMAIN_GPU = 0, ///< GPU Core Domain. 2162 ZES_FREQ_DOMAIN_MEMORY = 1, ///< Local Memory Domain. 2163 ZES_FREQ_DOMAIN_FORCE_UINT32 = 0x7fffffff 2164 2165 } zes_freq_domain_t; 2166 2167 /////////////////////////////////////////////////////////////////////////////// 2168 /// @brief Frequency properties 2169 /// 2170 /// @details 2171 /// - Indicates if this frequency domain can be overclocked (if true, 2172 /// functions such as ::zesFrequencyOcSetFrequencyTarget() are supported). 2173 /// - The min/max hardware frequencies are specified for non-overclock 2174 /// configurations. For overclock configurations, use 2175 /// ::zesFrequencyOcGetFrequencyTarget() to determine the maximum 2176 /// frequency that can be requested. 2177 typedef struct _zes_freq_properties_t 2178 { 2179 zes_structure_type_t stype; ///< [in] type of this structure 2180 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 2181 zes_freq_domain_t type; ///< [out] The hardware block that this frequency domain controls (GPU, 2182 ///< memory, ...) 2183 ze_bool_t onSubdevice; ///< [out] True if this resource is located on a sub-device; false means 2184 ///< that the resource is on the device of the calling Sysman handle 2185 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 2186 ze_bool_t canControl; ///< [out] Indicates if software can control the frequency of this domain 2187 ///< assuming the user has permissions 2188 ze_bool_t isThrottleEventSupported; ///< [out] Indicates if software can register to receive event 2189 ///< ::ZES_EVENT_TYPE_FLAG_FREQ_THROTTLED 2190 double min; ///< [out] The minimum hardware clock frequency in units of MHz. 2191 double max; ///< [out] The maximum non-overclock hardware clock frequency in units of 2192 ///< MHz. 2193 2194 } zes_freq_properties_t; 2195 2196 /////////////////////////////////////////////////////////////////////////////// 2197 /// @brief Frequency range between which the hardware can operate. The limits can 2198 /// be above or below the hardware limits - the hardware will clamp 2199 /// appropriately. 2200 typedef struct _zes_freq_range_t 2201 { 2202 double min; ///< [in,out] The min frequency in MHz below which hardware frequency 2203 ///< management will not request frequencies. On input, setting to 0 will 2204 ///< permit the frequency to go down to the hardware minimum. On output, a 2205 ///< negative value indicates that no external minimum frequency limit is 2206 ///< in effect. 2207 double max; ///< [in,out] The max frequency in MHz above which hardware frequency 2208 ///< management will not request frequencies. On input, setting to 0 or a 2209 ///< very big number will permit the frequency to go all the way up to the 2210 ///< hardware maximum. On output, a negative number indicates that no 2211 ///< external maximum frequency limit is in effect. 2212 2213 } zes_freq_range_t; 2214 2215 /////////////////////////////////////////////////////////////////////////////// 2216 /// @brief Frequency throttle reasons 2217 typedef uint32_t zes_freq_throttle_reason_flags_t; 2218 typedef enum _zes_freq_throttle_reason_flag_t 2219 { 2220 ZES_FREQ_THROTTLE_REASON_FLAG_AVE_PWR_CAP = ZE_BIT(0), ///< frequency throttled due to average power excursion (PL1) 2221 ZES_FREQ_THROTTLE_REASON_FLAG_BURST_PWR_CAP = ZE_BIT(1),///< frequency throttled due to burst power excursion (PL2) 2222 ZES_FREQ_THROTTLE_REASON_FLAG_CURRENT_LIMIT = ZE_BIT(2),///< frequency throttled due to current excursion (PL4) 2223 ZES_FREQ_THROTTLE_REASON_FLAG_THERMAL_LIMIT = ZE_BIT(3),///< frequency throttled due to thermal excursion (T > TjMax) 2224 ZES_FREQ_THROTTLE_REASON_FLAG_PSU_ALERT = ZE_BIT(4),///< frequency throttled due to power supply assertion 2225 ZES_FREQ_THROTTLE_REASON_FLAG_SW_RANGE = ZE_BIT(5), ///< frequency throttled due to software supplied frequency range 2226 ZES_FREQ_THROTTLE_REASON_FLAG_HW_RANGE = ZE_BIT(6), ///< frequency throttled due to a sub block that has a lower frequency 2227 ///< range when it receives clocks 2228 ZES_FREQ_THROTTLE_REASON_FLAG_FORCE_UINT32 = 0x7fffffff 2229 2230 } zes_freq_throttle_reason_flag_t; 2231 2232 /////////////////////////////////////////////////////////////////////////////// 2233 /// @brief Frequency state 2234 typedef struct _zes_freq_state_t 2235 { 2236 zes_structure_type_t stype; ///< [in] type of this structure 2237 const void* pNext; ///< [in][optional] pointer to extension-specific structure 2238 double currentVoltage; ///< [out] Current voltage in Volts. A negative value indicates that this 2239 ///< property is not known. 2240 double request; ///< [out] The current frequency request in MHz. A negative value indicates 2241 ///< that this property is not known. 2242 double tdp; ///< [out] The maximum frequency in MHz supported under the current TDP 2243 ///< conditions. This fluctuates dynamically based on the power and thermal 2244 ///< limits of the part. A negative value indicates that this property is 2245 ///< not known. 2246 double efficient; ///< [out] The efficient minimum frequency in MHz. A negative value 2247 ///< indicates that this property is not known. 2248 double actual; ///< [out] The resolved frequency in MHz. A negative value indicates that 2249 ///< this property is not known. 2250 zes_freq_throttle_reason_flags_t throttleReasons; ///< [out] The reasons that the frequency is being limited by the hardware. 2251 ///< Returns 0 (frequency not throttled) or a combination of ::zes_freq_throttle_reason_flag_t. 2252 2253 } zes_freq_state_t; 2254 2255 /////////////////////////////////////////////////////////////////////////////// 2256 /// @brief Frequency throttle time snapshot 2257 /// 2258 /// @details 2259 /// - Percent time throttled is calculated by taking two snapshots (s1, s2) 2260 /// and using the equation: %throttled = (s2.throttleTime - 2261 /// s1.throttleTime) / (s2.timestamp - s1.timestamp) 2262 typedef struct _zes_freq_throttle_time_t 2263 { 2264 uint64_t throttleTime; ///< [out] The monotonic counter of time in microseconds that the frequency 2265 ///< has been limited by the hardware. 2266 uint64_t timestamp; ///< [out] Microsecond timestamp when throttleTime was captured. 2267 ///< This timestamp should only be used to calculate delta time between 2268 ///< snapshots of this structure. 2269 ///< Never take the delta of this timestamp with the timestamp from a 2270 ///< different structure since they are not guaranteed to have the same base. 2271 ///< The absolute value of the timestamp is only valid during within the 2272 ///< application and may be different on the next execution. 2273 2274 } zes_freq_throttle_time_t; 2275 2276 /////////////////////////////////////////////////////////////////////////////// 2277 /// @brief Overclocking modes 2278 typedef enum _zes_oc_mode_t 2279 { 2280 ZES_OC_MODE_OFF = 0, ///< Overclocking if off - hardware is running using factory default 2281 ///< voltages/frequencies. 2282 ZES_OC_MODE_OVERRIDE = 1, ///< Overclock override mode - In this mode, a fixed user-supplied voltage 2283 ///< is applied independent of the frequency request. The maximum permitted 2284 ///< frequency can also be increased. This mode disables INTERPOLATIVE and 2285 ///< FIXED modes. 2286 ZES_OC_MODE_INTERPOLATIVE = 2, ///< Overclock interpolative mode - In this mode, the voltage/frequency 2287 ///< curve can be extended with a new voltage/frequency point that will be 2288 ///< interpolated. The existing voltage/frequency points can also be offset 2289 ///< (up or down) by a fixed voltage. This mode disables FIXED and OVERRIDE 2290 ///< modes. 2291 ZES_OC_MODE_FIXED = 3, ///< Overclocking fixed Mode - In this mode, hardware will disable most 2292 ///< frequency throttling and lock the frequency and voltage at the 2293 ///< specified overclock values. This mode disables OVERRIDE and 2294 ///< INTERPOLATIVE modes. This mode can damage the part, most of the 2295 ///< protections are disabled on this mode. 2296 ZES_OC_MODE_FORCE_UINT32 = 0x7fffffff 2297 2298 } zes_oc_mode_t; 2299 2300 /////////////////////////////////////////////////////////////////////////////// 2301 /// @brief Overclocking properties 2302 /// 2303 /// @details 2304 /// - Provides all the overclocking capabilities and properties supported by 2305 /// the device for the frequency domain. 2306 typedef struct _zes_oc_capabilities_t 2307 { 2308 zes_structure_type_t stype; ///< [in] type of this structure 2309 const void* pNext; ///< [in][optional] pointer to extension-specific structure 2310 ze_bool_t isOcSupported; ///< [out] Indicates if any overclocking features are supported on this 2311 ///< frequency domain. 2312 double maxFactoryDefaultFrequency; ///< [out] Factory default non-overclock maximum frequency in Mhz. 2313 double maxFactoryDefaultVoltage; ///< [out] Factory default voltage used for the non-overclock maximum 2314 ///< frequency in MHz. 2315 double maxOcFrequency; ///< [out] Maximum hardware overclocking frequency limit in Mhz. 2316 double minOcVoltageOffset; ///< [out] The minimum voltage offset that can be applied to the 2317 ///< voltage/frequency curve. Note that this number can be negative. 2318 double maxOcVoltageOffset; ///< [out] The maximum voltage offset that can be applied to the 2319 ///< voltage/frequency curve. 2320 double maxOcVoltage; ///< [out] The maximum overclock voltage that hardware supports. 2321 ze_bool_t isTjMaxSupported; ///< [out] Indicates if the maximum temperature limit (TjMax) can be 2322 ///< changed for this frequency domain. 2323 ze_bool_t isIccMaxSupported; ///< [out] Indicates if the maximum current (IccMax) can be changed for 2324 ///< this frequency domain. 2325 ze_bool_t isHighVoltModeCapable; ///< [out] Indicates if this frequency domains supports a feature to set 2326 ///< very high voltages. 2327 ze_bool_t isHighVoltModeEnabled; ///< [out] Indicates if very high voltages are permitted on this frequency 2328 ///< domain. 2329 ze_bool_t isExtendedModeSupported; ///< [out] Indicates if the extended overclocking features are supported. 2330 ///< If this is supported, increments are on 1 Mhz basis. 2331 ze_bool_t isFixedModeSupported; ///< [out] Indicates if the fixed mode is supported. In this mode, hardware 2332 ///< will disable most frequency throttling and lock the frequency and 2333 ///< voltage at the specified overclock values. 2334 2335 } zes_oc_capabilities_t; 2336 2337 /////////////////////////////////////////////////////////////////////////////// 2338 /// @brief Get handle of frequency domains 2339 /// 2340 /// @details 2341 /// - The application may call this function from simultaneous threads. 2342 /// - The implementation of this function should be lock-free. 2343 /// 2344 /// @returns 2345 /// - ::ZE_RESULT_SUCCESS 2346 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2347 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2348 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2349 /// + `nullptr == hDevice` 2350 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2351 /// + `nullptr == pCount` 2352 ZE_APIEXPORT ze_result_t ZE_APICALL 2353 zesDeviceEnumFrequencyDomains( 2354 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 2355 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 2356 ///< if count is zero, then the driver shall update the value with the 2357 ///< total number of components of this type that are available. 2358 ///< if count is greater than the number of components of this type that 2359 ///< are available, then the driver shall update the value with the correct 2360 ///< number of components. 2361 zes_freq_handle_t* phFrequency ///< [in,out][optional][range(0, *pCount)] array of handle of components of 2362 ///< this type. 2363 ///< if count is less than the number of components of this type that are 2364 ///< available, then the driver shall only retrieve that number of 2365 ///< component handles. 2366 ); 2367 2368 /////////////////////////////////////////////////////////////////////////////// 2369 /// @brief Get frequency properties - available frequencies 2370 /// 2371 /// @details 2372 /// - The application may call this function from simultaneous threads. 2373 /// - The implementation of this function should be lock-free. 2374 /// 2375 /// @returns 2376 /// - ::ZE_RESULT_SUCCESS 2377 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2378 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2379 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2380 /// + `nullptr == hFrequency` 2381 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2382 /// + `nullptr == pProperties` 2383 ZE_APIEXPORT ze_result_t ZE_APICALL 2384 zesFrequencyGetProperties( 2385 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2386 zes_freq_properties_t* pProperties ///< [in,out] The frequency properties for the specified domain. 2387 ); 2388 2389 /////////////////////////////////////////////////////////////////////////////// 2390 /// @brief Get available non-overclocked hardware clock frequencies for the 2391 /// frequency domain 2392 /// 2393 /// @details 2394 /// - The list of available frequencies is returned in order of slowest to 2395 /// fastest. 2396 /// - The application may call this function from simultaneous threads. 2397 /// - The implementation of this function should be lock-free. 2398 /// 2399 /// @returns 2400 /// - ::ZE_RESULT_SUCCESS 2401 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2402 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2403 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2404 /// + `nullptr == hFrequency` 2405 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2406 /// + `nullptr == pCount` 2407 ZE_APIEXPORT ze_result_t ZE_APICALL 2408 zesFrequencyGetAvailableClocks( 2409 zes_freq_handle_t hFrequency, ///< [in] Sysman handle of the device. 2410 uint32_t* pCount, ///< [in,out] pointer to the number of frequencies. 2411 ///< if count is zero, then the driver shall update the value with the 2412 ///< total number of frequencies that are available. 2413 ///< if count is greater than the number of frequencies that are available, 2414 ///< then the driver shall update the value with the correct number of frequencies. 2415 double* phFrequency ///< [in,out][optional][range(0, *pCount)] array of frequencies in units of 2416 ///< MHz and sorted from slowest to fastest. 2417 ///< if count is less than the number of frequencies that are available, 2418 ///< then the driver shall only retrieve that number of frequencies. 2419 ); 2420 2421 /////////////////////////////////////////////////////////////////////////////// 2422 /// @brief Get current frequency limits 2423 /// 2424 /// @details 2425 /// - The application may call this function from simultaneous threads. 2426 /// - The implementation of this function should be lock-free. 2427 /// 2428 /// @returns 2429 /// - ::ZE_RESULT_SUCCESS 2430 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2431 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2432 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2433 /// + `nullptr == hFrequency` 2434 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2435 /// + `nullptr == pLimits` 2436 ZE_APIEXPORT ze_result_t ZE_APICALL 2437 zesFrequencyGetRange( 2438 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2439 zes_freq_range_t* pLimits ///< [in,out] The range between which the hardware can operate for the 2440 ///< specified domain. 2441 ); 2442 2443 /////////////////////////////////////////////////////////////////////////////// 2444 /// @brief Set frequency range between which the hardware can operate. 2445 /// 2446 /// @details 2447 /// - The application may call this function from simultaneous threads. 2448 /// - The implementation of this function should be lock-free. 2449 /// 2450 /// @returns 2451 /// - ::ZE_RESULT_SUCCESS 2452 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2453 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2454 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2455 /// + `nullptr == hFrequency` 2456 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2457 /// + `nullptr == pLimits` 2458 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2459 /// + User does not have permissions to make these modifications. 2460 ZE_APIEXPORT ze_result_t ZE_APICALL 2461 zesFrequencySetRange( 2462 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2463 const zes_freq_range_t* pLimits ///< [in] The limits between which the hardware can operate for the 2464 ///< specified domain. 2465 ); 2466 2467 /////////////////////////////////////////////////////////////////////////////// 2468 /// @brief Get current frequency state - frequency request, actual frequency, TDP 2469 /// limits 2470 /// 2471 /// @details 2472 /// - The application may call this function from simultaneous threads. 2473 /// - The implementation of this function should be lock-free. 2474 /// 2475 /// @returns 2476 /// - ::ZE_RESULT_SUCCESS 2477 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2478 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2479 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2480 /// + `nullptr == hFrequency` 2481 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2482 /// + `nullptr == pState` 2483 ZE_APIEXPORT ze_result_t ZE_APICALL 2484 zesFrequencyGetState( 2485 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2486 zes_freq_state_t* pState ///< [in,out] Frequency state for the specified domain. 2487 ); 2488 2489 /////////////////////////////////////////////////////////////////////////////// 2490 /// @brief Get frequency throttle time 2491 /// 2492 /// @details 2493 /// - The application may call this function from simultaneous threads. 2494 /// - The implementation of this function should be lock-free. 2495 /// 2496 /// @returns 2497 /// - ::ZE_RESULT_SUCCESS 2498 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2499 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2500 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2501 /// + `nullptr == hFrequency` 2502 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2503 /// + `nullptr == pThrottleTime` 2504 ZE_APIEXPORT ze_result_t ZE_APICALL 2505 zesFrequencyGetThrottleTime( 2506 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2507 zes_freq_throttle_time_t* pThrottleTime ///< [in,out] Will contain a snapshot of the throttle time counters for the 2508 ///< specified domain. 2509 ); 2510 2511 /////////////////////////////////////////////////////////////////////////////// 2512 /// @brief Get the overclocking capabilities. 2513 /// 2514 /// @details 2515 /// - The application may call this function from simultaneous threads. 2516 /// - The implementation of this function should be lock-free. 2517 /// 2518 /// @returns 2519 /// - ::ZE_RESULT_SUCCESS 2520 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2521 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2522 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2523 /// + `nullptr == hFrequency` 2524 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2525 /// + `nullptr == pOcCapabilities` 2526 ZE_APIEXPORT ze_result_t ZE_APICALL 2527 zesFrequencyOcGetCapabilities( 2528 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2529 zes_oc_capabilities_t* pOcCapabilities ///< [in,out] Pointer to the capabilities structure 2530 ///< ::zes_oc_capabilities_t. 2531 ); 2532 2533 /////////////////////////////////////////////////////////////////////////////// 2534 /// @brief Get the current overclocking frequency target, if extended moded is 2535 /// supported, will returned in 1 Mhz granularity. 2536 /// 2537 /// @details 2538 /// - The application may call this function from simultaneous threads. 2539 /// - The implementation of this function should be lock-free. 2540 /// 2541 /// @returns 2542 /// - ::ZE_RESULT_SUCCESS 2543 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2544 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2545 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2546 /// + `nullptr == hFrequency` 2547 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2548 /// + `nullptr == pCurrentOcFrequency` 2549 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2550 /// + Overclocking is not supported on this frequency domain (::zes_oc_capabilities_t.isOcSupported) 2551 /// + The specified voltage and/or frequency overclock settings exceed the hardware values (see ::zes_oc_capabilities_t.maxOcFrequency, ::zes_oc_capabilities_t.maxOcVoltage, ::zes_oc_capabilities_t.minOcVoltageOffset, ::zes_oc_capabilities_t.maxOcVoltageOffset). 2552 /// + Requested voltage overclock is very high but ::zes_oc_capabilities_t.isHighVoltModeEnabled is not enabled for the device. 2553 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 2554 /// + Overclocking feature is locked on this frequency domain 2555 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2556 /// + User does not have permissions to make these modifications. 2557 ZE_APIEXPORT ze_result_t ZE_APICALL 2558 zesFrequencyOcGetFrequencyTarget( 2559 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2560 double* pCurrentOcFrequency ///< [out] Overclocking Frequency in MHz, if extended moded is supported, 2561 ///< will returned in 1 Mhz granularity, else, in multiples of 50 Mhz. This 2562 ///< cannot be greater than ::zes_oc_capabilities_t.maxOcFrequency. 2563 ); 2564 2565 /////////////////////////////////////////////////////////////////////////////// 2566 /// @brief Set the current overclocking frequency target, if extended moded is 2567 /// supported, can be set in 1 Mhz granularity. 2568 /// 2569 /// @details 2570 /// - The application may call this function from simultaneous threads. 2571 /// - The implementation of this function should be lock-free. 2572 /// 2573 /// @returns 2574 /// - ::ZE_RESULT_SUCCESS 2575 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2576 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2577 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2578 /// + `nullptr == hFrequency` 2579 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2580 /// + Overclocking is not supported on this frequency domain (::zes_oc_capabilities_t.isOcSupported) 2581 /// + The specified voltage and/or frequency overclock settings exceed the hardware values (see ::zes_oc_capabilities_t.maxOcFrequency, ::zes_oc_capabilities_t.maxOcVoltage, ::zes_oc_capabilities_t.minOcVoltageOffset, ::zes_oc_capabilities_t.maxOcVoltageOffset). 2582 /// + Requested voltage overclock is very high but ::zes_oc_capabilities_t.isHighVoltModeEnabled is not enabled for the device. 2583 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 2584 /// + Overclocking feature is locked on this frequency domain 2585 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2586 /// + User does not have permissions to make these modifications. 2587 ZE_APIEXPORT ze_result_t ZE_APICALL 2588 zesFrequencyOcSetFrequencyTarget( 2589 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2590 double CurrentOcFrequency ///< [in] Overclocking Frequency in MHz, if extended moded is supported, it 2591 ///< could be set in 1 Mhz granularity, else, in multiples of 50 Mhz. This 2592 ///< cannot be greater than ::zes_oc_capabilities_t.maxOcFrequency. 2593 ); 2594 2595 /////////////////////////////////////////////////////////////////////////////// 2596 /// @brief Get the current overclocking voltage settings. 2597 /// 2598 /// @details 2599 /// - The application may call this function from simultaneous threads. 2600 /// - The implementation of this function should be lock-free. 2601 /// 2602 /// @returns 2603 /// - ::ZE_RESULT_SUCCESS 2604 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2605 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2606 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2607 /// + `nullptr == hFrequency` 2608 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2609 /// + `nullptr == pCurrentVoltageTarget` 2610 /// + `nullptr == pCurrentVoltageOffset` 2611 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2612 /// + Overclocking is not supported on this frequency domain (::zes_oc_capabilities_t.isOcSupported) 2613 /// + The specified voltage and/or frequency overclock settings exceed the hardware values (see ::zes_oc_capabilities_t.maxOcFrequency, ::zes_oc_capabilities_t.maxOcVoltage, ::zes_oc_capabilities_t.minOcVoltageOffset, ::zes_oc_capabilities_t.maxOcVoltageOffset). 2614 /// + Requested voltage overclock is very high but ::zes_oc_capabilities_t.isHighVoltModeEnabled is not enabled for the device. 2615 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 2616 /// + Overclocking feature is locked on this frequency domain 2617 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2618 /// + User does not have permissions to make these modifications. 2619 ZE_APIEXPORT ze_result_t ZE_APICALL 2620 zesFrequencyOcGetVoltageTarget( 2621 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2622 double* pCurrentVoltageTarget, ///< [out] Overclock voltage in Volts. This cannot be greater than 2623 ///< ::zes_oc_capabilities_t.maxOcVoltage. 2624 double* pCurrentVoltageOffset ///< [out] This voltage offset is applied to all points on the 2625 ///< voltage/frequency curve, include the new overclock voltageTarget. It 2626 ///< can be in the range (::zes_oc_capabilities_t.minOcVoltageOffset, 2627 ///< ::zes_oc_capabilities_t.maxOcVoltageOffset). 2628 ); 2629 2630 /////////////////////////////////////////////////////////////////////////////// 2631 /// @brief Set the current overclocking voltage settings. 2632 /// 2633 /// @details 2634 /// - The application may call this function from simultaneous threads. 2635 /// - The implementation of this function should be lock-free. 2636 /// 2637 /// @returns 2638 /// - ::ZE_RESULT_SUCCESS 2639 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2640 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2641 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2642 /// + `nullptr == hFrequency` 2643 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2644 /// + Overclocking is not supported on this frequency domain (::zes_oc_capabilities_t.isOcSupported) 2645 /// + The specified voltage and/or frequency overclock settings exceed the hardware values (see ::zes_oc_capabilities_t.maxOcFrequency, ::zes_oc_capabilities_t.maxOcVoltage, ::zes_oc_capabilities_t.minOcVoltageOffset, ::zes_oc_capabilities_t.maxOcVoltageOffset). 2646 /// + Requested voltage overclock is very high but ::zes_oc_capabilities_t.isHighVoltModeEnabled is not enabled for the device. 2647 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 2648 /// + Overclocking feature is locked on this frequency domain 2649 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2650 /// + User does not have permissions to make these modifications. 2651 ZE_APIEXPORT ze_result_t ZE_APICALL 2652 zesFrequencyOcSetVoltageTarget( 2653 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2654 double CurrentVoltageTarget, ///< [in] Overclock voltage in Volts. This cannot be greater than 2655 ///< ::zes_oc_capabilities_t.maxOcVoltage. 2656 double CurrentVoltageOffset ///< [in] This voltage offset is applied to all points on the 2657 ///< voltage/frequency curve, include the new overclock voltageTarget. It 2658 ///< can be in the range (::zes_oc_capabilities_t.minOcVoltageOffset, 2659 ///< ::zes_oc_capabilities_t.maxOcVoltageOffset). 2660 ); 2661 2662 /////////////////////////////////////////////////////////////////////////////// 2663 /// @brief Set the current overclocking mode. 2664 /// 2665 /// @details 2666 /// - The application may call this function from simultaneous threads. 2667 /// - The implementation of this function should be lock-free. 2668 /// 2669 /// @returns 2670 /// - ::ZE_RESULT_SUCCESS 2671 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2672 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2673 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2674 /// + `nullptr == hFrequency` 2675 /// - ::ZE_RESULT_ERROR_INVALID_ENUMERATION 2676 /// + `::ZES_OC_MODE_FIXED < CurrentOcMode` 2677 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2678 /// + Overclocking is not supported on this frequency domain (::zes_oc_capabilities_t.isOcSupported) 2679 /// + The specified voltage and/or frequency overclock settings exceed the hardware values (see ::zes_oc_capabilities_t.maxOcFrequency, ::zes_oc_capabilities_t.maxOcVoltage, ::zes_oc_capabilities_t.minOcVoltageOffset, ::zes_oc_capabilities_t.maxOcVoltageOffset). 2680 /// + Requested voltage overclock is very high but ::zes_oc_capabilities_t.isHighVoltModeEnabled is not enabled for the device. 2681 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 2682 /// + Overclocking feature is locked on this frequency domain 2683 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2684 /// + User does not have permissions to make these modifications. 2685 ZE_APIEXPORT ze_result_t ZE_APICALL 2686 zesFrequencyOcSetMode( 2687 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2688 zes_oc_mode_t CurrentOcMode ///< [in] Current Overclocking Mode ::zes_oc_mode_t. 2689 ); 2690 2691 /////////////////////////////////////////////////////////////////////////////// 2692 /// @brief Get the current overclocking mode. 2693 /// 2694 /// @details 2695 /// - The application may call this function from simultaneous threads. 2696 /// - The implementation of this function should be lock-free. 2697 /// 2698 /// @returns 2699 /// - ::ZE_RESULT_SUCCESS 2700 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2701 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2702 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2703 /// + `nullptr == hFrequency` 2704 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2705 /// + `nullptr == pCurrentOcMode` 2706 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2707 /// + Overclocking is not supported on this frequency domain (::zes_oc_capabilities_t.isOcSupported) 2708 /// + The specified voltage and/or frequency overclock settings exceed the hardware values (see ::zes_oc_capabilities_t.maxOcFrequency, ::zes_oc_capabilities_t.maxOcVoltage, ::zes_oc_capabilities_t.minOcVoltageOffset, ::zes_oc_capabilities_t.maxOcVoltageOffset). 2709 /// + Requested voltage overclock is very high but ::zes_oc_capabilities_t.isHighVoltModeEnabled is not enabled for the device. 2710 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 2711 /// + Overclocking feature is locked on this frequency domain 2712 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2713 /// + User does not have permissions to make these modifications. 2714 ZE_APIEXPORT ze_result_t ZE_APICALL 2715 zesFrequencyOcGetMode( 2716 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2717 zes_oc_mode_t* pCurrentOcMode ///< [out] Current Overclocking Mode ::zes_oc_mode_t. 2718 ); 2719 2720 /////////////////////////////////////////////////////////////////////////////// 2721 /// @brief Get the maximum current limit setting. 2722 /// 2723 /// @details 2724 /// - The application may call this function from simultaneous threads. 2725 /// - The implementation of this function should be lock-free. 2726 /// 2727 /// @returns 2728 /// - ::ZE_RESULT_SUCCESS 2729 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2730 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2731 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2732 /// + `nullptr == hFrequency` 2733 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2734 /// + `nullptr == pOcIccMax` 2735 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2736 /// + Overclocking is not supported on this frequency domain (::zes_oc_capabilities_t.isOcSupported) 2737 /// + Capability ::zes_oc_capabilities_t.isIccMaxSupported is false for this frequency domain 2738 ZE_APIEXPORT ze_result_t ZE_APICALL 2739 zesFrequencyOcGetIccMax( 2740 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2741 double* pOcIccMax ///< [in,out] Will contain the maximum current limit in Amperes on 2742 ///< successful return. 2743 ); 2744 2745 /////////////////////////////////////////////////////////////////////////////// 2746 /// @brief Change the maximum current limit setting. 2747 /// 2748 /// @details 2749 /// - Setting ocIccMax to 0.0 will return the value to the factory default. 2750 /// - The application may call this function from simultaneous threads. 2751 /// - The implementation of this function should be lock-free. 2752 /// 2753 /// @returns 2754 /// - ::ZE_RESULT_SUCCESS 2755 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2756 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2757 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2758 /// + `nullptr == hFrequency` 2759 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2760 /// + Overclocking is not supported on this frequency domain (::zes_oc_capabilities_t.isOcSupported) 2761 /// + Capability ::zes_oc_capabilities_t.isIccMaxSupported is false for this frequency domain 2762 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 2763 /// + Overclocking feature is locked on this frequency domain 2764 /// - ::ZE_RESULT_ERROR_INVALID_ARGUMENT 2765 /// + The specified current limit is too low or too high 2766 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2767 /// + User does not have permissions to make these modifications. 2768 ZE_APIEXPORT ze_result_t ZE_APICALL 2769 zesFrequencyOcSetIccMax( 2770 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2771 double ocIccMax ///< [in] The new maximum current limit in Amperes. 2772 ); 2773 2774 /////////////////////////////////////////////////////////////////////////////// 2775 /// @brief Get the maximum temperature limit setting. 2776 /// 2777 /// @details 2778 /// - The application may call this function from simultaneous threads. 2779 /// - The implementation of this function should be lock-free. 2780 /// 2781 /// @returns 2782 /// - ::ZE_RESULT_SUCCESS 2783 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2784 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2785 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2786 /// + `nullptr == hFrequency` 2787 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2788 /// + `nullptr == pOcTjMax` 2789 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2790 /// + Overclocking is not supported on this frequency domain (::zes_oc_capabilities_t.isOcSupported) 2791 ZE_APIEXPORT ze_result_t ZE_APICALL 2792 zesFrequencyOcGetTjMax( 2793 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2794 double* pOcTjMax ///< [in,out] Will contain the maximum temperature limit in degrees Celsius 2795 ///< on successful return. 2796 ); 2797 2798 /////////////////////////////////////////////////////////////////////////////// 2799 /// @brief Change the maximum temperature limit setting. 2800 /// 2801 /// @details 2802 /// - Setting ocTjMax to 0.0 will return the value to the factory default. 2803 /// - The application may call this function from simultaneous threads. 2804 /// - The implementation of this function should be lock-free. 2805 /// 2806 /// @returns 2807 /// - ::ZE_RESULT_SUCCESS 2808 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2809 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2810 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2811 /// + `nullptr == hFrequency` 2812 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2813 /// + Overclocking is not supported on this frequency domain (::zes_oc_capabilities_t.isOcSupported) 2814 /// + Capability ::zes_oc_capabilities_t.isTjMaxSupported is false for this frequency domain 2815 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 2816 /// + Overclocking feature is locked on this frequency domain 2817 /// - ::ZE_RESULT_ERROR_INVALID_ARGUMENT 2818 /// + The specified temperature limit is too high 2819 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2820 /// + User does not have permissions to make these modifications. 2821 ZE_APIEXPORT ze_result_t ZE_APICALL 2822 zesFrequencyOcSetTjMax( 2823 zes_freq_handle_t hFrequency, ///< [in] Handle for the component. 2824 double ocTjMax ///< [in] The new maximum temperature limit in degrees Celsius. 2825 ); 2826 2827 #if !defined(__GNUC__) 2828 #pragma endregion 2829 #endif 2830 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Firmware management 2831 #if !defined(__GNUC__) 2832 #pragma region led 2833 #endif 2834 /////////////////////////////////////////////////////////////////////////////// 2835 /// @brief LED properties 2836 typedef struct _zes_led_properties_t 2837 { 2838 zes_structure_type_t stype; ///< [in] type of this structure 2839 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 2840 ze_bool_t onSubdevice; ///< [out] True if the resource is located on a sub-device; false means 2841 ///< that the resource is on the device of the calling Sysman handle 2842 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 2843 ze_bool_t canControl; ///< [out] Indicates if software can control the LED assuming the user has 2844 ///< permissions 2845 ze_bool_t haveRGB; ///< [out] Indicates if the LED is RGB capable 2846 2847 } zes_led_properties_t; 2848 2849 /////////////////////////////////////////////////////////////////////////////// 2850 /// @brief LED color 2851 typedef struct _zes_led_color_t 2852 { 2853 double red; ///< [in,out][range(0.0, 1.0)] The LED red value. On output, a value less 2854 ///< than 0.0 indicates that the color is not known. 2855 double green; ///< [in,out][range(0.0, 1.0)] The LED green value. On output, a value less 2856 ///< than 0.0 indicates that the color is not known. 2857 double blue; ///< [in,out][range(0.0, 1.0)] The LED blue value. On output, a value less 2858 ///< than 0.0 indicates that the color is not known. 2859 2860 } zes_led_color_t; 2861 2862 /////////////////////////////////////////////////////////////////////////////// 2863 /// @brief LED state 2864 typedef struct _zes_led_state_t 2865 { 2866 zes_structure_type_t stype; ///< [in] type of this structure 2867 const void* pNext; ///< [in][optional] pointer to extension-specific structure 2868 ze_bool_t isOn; ///< [out] Indicates if the LED is on or off 2869 zes_led_color_t color; ///< [out] Color of the LED 2870 2871 } zes_led_state_t; 2872 2873 /////////////////////////////////////////////////////////////////////////////// 2874 /// @brief Get handle of LEDs 2875 /// 2876 /// @details 2877 /// - The application may call this function from simultaneous threads. 2878 /// - The implementation of this function should be lock-free. 2879 /// 2880 /// @returns 2881 /// - ::ZE_RESULT_SUCCESS 2882 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2883 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2884 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2885 /// + `nullptr == hDevice` 2886 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2887 /// + `nullptr == pCount` 2888 ZE_APIEXPORT ze_result_t ZE_APICALL 2889 zesDeviceEnumLeds( 2890 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 2891 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 2892 ///< if count is zero, then the driver shall update the value with the 2893 ///< total number of components of this type that are available. 2894 ///< if count is greater than the number of components of this type that 2895 ///< are available, then the driver shall update the value with the correct 2896 ///< number of components. 2897 zes_led_handle_t* phLed ///< [in,out][optional][range(0, *pCount)] array of handle of components of 2898 ///< this type. 2899 ///< if count is less than the number of components of this type that are 2900 ///< available, then the driver shall only retrieve that number of 2901 ///< component handles. 2902 ); 2903 2904 /////////////////////////////////////////////////////////////////////////////// 2905 /// @brief Get LED properties 2906 /// 2907 /// @details 2908 /// - The application may call this function from simultaneous threads. 2909 /// - The implementation of this function should be lock-free. 2910 /// 2911 /// @returns 2912 /// - ::ZE_RESULT_SUCCESS 2913 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2914 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2915 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2916 /// + `nullptr == hLed` 2917 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2918 /// + `nullptr == pProperties` 2919 ZE_APIEXPORT ze_result_t ZE_APICALL 2920 zesLedGetProperties( 2921 zes_led_handle_t hLed, ///< [in] Handle for the component. 2922 zes_led_properties_t* pProperties ///< [in,out] Will contain the properties of the LED. 2923 ); 2924 2925 /////////////////////////////////////////////////////////////////////////////// 2926 /// @brief Get current state of a LED - on/off, color 2927 /// 2928 /// @details 2929 /// - The application may call this function from simultaneous threads. 2930 /// - The implementation of this function should be lock-free. 2931 /// 2932 /// @returns 2933 /// - ::ZE_RESULT_SUCCESS 2934 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2935 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2936 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2937 /// + `nullptr == hLed` 2938 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2939 /// + `nullptr == pState` 2940 ZE_APIEXPORT ze_result_t ZE_APICALL 2941 zesLedGetState( 2942 zes_led_handle_t hLed, ///< [in] Handle for the component. 2943 zes_led_state_t* pState ///< [in,out] Will contain the current state of the LED. 2944 ); 2945 2946 /////////////////////////////////////////////////////////////////////////////// 2947 /// @brief Turn the LED on/off 2948 /// 2949 /// @details 2950 /// - The application may call this function from simultaneous threads. 2951 /// - The implementation of this function should be lock-free. 2952 /// 2953 /// @returns 2954 /// - ::ZE_RESULT_SUCCESS 2955 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2956 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2957 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2958 /// + `nullptr == hLed` 2959 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2960 /// + User does not have permissions to make these modifications. 2961 ZE_APIEXPORT ze_result_t ZE_APICALL 2962 zesLedSetState( 2963 zes_led_handle_t hLed, ///< [in] Handle for the component. 2964 ze_bool_t enable ///< [in] Set to TRUE to turn the LED on, FALSE to turn off. 2965 ); 2966 2967 /////////////////////////////////////////////////////////////////////////////// 2968 /// @brief Set the color of the LED 2969 /// 2970 /// @details 2971 /// - The application may call this function from simultaneous threads. 2972 /// - The implementation of this function should be lock-free. 2973 /// 2974 /// @returns 2975 /// - ::ZE_RESULT_SUCCESS 2976 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 2977 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 2978 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 2979 /// + `nullptr == hLed` 2980 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 2981 /// + `nullptr == pColor` 2982 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 2983 /// + User does not have permissions to make these modifications. 2984 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 2985 /// + This LED doesn't not support color changes. See ::zes_led_properties_t.haveRGB. 2986 ZE_APIEXPORT ze_result_t ZE_APICALL 2987 zesLedSetColor( 2988 zes_led_handle_t hLed, ///< [in] Handle for the component. 2989 const zes_led_color_t* pColor ///< [in] New color of the LED. 2990 ); 2991 2992 #if !defined(__GNUC__) 2993 #pragma endregion 2994 #endif 2995 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Memory management 2996 #if !defined(__GNUC__) 2997 #pragma region memory 2998 #endif 2999 /////////////////////////////////////////////////////////////////////////////// 3000 /// @brief Memory module types 3001 typedef enum _zes_mem_type_t 3002 { 3003 ZES_MEM_TYPE_HBM = 0, ///< HBM memory 3004 ZES_MEM_TYPE_DDR = 1, ///< DDR memory 3005 ZES_MEM_TYPE_DDR3 = 2, ///< DDR3 memory 3006 ZES_MEM_TYPE_DDR4 = 3, ///< DDR4 memory 3007 ZES_MEM_TYPE_DDR5 = 4, ///< DDR5 memory 3008 ZES_MEM_TYPE_LPDDR = 5, ///< LPDDR memory 3009 ZES_MEM_TYPE_LPDDR3 = 6, ///< LPDDR3 memory 3010 ZES_MEM_TYPE_LPDDR4 = 7, ///< LPDDR4 memory 3011 ZES_MEM_TYPE_LPDDR5 = 8, ///< LPDDR5 memory 3012 ZES_MEM_TYPE_SRAM = 9, ///< SRAM memory 3013 ZES_MEM_TYPE_L1 = 10, ///< L1 cache 3014 ZES_MEM_TYPE_L3 = 11, ///< L3 cache 3015 ZES_MEM_TYPE_GRF = 12, ///< Execution unit register file 3016 ZES_MEM_TYPE_SLM = 13, ///< Execution unit shared local memory 3017 ZES_MEM_TYPE_GDDR4 = 14, ///< GDDR4 memory 3018 ZES_MEM_TYPE_GDDR5 = 15, ///< GDDR5 memory 3019 ZES_MEM_TYPE_GDDR5X = 16, ///< GDDR5X memory 3020 ZES_MEM_TYPE_GDDR6 = 17, ///< GDDR6 memory 3021 ZES_MEM_TYPE_GDDR6X = 18, ///< GDDR6X memory 3022 ZES_MEM_TYPE_GDDR7 = 19, ///< GDDR7 memory 3023 ZES_MEM_TYPE_FORCE_UINT32 = 0x7fffffff 3024 3025 } zes_mem_type_t; 3026 3027 /////////////////////////////////////////////////////////////////////////////// 3028 /// @brief Memory module location 3029 typedef enum _zes_mem_loc_t 3030 { 3031 ZES_MEM_LOC_SYSTEM = 0, ///< System memory 3032 ZES_MEM_LOC_DEVICE = 1, ///< On board local device memory 3033 ZES_MEM_LOC_FORCE_UINT32 = 0x7fffffff 3034 3035 } zes_mem_loc_t; 3036 3037 /////////////////////////////////////////////////////////////////////////////// 3038 /// @brief Memory health 3039 typedef enum _zes_mem_health_t 3040 { 3041 ZES_MEM_HEALTH_UNKNOWN = 0, ///< The memory health cannot be determined. 3042 ZES_MEM_HEALTH_OK = 1, ///< All memory channels are healthy. 3043 ZES_MEM_HEALTH_DEGRADED = 2, ///< Excessive correctable errors have been detected on one or more 3044 ///< channels. Device should be reset. 3045 ZES_MEM_HEALTH_CRITICAL = 3, ///< Operating with reduced memory to cover banks with too many 3046 ///< uncorrectable errors. 3047 ZES_MEM_HEALTH_REPLACE = 4, ///< Device should be replaced due to excessive uncorrectable errors. 3048 ZES_MEM_HEALTH_FORCE_UINT32 = 0x7fffffff 3049 3050 } zes_mem_health_t; 3051 3052 /////////////////////////////////////////////////////////////////////////////// 3053 /// @brief Memory properties 3054 typedef struct _zes_mem_properties_t 3055 { 3056 zes_structure_type_t stype; ///< [in] type of this structure 3057 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 3058 zes_mem_type_t type; ///< [out] The memory type 3059 ze_bool_t onSubdevice; ///< [out] True if this resource is located on a sub-device; false means 3060 ///< that the resource is on the device of the calling Sysman handle 3061 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 3062 zes_mem_loc_t location; ///< [out] Location of this memory (system, device) 3063 uint64_t physicalSize; ///< [out] Physical memory size in bytes. A value of 0 indicates that this 3064 ///< property is not known. However, a call to ::zesMemoryGetState() will 3065 ///< correctly return the total size of usable memory. 3066 int32_t busWidth; ///< [out] Width of the memory bus. A value of -1 means that this property 3067 ///< is unknown. 3068 int32_t numChannels; ///< [out] The number of memory channels. A value of -1 means that this 3069 ///< property is unknown. 3070 3071 } zes_mem_properties_t; 3072 3073 /////////////////////////////////////////////////////////////////////////////// 3074 /// @brief Memory state - health, allocated 3075 /// 3076 /// @details 3077 /// - Percent allocation is given by 100 * (size - free / size. 3078 /// - Percent free is given by 100 * free / size. 3079 typedef struct _zes_mem_state_t 3080 { 3081 zes_structure_type_t stype; ///< [in] type of this structure 3082 const void* pNext; ///< [in][optional] pointer to extension-specific structure 3083 zes_mem_health_t health; ///< [out] Indicates the health of the memory 3084 uint64_t free; ///< [out] The free memory in bytes 3085 uint64_t size; ///< [out] The total allocatable memory in bytes (can be less than 3086 ///< ::zes_mem_properties_t.physicalSize) 3087 3088 } zes_mem_state_t; 3089 3090 /////////////////////////////////////////////////////////////////////////////// 3091 /// @brief Memory bandwidth 3092 /// 3093 /// @details 3094 /// - Percent bandwidth is calculated by taking two snapshots (s1, s2) and 3095 /// using the equation: %bw = 10^6 * ((s2.readCounter - s1.readCounter) + 3096 /// (s2.writeCounter - s1.writeCounter)) / (s2.maxBandwidth * 3097 /// (s2.timestamp - s1.timestamp)) 3098 typedef struct _zes_mem_bandwidth_t 3099 { 3100 uint64_t readCounter; ///< [out] Total bytes read from memory 3101 uint64_t writeCounter; ///< [out] Total bytes written to memory 3102 uint64_t maxBandwidth; ///< [out] Current maximum bandwidth in units of bytes/sec 3103 uint64_t timestamp; ///< [out] The timestamp when these measurements were sampled. 3104 ///< This timestamp should only be used to calculate delta time between 3105 ///< snapshots of this structure. 3106 ///< Never take the delta of this timestamp with the timestamp from a 3107 ///< different structure since they are not guaranteed to have the same base. 3108 ///< The absolute value of the timestamp is only valid during within the 3109 ///< application and may be different on the next execution. 3110 3111 } zes_mem_bandwidth_t; 3112 3113 /////////////////////////////////////////////////////////////////////////////// 3114 /// @brief Get handle of memory modules 3115 /// 3116 /// @details 3117 /// - The application may call this function from simultaneous threads. 3118 /// - The implementation of this function should be lock-free. 3119 /// 3120 /// @returns 3121 /// - ::ZE_RESULT_SUCCESS 3122 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3123 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3124 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3125 /// + `nullptr == hDevice` 3126 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3127 /// + `nullptr == pCount` 3128 ZE_APIEXPORT ze_result_t ZE_APICALL 3129 zesDeviceEnumMemoryModules( 3130 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 3131 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 3132 ///< if count is zero, then the driver shall update the value with the 3133 ///< total number of components of this type that are available. 3134 ///< if count is greater than the number of components of this type that 3135 ///< are available, then the driver shall update the value with the correct 3136 ///< number of components. 3137 zes_mem_handle_t* phMemory ///< [in,out][optional][range(0, *pCount)] array of handle of components of 3138 ///< this type. 3139 ///< if count is less than the number of components of this type that are 3140 ///< available, then the driver shall only retrieve that number of 3141 ///< component handles. 3142 ); 3143 3144 /////////////////////////////////////////////////////////////////////////////// 3145 /// @brief Get memory properties 3146 /// 3147 /// @details 3148 /// - The application may call this function from simultaneous threads. 3149 /// - The implementation of this function should be lock-free. 3150 /// 3151 /// @returns 3152 /// - ::ZE_RESULT_SUCCESS 3153 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3154 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3155 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3156 /// + `nullptr == hMemory` 3157 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3158 /// + `nullptr == pProperties` 3159 ZE_APIEXPORT ze_result_t ZE_APICALL 3160 zesMemoryGetProperties( 3161 zes_mem_handle_t hMemory, ///< [in] Handle for the component. 3162 zes_mem_properties_t* pProperties ///< [in,out] Will contain memory properties. 3163 ); 3164 3165 /////////////////////////////////////////////////////////////////////////////// 3166 /// @brief Get memory state - health, allocated 3167 /// 3168 /// @details 3169 /// - The application may call this function from simultaneous threads. 3170 /// - The implementation of this function should be lock-free. 3171 /// 3172 /// @returns 3173 /// - ::ZE_RESULT_SUCCESS 3174 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3175 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3176 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3177 /// + `nullptr == hMemory` 3178 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3179 /// + `nullptr == pState` 3180 ZE_APIEXPORT ze_result_t ZE_APICALL 3181 zesMemoryGetState( 3182 zes_mem_handle_t hMemory, ///< [in] Handle for the component. 3183 zes_mem_state_t* pState ///< [in,out] Will contain the current health and allocated memory. 3184 ); 3185 3186 /////////////////////////////////////////////////////////////////////////////// 3187 /// @brief Get memory bandwidth 3188 /// 3189 /// @details 3190 /// - The application may call this function from simultaneous threads. 3191 /// - The implementation of this function should be lock-free. 3192 /// 3193 /// @returns 3194 /// - ::ZE_RESULT_SUCCESS 3195 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3196 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3197 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3198 /// + `nullptr == hMemory` 3199 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3200 /// + `nullptr == pBandwidth` 3201 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 3202 /// + User does not have permissions to query this telemetry. 3203 ZE_APIEXPORT ze_result_t ZE_APICALL 3204 zesMemoryGetBandwidth( 3205 zes_mem_handle_t hMemory, ///< [in] Handle for the component. 3206 zes_mem_bandwidth_t* pBandwidth ///< [in,out] Will contain the current health, free memory, total memory 3207 ///< size. 3208 ); 3209 3210 #if !defined(__GNUC__) 3211 #pragma endregion 3212 #endif 3213 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Performance factor 3214 #if !defined(__GNUC__) 3215 #pragma region performance 3216 #endif 3217 /////////////////////////////////////////////////////////////////////////////// 3218 /// @brief Static information about a Performance Factor domain 3219 typedef struct _zes_perf_properties_t 3220 { 3221 zes_structure_type_t stype; ///< [in] type of this structure 3222 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 3223 ze_bool_t onSubdevice; ///< [out] True if this Performance Factor affects accelerators located on 3224 ///< a sub-device 3225 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 3226 zes_engine_type_flags_t engines; ///< [out] Bitfield of accelerator engine types that are affected by this 3227 ///< Performance Factor. 3228 3229 } zes_perf_properties_t; 3230 3231 /////////////////////////////////////////////////////////////////////////////// 3232 /// @brief Get handles to accelerator domains whose performance can be optimized 3233 /// via a Performance Factor 3234 /// 3235 /// @details 3236 /// - A Performance Factor should be tuned for each workload. 3237 /// - The application may call this function from simultaneous threads. 3238 /// - The implementation of this function should be lock-free. 3239 /// 3240 /// @returns 3241 /// - ::ZE_RESULT_SUCCESS 3242 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3243 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3244 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3245 /// + `nullptr == hDevice` 3246 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3247 /// + `nullptr == pCount` 3248 ZE_APIEXPORT ze_result_t ZE_APICALL 3249 zesDeviceEnumPerformanceFactorDomains( 3250 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 3251 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 3252 ///< if count is zero, then the driver shall update the value with the 3253 ///< total number of components of this type that are available. 3254 ///< if count is greater than the number of components of this type that 3255 ///< are available, then the driver shall update the value with the correct 3256 ///< number of components. 3257 zes_perf_handle_t* phPerf ///< [in,out][optional][range(0, *pCount)] array of handle of components of 3258 ///< this type. 3259 ///< if count is less than the number of components of this type that are 3260 ///< available, then the driver shall only retrieve that number of 3261 ///< component handles. 3262 ); 3263 3264 /////////////////////////////////////////////////////////////////////////////// 3265 /// @brief Get properties about a Performance Factor domain 3266 /// 3267 /// @details 3268 /// - The application may call this function from simultaneous threads. 3269 /// - The implementation of this function should be lock-free. 3270 /// 3271 /// @returns 3272 /// - ::ZE_RESULT_SUCCESS 3273 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3274 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3275 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3276 /// + `nullptr == hPerf` 3277 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3278 /// + `nullptr == pProperties` 3279 ZE_APIEXPORT ze_result_t ZE_APICALL 3280 zesPerformanceFactorGetProperties( 3281 zes_perf_handle_t hPerf, ///< [in] Handle for the Performance Factor domain. 3282 zes_perf_properties_t* pProperties ///< [in,out] Will contain information about the specified Performance 3283 ///< Factor domain. 3284 ); 3285 3286 /////////////////////////////////////////////////////////////////////////////// 3287 /// @brief Get current Performance Factor for a given domain 3288 /// 3289 /// @details 3290 /// - The application may call this function from simultaneous threads. 3291 /// - The implementation of this function should be lock-free. 3292 /// 3293 /// @returns 3294 /// - ::ZE_RESULT_SUCCESS 3295 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3296 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3297 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3298 /// + `nullptr == hPerf` 3299 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3300 /// + `nullptr == pFactor` 3301 ZE_APIEXPORT ze_result_t ZE_APICALL 3302 zesPerformanceFactorGetConfig( 3303 zes_perf_handle_t hPerf, ///< [in] Handle for the Performance Factor domain. 3304 double* pFactor ///< [in,out] Will contain the actual Performance Factor being used by the 3305 ///< hardware (may not be the same as the requested Performance Factor). 3306 ); 3307 3308 /////////////////////////////////////////////////////////////////////////////// 3309 /// @brief Change the performance factor for a domain 3310 /// 3311 /// @details 3312 /// - The Performance Factor is a number between 0 and 100. 3313 /// - A Performance Factor is a hint to the hardware. Depending on the 3314 /// hardware, the request may not be granted. Follow up this function with 3315 /// a call to ::zesPerformanceFactorGetConfig() to determine the actual 3316 /// factor being used by the hardware. 3317 /// - The application may call this function from simultaneous threads. 3318 /// - The implementation of this function should be lock-free. 3319 /// 3320 /// @returns 3321 /// - ::ZE_RESULT_SUCCESS 3322 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3323 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3324 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3325 /// + `nullptr == hPerf` 3326 ZE_APIEXPORT ze_result_t ZE_APICALL 3327 zesPerformanceFactorSetConfig( 3328 zes_perf_handle_t hPerf, ///< [in] Handle for the Performance Factor domain. 3329 double factor ///< [in] The new Performance Factor. 3330 ); 3331 3332 #if !defined(__GNUC__) 3333 #pragma endregion 3334 #endif 3335 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Scheduler management 3336 #if !defined(__GNUC__) 3337 #pragma region power 3338 #endif 3339 /////////////////////////////////////////////////////////////////////////////// 3340 /// @brief Properties related to device power settings 3341 typedef struct _zes_power_properties_t 3342 { 3343 zes_structure_type_t stype; ///< [in] type of this structure 3344 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 3345 ze_bool_t onSubdevice; ///< [out] True if this resource is located on a sub-device; false means 3346 ///< that the resource is on the device of the calling Sysman handle 3347 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 3348 ze_bool_t canControl; ///< [out] Software can change the power limits of this domain assuming the 3349 ///< user has permissions. 3350 ze_bool_t isEnergyThresholdSupported; ///< [out] Indicates if this power domain supports the energy threshold 3351 ///< event (::ZES_EVENT_TYPE_FLAG_ENERGY_THRESHOLD_CROSSED). 3352 int32_t defaultLimit; ///< [out] The factory default TDP power limit of the part in milliwatts. A 3353 ///< value of -1 means that this is not known. 3354 int32_t minLimit; ///< [out] The minimum power limit in milliwatts that can be requested. 3355 int32_t maxLimit; ///< [out] The maximum power limit in milliwatts that can be requested. 3356 3357 } zes_power_properties_t; 3358 3359 /////////////////////////////////////////////////////////////////////////////// 3360 /// @brief Energy counter snapshot 3361 /// 3362 /// @details 3363 /// - Average power is calculated by taking two snapshots (s1, s2) and using 3364 /// the equation: PowerWatts = (s2.energy - s1.energy) / (s2.timestamp - 3365 /// s1.timestamp) 3366 typedef struct _zes_power_energy_counter_t 3367 { 3368 uint64_t energy; ///< [out] The monotonic energy counter in microjoules. 3369 uint64_t timestamp; ///< [out] Microsecond timestamp when energy was captured. 3370 ///< This timestamp should only be used to calculate delta time between 3371 ///< snapshots of this structure. 3372 ///< Never take the delta of this timestamp with the timestamp from a 3373 ///< different structure since they are not guaranteed to have the same base. 3374 ///< The absolute value of the timestamp is only valid during within the 3375 ///< application and may be different on the next execution. 3376 3377 } zes_power_energy_counter_t; 3378 3379 /////////////////////////////////////////////////////////////////////////////// 3380 /// @brief Sustained power limits 3381 /// 3382 /// @details 3383 /// - The power controller (Punit) will throttle the operating frequency if 3384 /// the power averaged over a window (typically seconds) exceeds this 3385 /// limit. 3386 typedef struct _zes_power_sustained_limit_t 3387 { 3388 ze_bool_t enabled; ///< [in,out] indicates if the limit is enabled (true) or ignored (false) 3389 int32_t power; ///< [in,out] power limit in milliwatts 3390 int32_t interval; ///< [in,out] power averaging window (Tau) in milliseconds 3391 3392 } zes_power_sustained_limit_t; 3393 3394 /////////////////////////////////////////////////////////////////////////////// 3395 /// @brief Burst power limit 3396 /// 3397 /// @details 3398 /// - The power controller (Punit) will throttle the operating frequency of 3399 /// the device if the power averaged over a few milliseconds exceeds a 3400 /// limit known as PL2. Typically PL2 > PL1 so that it permits the 3401 /// frequency to burst higher for short periods than would be otherwise 3402 /// permitted by PL1. 3403 typedef struct _zes_power_burst_limit_t 3404 { 3405 ze_bool_t enabled; ///< [in,out] indicates if the limit is enabled (true) or ignored (false) 3406 int32_t power; ///< [in,out] power limit in milliwatts 3407 3408 } zes_power_burst_limit_t; 3409 3410 /////////////////////////////////////////////////////////////////////////////// 3411 /// @brief Peak power limit 3412 /// 3413 /// @details 3414 /// - The power controller (Punit) will reactively/proactively throttle the 3415 /// operating frequency of the device when the instantaneous/100usec power 3416 /// exceeds this limit. The limit is known as PL4 or Psys. It expresses 3417 /// the maximum power that can be drawn from the power supply. 3418 /// - If this power limit is removed or set too high, the power supply will 3419 /// generate an interrupt when it detects an overcurrent condition and the 3420 /// power controller will throttle the device frequencies down to min. It 3421 /// is thus better to tune the PL4 value in order to avoid such 3422 /// excursions. 3423 typedef struct _zes_power_peak_limit_t 3424 { 3425 int32_t powerAC; ///< [in,out] power limit in milliwatts for the AC power source. 3426 int32_t powerDC; ///< [in,out] power limit in milliwatts for the DC power source. On input, 3427 ///< this is ignored if the product does not have a battery. On output, 3428 ///< this will be -1 if the product does not have a battery. 3429 3430 } zes_power_peak_limit_t; 3431 3432 /////////////////////////////////////////////////////////////////////////////// 3433 /// @brief Energy threshold 3434 /// 3435 /// @details 3436 /// - . 3437 typedef struct _zes_energy_threshold_t 3438 { 3439 ze_bool_t enable; ///< [in,out] Indicates if the energy threshold is enabled. 3440 double threshold; ///< [in,out] The energy threshold in Joules. Will be 0.0 if no threshold 3441 ///< has been set. 3442 uint32_t processId; ///< [in,out] The host process ID that set the energy threshold. Will be 3443 ///< 0xFFFFFFFF if no threshold has been set. 3444 3445 } zes_energy_threshold_t; 3446 3447 /////////////////////////////////////////////////////////////////////////////// 3448 /// @brief Get handle of power domains 3449 /// 3450 /// @details 3451 /// - The application may call this function from simultaneous threads. 3452 /// - The implementation of this function should be lock-free. 3453 /// 3454 /// @returns 3455 /// - ::ZE_RESULT_SUCCESS 3456 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3457 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3458 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3459 /// + `nullptr == hDevice` 3460 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3461 /// + `nullptr == pCount` 3462 ZE_APIEXPORT ze_result_t ZE_APICALL 3463 zesDeviceEnumPowerDomains( 3464 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 3465 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 3466 ///< if count is zero, then the driver shall update the value with the 3467 ///< total number of components of this type that are available. 3468 ///< if count is greater than the number of components of this type that 3469 ///< are available, then the driver shall update the value with the correct 3470 ///< number of components. 3471 zes_pwr_handle_t* phPower ///< [in,out][optional][range(0, *pCount)] array of handle of components of 3472 ///< this type. 3473 ///< if count is less than the number of components of this type that are 3474 ///< available, then the driver shall only retrieve that number of 3475 ///< component handles. 3476 ); 3477 3478 /////////////////////////////////////////////////////////////////////////////// 3479 /// @brief Get handle of the PCIe card-level power 3480 /// 3481 /// @details 3482 /// - The application may call this function from simultaneous threads. 3483 /// - The implementation of this function should be lock-free. 3484 /// 3485 /// @returns 3486 /// - ::ZE_RESULT_SUCCESS 3487 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3488 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3489 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3490 /// + `nullptr == hDevice` 3491 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3492 /// + `nullptr == phPower` 3493 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 3494 /// + The device does not provide access to card level power controls or telemetry. An invalid power domain handle will be returned in phPower. 3495 ZE_APIEXPORT ze_result_t ZE_APICALL 3496 zesDeviceGetCardPowerDomain( 3497 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 3498 zes_pwr_handle_t* phPower ///< [in,out] power domain handle for the entire PCIe card. 3499 ); 3500 3501 /////////////////////////////////////////////////////////////////////////////// 3502 /// @brief Get properties related to a power domain 3503 /// 3504 /// @details 3505 /// - The application may call this function from simultaneous threads. 3506 /// - The implementation of this function should be lock-free. 3507 /// 3508 /// @returns 3509 /// - ::ZE_RESULT_SUCCESS 3510 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3511 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3512 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3513 /// + `nullptr == hPower` 3514 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3515 /// + `nullptr == pProperties` 3516 ZE_APIEXPORT ze_result_t ZE_APICALL 3517 zesPowerGetProperties( 3518 zes_pwr_handle_t hPower, ///< [in] Handle for the component. 3519 zes_power_properties_t* pProperties ///< [in,out] Structure that will contain property data. 3520 ); 3521 3522 /////////////////////////////////////////////////////////////////////////////// 3523 /// @brief Get energy counter 3524 /// 3525 /// @details 3526 /// - The application may call this function from simultaneous threads. 3527 /// - The implementation of this function should be lock-free. 3528 /// 3529 /// @returns 3530 /// - ::ZE_RESULT_SUCCESS 3531 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3532 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3533 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3534 /// + `nullptr == hPower` 3535 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3536 /// + `nullptr == pEnergy` 3537 ZE_APIEXPORT ze_result_t ZE_APICALL 3538 zesPowerGetEnergyCounter( 3539 zes_pwr_handle_t hPower, ///< [in] Handle for the component. 3540 zes_power_energy_counter_t* pEnergy ///< [in,out] Will contain the latest snapshot of the energy counter and 3541 ///< timestamp when the last counter value was measured. 3542 ); 3543 3544 /////////////////////////////////////////////////////////////////////////////// 3545 /// @brief Get power limits 3546 /// 3547 /// @details 3548 /// - The application may call this function from simultaneous threads. 3549 /// - The implementation of this function should be lock-free. 3550 /// 3551 /// @returns 3552 /// - ::ZE_RESULT_SUCCESS 3553 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3554 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3555 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3556 /// + `nullptr == hPower` 3557 ZE_APIEXPORT ze_result_t ZE_APICALL 3558 zesPowerGetLimits( 3559 zes_pwr_handle_t hPower, ///< [in] Handle for the component. 3560 zes_power_sustained_limit_t* pSustained, ///< [in,out][optional] The sustained power limit. If this is null, the 3561 ///< current sustained power limits will not be returned. 3562 zes_power_burst_limit_t* pBurst, ///< [in,out][optional] The burst power limit. If this is null, the current 3563 ///< peak power limits will not be returned. 3564 zes_power_peak_limit_t* pPeak ///< [in,out][optional] The peak power limit. If this is null, the peak 3565 ///< power limits will not be returned. 3566 ); 3567 3568 /////////////////////////////////////////////////////////////////////////////// 3569 /// @brief Set power limits 3570 /// 3571 /// @details 3572 /// - The application may call this function from simultaneous threads. 3573 /// - The implementation of this function should be lock-free. 3574 /// 3575 /// @returns 3576 /// - ::ZE_RESULT_SUCCESS 3577 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3578 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3579 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3580 /// + `nullptr == hPower` 3581 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 3582 /// + User does not have permissions to make these modifications. 3583 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 3584 /// + The device is in use, meaning that the GPU is under Over clocking, applying power limits under overclocking is not supported. 3585 ZE_APIEXPORT ze_result_t ZE_APICALL 3586 zesPowerSetLimits( 3587 zes_pwr_handle_t hPower, ///< [in] Handle for the component. 3588 const zes_power_sustained_limit_t* pSustained, ///< [in][optional] The sustained power limit. If this is null, no changes 3589 ///< will be made to the sustained power limits. 3590 const zes_power_burst_limit_t* pBurst, ///< [in][optional] The burst power limit. If this is null, no changes will 3591 ///< be made to the burst power limits. 3592 const zes_power_peak_limit_t* pPeak ///< [in][optional] The peak power limit. If this is null, no changes will 3593 ///< be made to the peak power limits. 3594 ); 3595 3596 /////////////////////////////////////////////////////////////////////////////// 3597 /// @brief Get energy threshold 3598 /// 3599 /// @details 3600 /// - The application may call this function from simultaneous threads. 3601 /// - The implementation of this function should be lock-free. 3602 /// 3603 /// @returns 3604 /// - ::ZE_RESULT_SUCCESS 3605 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3606 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3607 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3608 /// + `nullptr == hPower` 3609 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3610 /// + `nullptr == pThreshold` 3611 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 3612 /// + Energy threshold not supported on this power domain (check ::zes_power_properties_t.isEnergyThresholdSupported). 3613 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 3614 /// + User does not have permissions to request this feature. 3615 ZE_APIEXPORT ze_result_t ZE_APICALL 3616 zesPowerGetEnergyThreshold( 3617 zes_pwr_handle_t hPower, ///< [in] Handle for the component. 3618 zes_energy_threshold_t* pThreshold ///< [in,out] Returns information about the energy threshold setting - 3619 ///< enabled/energy threshold/process ID. 3620 ); 3621 3622 /////////////////////////////////////////////////////////////////////////////// 3623 /// @brief Set energy threshold 3624 /// 3625 /// @details 3626 /// - An event ::ZES_EVENT_TYPE_FLAG_ENERGY_THRESHOLD_CROSSED will be 3627 /// generated when the delta energy consumed starting from this call 3628 /// exceeds the specified threshold. Use the function 3629 /// ::zesDeviceEventRegister() to start receiving the event. 3630 /// - Only one running process can control the energy threshold at a given 3631 /// time. If another process attempts to change the energy threshold, the 3632 /// error ::ZE_RESULT_ERROR_NOT_AVAILABLE will be returned. The function 3633 /// ::zesPowerGetEnergyThreshold() to determine the process ID currently 3634 /// controlling this setting. 3635 /// - Calling this function will remove any pending energy thresholds and 3636 /// start counting from the time of this call. 3637 /// - Once the energy threshold has been reached and the event generated, 3638 /// the threshold is automatically removed. It is up to the application to 3639 /// request a new threshold. 3640 /// - The application may call this function from simultaneous threads. 3641 /// - The implementation of this function should be lock-free. 3642 /// 3643 /// @returns 3644 /// - ::ZE_RESULT_SUCCESS 3645 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3646 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3647 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3648 /// + `nullptr == hPower` 3649 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 3650 /// + Energy threshold not supported on this power domain (check ::zes_power_properties_t.isEnergyThresholdSupported). 3651 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 3652 /// + User does not have permissions to request this feature. 3653 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 3654 /// + Another running process has set the energy threshold. 3655 ZE_APIEXPORT ze_result_t ZE_APICALL 3656 zesPowerSetEnergyThreshold( 3657 zes_pwr_handle_t hPower, ///< [in] Handle for the component. 3658 double threshold ///< [in] The energy threshold to be set in joules. 3659 ); 3660 3661 #if !defined(__GNUC__) 3662 #pragma endregion 3663 #endif 3664 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Firmware management 3665 #if !defined(__GNUC__) 3666 #pragma region psu 3667 #endif 3668 /////////////////////////////////////////////////////////////////////////////// 3669 /// @brief PSU voltage status 3670 typedef enum _zes_psu_voltage_status_t 3671 { 3672 ZES_PSU_VOLTAGE_STATUS_UNKNOWN = 0, ///< The status of the power supply voltage controllers cannot be 3673 ///< determined 3674 ZES_PSU_VOLTAGE_STATUS_NORMAL = 1, ///< No unusual voltages have been detected 3675 ZES_PSU_VOLTAGE_STATUS_OVER = 2, ///< Over-voltage has occurred 3676 ZES_PSU_VOLTAGE_STATUS_UNDER = 3, ///< Under-voltage has occurred 3677 ZES_PSU_VOLTAGE_STATUS_FORCE_UINT32 = 0x7fffffff 3678 3679 } zes_psu_voltage_status_t; 3680 3681 /////////////////////////////////////////////////////////////////////////////// 3682 /// @brief Static properties of the power supply 3683 typedef struct _zes_psu_properties_t 3684 { 3685 zes_structure_type_t stype; ///< [in] type of this structure 3686 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 3687 ze_bool_t onSubdevice; ///< [out] True if the resource is located on a sub-device; false means 3688 ///< that the resource is on the device of the calling Sysman handle 3689 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 3690 ze_bool_t haveFan; ///< [out] True if the power supply has a fan 3691 int32_t ampLimit; ///< [out] The maximum electrical current in milliamperes that can be 3692 ///< drawn. A value of -1 indicates that this property cannot be 3693 ///< determined. 3694 3695 } zes_psu_properties_t; 3696 3697 /////////////////////////////////////////////////////////////////////////////// 3698 /// @brief Dynamic state of the power supply 3699 typedef struct _zes_psu_state_t 3700 { 3701 zes_structure_type_t stype; ///< [in] type of this structure 3702 const void* pNext; ///< [in][optional] pointer to extension-specific structure 3703 zes_psu_voltage_status_t voltStatus; ///< [out] The current PSU voltage status 3704 ze_bool_t fanFailed; ///< [out] Indicates if the fan has failed 3705 int32_t temperature; ///< [out] Read the current heatsink temperature in degrees Celsius. A 3706 ///< value of -1 indicates that this property cannot be determined. 3707 int32_t current; ///< [out] The amps being drawn in milliamperes. A value of -1 indicates 3708 ///< that this property cannot be determined. 3709 3710 } zes_psu_state_t; 3711 3712 /////////////////////////////////////////////////////////////////////////////// 3713 /// @brief Get handle of power supplies 3714 /// 3715 /// @details 3716 /// - The application may call this function from simultaneous threads. 3717 /// - The implementation of this function should be lock-free. 3718 /// 3719 /// @returns 3720 /// - ::ZE_RESULT_SUCCESS 3721 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3722 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3723 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3724 /// + `nullptr == hDevice` 3725 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3726 /// + `nullptr == pCount` 3727 ZE_APIEXPORT ze_result_t ZE_APICALL 3728 zesDeviceEnumPsus( 3729 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 3730 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 3731 ///< if count is zero, then the driver shall update the value with the 3732 ///< total number of components of this type that are available. 3733 ///< if count is greater than the number of components of this type that 3734 ///< are available, then the driver shall update the value with the correct 3735 ///< number of components. 3736 zes_psu_handle_t* phPsu ///< [in,out][optional][range(0, *pCount)] array of handle of components of 3737 ///< this type. 3738 ///< if count is less than the number of components of this type that are 3739 ///< available, then the driver shall only retrieve that number of 3740 ///< component handles. 3741 ); 3742 3743 /////////////////////////////////////////////////////////////////////////////// 3744 /// @brief Get power supply properties 3745 /// 3746 /// @details 3747 /// - The application may call this function from simultaneous threads. 3748 /// - The implementation of this function should be lock-free. 3749 /// 3750 /// @returns 3751 /// - ::ZE_RESULT_SUCCESS 3752 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3753 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3754 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3755 /// + `nullptr == hPsu` 3756 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3757 /// + `nullptr == pProperties` 3758 ZE_APIEXPORT ze_result_t ZE_APICALL 3759 zesPsuGetProperties( 3760 zes_psu_handle_t hPsu, ///< [in] Handle for the component. 3761 zes_psu_properties_t* pProperties ///< [in,out] Will contain the properties of the power supply. 3762 ); 3763 3764 /////////////////////////////////////////////////////////////////////////////// 3765 /// @brief Get current power supply state 3766 /// 3767 /// @details 3768 /// - The application may call this function from simultaneous threads. 3769 /// - The implementation of this function should be lock-free. 3770 /// 3771 /// @returns 3772 /// - ::ZE_RESULT_SUCCESS 3773 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3774 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3775 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3776 /// + `nullptr == hPsu` 3777 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3778 /// + `nullptr == pState` 3779 ZE_APIEXPORT ze_result_t ZE_APICALL 3780 zesPsuGetState( 3781 zes_psu_handle_t hPsu, ///< [in] Handle for the component. 3782 zes_psu_state_t* pState ///< [in,out] Will contain the current state of the power supply. 3783 ); 3784 3785 #if !defined(__GNUC__) 3786 #pragma endregion 3787 #endif 3788 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Firmware management 3789 #if !defined(__GNUC__) 3790 #pragma region ras 3791 #endif 3792 /////////////////////////////////////////////////////////////////////////////// 3793 /// @brief RAS error type 3794 typedef enum _zes_ras_error_type_t 3795 { 3796 ZES_RAS_ERROR_TYPE_CORRECTABLE = 0, ///< Errors were corrected by hardware 3797 ZES_RAS_ERROR_TYPE_UNCORRECTABLE = 1, ///< Error were not corrected 3798 ZES_RAS_ERROR_TYPE_FORCE_UINT32 = 0x7fffffff 3799 3800 } zes_ras_error_type_t; 3801 3802 /////////////////////////////////////////////////////////////////////////////// 3803 /// @brief RAS error categories 3804 typedef enum _zes_ras_error_cat_t 3805 { 3806 ZES_RAS_ERROR_CAT_RESET = 0, ///< The number of accelerator engine resets attempted by the driver 3807 ZES_RAS_ERROR_CAT_PROGRAMMING_ERRORS = 1, ///< The number of hardware exceptions generated by the way workloads have 3808 ///< programmed the hardware 3809 ZES_RAS_ERROR_CAT_DRIVER_ERRORS = 2, ///< The number of low level driver communication errors have occurred 3810 ZES_RAS_ERROR_CAT_COMPUTE_ERRORS = 3, ///< The number of errors that have occurred in the compute accelerator 3811 ///< hardware 3812 ZES_RAS_ERROR_CAT_NON_COMPUTE_ERRORS = 4, ///< The number of errors that have occurred in the fixed-function 3813 ///< accelerator hardware 3814 ZES_RAS_ERROR_CAT_CACHE_ERRORS = 5, ///< The number of errors that have occurred in caches (L1/L3/register 3815 ///< file/shared local memory/sampler) 3816 ZES_RAS_ERROR_CAT_DISPLAY_ERRORS = 6, ///< The number of errors that have occurred in the display 3817 ZES_RAS_ERROR_CAT_FORCE_UINT32 = 0x7fffffff 3818 3819 } zes_ras_error_cat_t; 3820 3821 /////////////////////////////////////////////////////////////////////////////// 3822 #ifndef ZES_MAX_RAS_ERROR_CATEGORY_COUNT 3823 /// @brief The maximum number of categories 3824 #define ZES_MAX_RAS_ERROR_CATEGORY_COUNT 7 3825 #endif // ZES_MAX_RAS_ERROR_CATEGORY_COUNT 3826 3827 /////////////////////////////////////////////////////////////////////////////// 3828 /// @brief RAS properties 3829 typedef struct _zes_ras_properties_t 3830 { 3831 zes_structure_type_t stype; ///< [in] type of this structure 3832 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 3833 zes_ras_error_type_t type; ///< [out] The type of RAS error 3834 ze_bool_t onSubdevice; ///< [out] True if the resource is located on a sub-device; false means 3835 ///< that the resource is on the device of the calling Sysman handle 3836 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 3837 3838 } zes_ras_properties_t; 3839 3840 /////////////////////////////////////////////////////////////////////////////// 3841 /// @brief RAS error details 3842 typedef struct _zes_ras_state_t 3843 { 3844 zes_structure_type_t stype; ///< [in] type of this structure 3845 const void* pNext; ///< [in][optional] pointer to extension-specific structure 3846 uint64_t category[ZES_MAX_RAS_ERROR_CATEGORY_COUNT];///< [in][out] Breakdown of error by category 3847 3848 } zes_ras_state_t; 3849 3850 /////////////////////////////////////////////////////////////////////////////// 3851 /// @brief RAS error configuration - thresholds used for triggering RAS events 3852 /// (::ZES_EVENT_TYPE_FLAG_RAS_CORRECTABLE_ERRORS, 3853 /// ::ZES_EVENT_TYPE_FLAG_RAS_UNCORRECTABLE_ERRORS) 3854 /// 3855 /// @details 3856 /// - The driver maintains a total counter which is updated every time a 3857 /// hardware block covered by the corresponding RAS error set notifies 3858 /// that an error has occurred. When this total count goes above the 3859 /// totalThreshold specified below, a RAS event is triggered. 3860 /// - The driver also maintains a counter for each category of RAS error 3861 /// (see ::zes_ras_state_t for a breakdown). Each time a hardware block of 3862 /// that category notifies that an error has occurred, that corresponding 3863 /// category counter is updated. When it goes above the threshold 3864 /// specified in detailedThresholds, a RAS event is triggered. 3865 typedef struct _zes_ras_config_t 3866 { 3867 zes_structure_type_t stype; ///< [in] type of this structure 3868 const void* pNext; ///< [in][optional] pointer to extension-specific structure 3869 uint64_t totalThreshold; ///< [in,out] If the total RAS errors exceeds this threshold, the event 3870 ///< will be triggered. A value of 0ULL disables triggering the event based 3871 ///< on the total counter. 3872 zes_ras_state_t detailedThresholds; ///< [in,out] If the RAS errors for each category exceed the threshold for 3873 ///< that category, the event will be triggered. A value of 0ULL will 3874 ///< disable an event being triggered for that category. 3875 3876 } zes_ras_config_t; 3877 3878 /////////////////////////////////////////////////////////////////////////////// 3879 /// @brief Get handle of all RAS error sets on a device 3880 /// 3881 /// @details 3882 /// - A RAS error set is a collection of RAS error counters of a given type 3883 /// (correctable/uncorrectable) from hardware blocks contained within a 3884 /// sub-device or within the device. 3885 /// - A device without sub-devices will typically return two handles, one 3886 /// for correctable errors sets and one for uncorrectable error sets. 3887 /// - A device with sub-devices will return RAS error sets for each 3888 /// sub-device and possibly RAS error sets for hardware blocks outside the 3889 /// sub-devices. 3890 /// - If the function completes successfully but pCount is set to 0, RAS 3891 /// features are not available/enabled on this device. 3892 /// - The application may call this function from simultaneous threads. 3893 /// - The implementation of this function should be lock-free. 3894 /// 3895 /// @returns 3896 /// - ::ZE_RESULT_SUCCESS 3897 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3898 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3899 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3900 /// + `nullptr == hDevice` 3901 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3902 /// + `nullptr == pCount` 3903 ZE_APIEXPORT ze_result_t ZE_APICALL 3904 zesDeviceEnumRasErrorSets( 3905 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 3906 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 3907 ///< if count is zero, then the driver shall update the value with the 3908 ///< total number of components of this type that are available. 3909 ///< if count is greater than the number of components of this type that 3910 ///< are available, then the driver shall update the value with the correct 3911 ///< number of components. 3912 zes_ras_handle_t* phRas ///< [in,out][optional][range(0, *pCount)] array of handle of components of 3913 ///< this type. 3914 ///< if count is less than the number of components of this type that are 3915 ///< available, then the driver shall only retrieve that number of 3916 ///< component handles. 3917 ); 3918 3919 /////////////////////////////////////////////////////////////////////////////// 3920 /// @brief Get RAS properties of a given RAS error set - this enables discovery 3921 /// of the type of RAS error set (correctable/uncorrectable) and if 3922 /// located on a sub-device 3923 /// 3924 /// @details 3925 /// - The application may call this function from simultaneous threads. 3926 /// - The implementation of this function should be lock-free. 3927 /// 3928 /// @returns 3929 /// - ::ZE_RESULT_SUCCESS 3930 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3931 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3932 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3933 /// + `nullptr == hRas` 3934 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3935 /// + `nullptr == pProperties` 3936 ZE_APIEXPORT ze_result_t ZE_APICALL 3937 zesRasGetProperties( 3938 zes_ras_handle_t hRas, ///< [in] Handle for the component. 3939 zes_ras_properties_t* pProperties ///< [in,out] Structure describing RAS properties 3940 ); 3941 3942 /////////////////////////////////////////////////////////////////////////////// 3943 /// @brief Get RAS error thresholds that control when RAS events are generated 3944 /// 3945 /// @details 3946 /// - The driver maintains counters for all RAS error sets and error 3947 /// categories. Events are generated when errors occur. The configuration 3948 /// enables setting thresholds to limit when events are sent. 3949 /// - When a particular RAS correctable error counter exceeds the configured 3950 /// threshold, the event ::ZES_EVENT_TYPE_FLAG_RAS_CORRECTABLE_ERRORS will 3951 /// be triggered. 3952 /// - When a particular RAS uncorrectable error counter exceeds the 3953 /// configured threshold, the event 3954 /// ::ZES_EVENT_TYPE_FLAG_RAS_UNCORRECTABLE_ERRORS will be triggered. 3955 /// - The application may call this function from simultaneous threads. 3956 /// - The implementation of this function should be lock-free. 3957 /// 3958 /// @returns 3959 /// - ::ZE_RESULT_SUCCESS 3960 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3961 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3962 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3963 /// + `nullptr == hRas` 3964 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3965 /// + `nullptr == pConfig` 3966 ZE_APIEXPORT ze_result_t ZE_APICALL 3967 zesRasGetConfig( 3968 zes_ras_handle_t hRas, ///< [in] Handle for the component. 3969 zes_ras_config_t* pConfig ///< [in,out] Will be populed with the current RAS configuration - 3970 ///< thresholds used to trigger events 3971 ); 3972 3973 /////////////////////////////////////////////////////////////////////////////// 3974 /// @brief Set RAS error thresholds that control when RAS events are generated 3975 /// 3976 /// @details 3977 /// - The driver maintains counters for all RAS error sets and error 3978 /// categories. Events are generated when errors occur. The configuration 3979 /// enables setting thresholds to limit when events are sent. 3980 /// - When a particular RAS correctable error counter exceeds the specified 3981 /// threshold, the event ::ZES_EVENT_TYPE_FLAG_RAS_CORRECTABLE_ERRORS will 3982 /// be generated. 3983 /// - When a particular RAS uncorrectable error counter exceeds the 3984 /// specified threshold, the event 3985 /// ::ZES_EVENT_TYPE_FLAG_RAS_UNCORRECTABLE_ERRORS will be generated. 3986 /// - Call ::zesRasGetState() and set the clear flag to true to restart 3987 /// event generation once counters have exceeded thresholds. 3988 /// - The application may call this function from simultaneous threads. 3989 /// - The implementation of this function should be lock-free. 3990 /// 3991 /// @returns 3992 /// - ::ZE_RESULT_SUCCESS 3993 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 3994 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 3995 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 3996 /// + `nullptr == hRas` 3997 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 3998 /// + `nullptr == pConfig` 3999 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 4000 /// + Another running process is controlling these settings. 4001 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 4002 /// + Don't have permissions to set thresholds. 4003 ZE_APIEXPORT ze_result_t ZE_APICALL 4004 zesRasSetConfig( 4005 zes_ras_handle_t hRas, ///< [in] Handle for the component. 4006 const zes_ras_config_t* pConfig ///< [in] Change the RAS configuration - thresholds used to trigger events 4007 ); 4008 4009 /////////////////////////////////////////////////////////////////////////////// 4010 /// @brief Get the current value of RAS error counters for a particular error set 4011 /// 4012 /// @details 4013 /// - Clearing errors will affect other threads/applications - the counter 4014 /// values will start from zero. 4015 /// - Clearing errors requires write permissions. 4016 /// - The application may call this function from simultaneous threads. 4017 /// - The implementation of this function should be lock-free. 4018 /// 4019 /// @returns 4020 /// - ::ZE_RESULT_SUCCESS 4021 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4022 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4023 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4024 /// + `nullptr == hRas` 4025 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4026 /// + `nullptr == pState` 4027 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 4028 /// + Don't have permissions to clear error counters. 4029 ZE_APIEXPORT ze_result_t ZE_APICALL 4030 zesRasGetState( 4031 zes_ras_handle_t hRas, ///< [in] Handle for the component. 4032 ze_bool_t clear, ///< [in] Set to 1 to clear the counters of this type 4033 zes_ras_state_t* pState ///< [in,out] Breakdown of where errors have occurred 4034 ); 4035 4036 #if !defined(__GNUC__) 4037 #pragma endregion 4038 #endif 4039 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Scheduler management 4040 #if !defined(__GNUC__) 4041 #pragma region scheduler 4042 #endif 4043 /////////////////////////////////////////////////////////////////////////////// 4044 /// @brief Scheduler mode 4045 typedef enum _zes_sched_mode_t 4046 { 4047 ZES_SCHED_MODE_TIMEOUT = 0, ///< Multiple applications or contexts are submitting work to the hardware. 4048 ///< When higher priority work arrives, the scheduler attempts to pause the 4049 ///< current executing work within some timeout interval, then submits the 4050 ///< other work. 4051 ZES_SCHED_MODE_TIMESLICE = 1, ///< The scheduler attempts to fairly timeslice hardware execution time 4052 ///< between multiple contexts submitting work to the hardware 4053 ///< concurrently. 4054 ZES_SCHED_MODE_EXCLUSIVE = 2, ///< Any application or context can run indefinitely on the hardware 4055 ///< without being preempted or terminated. All pending work for other 4056 ///< contexts must wait until the running context completes with no further 4057 ///< submitted work. 4058 ZES_SCHED_MODE_COMPUTE_UNIT_DEBUG = 3, ///< This is a special mode that must ben enabled when debugging an 4059 ///< application that uses this device e.g. using the Level0 Debug API. It 4060 ///< has the effect of disabling any timeouts on workload execution time 4061 ///< and will change workload scheduling to ensure debug accuracy. 4062 ZES_SCHED_MODE_FORCE_UINT32 = 0x7fffffff 4063 4064 } zes_sched_mode_t; 4065 4066 /////////////////////////////////////////////////////////////////////////////// 4067 /// @brief Properties related to scheduler component 4068 typedef struct _zes_sched_properties_t 4069 { 4070 zes_structure_type_t stype; ///< [in] type of this structure 4071 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 4072 ze_bool_t onSubdevice; ///< [out] True if this resource is located on a sub-device; false means 4073 ///< that the resource is on the device of the calling Sysman handle 4074 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 4075 ze_bool_t canControl; ///< [out] Software can change the scheduler component configuration 4076 ///< assuming the user has permissions. 4077 zes_engine_type_flags_t engines; ///< [out] Bitfield of accelerator engine types that are managed by this 4078 ///< scheduler component. Note that there can be more than one scheduler 4079 ///< component for the same type of accelerator engine. 4080 uint32_t supportedModes; ///< [out] Bitfield of scheduler modes that can be configured for this 4081 ///< scheduler component (bitfield of 1<<::zes_sched_mode_t). 4082 4083 } zes_sched_properties_t; 4084 4085 /////////////////////////////////////////////////////////////////////////////// 4086 #ifndef ZES_SCHED_WATCHDOG_DISABLE 4087 /// @brief Disable forward progress guard timeout. 4088 #define ZES_SCHED_WATCHDOG_DISABLE (~(0ULL)) 4089 #endif // ZES_SCHED_WATCHDOG_DISABLE 4090 4091 /////////////////////////////////////////////////////////////////////////////// 4092 /// @brief Configuration for timeout scheduler mode (::ZES_SCHED_MODE_TIMEOUT) 4093 typedef struct _zes_sched_timeout_properties_t 4094 { 4095 zes_structure_type_t stype; ///< [in] type of this structure 4096 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 4097 uint64_t watchdogTimeout; ///< [in,out] The maximum time in microseconds that the scheduler will wait 4098 ///< for a batch of work submitted to a hardware engine to complete or to 4099 ///< be preempted so as to run another context. 4100 ///< If this time is exceeded, the hardware engine is reset and the context terminated. 4101 ///< If set to ::ZES_SCHED_WATCHDOG_DISABLE, a running workload can run as 4102 ///< long as it wants without being terminated, but preemption attempts to 4103 ///< run other contexts are permitted but not enforced. 4104 4105 } zes_sched_timeout_properties_t; 4106 4107 /////////////////////////////////////////////////////////////////////////////// 4108 /// @brief Configuration for timeslice scheduler mode 4109 /// (::ZES_SCHED_MODE_TIMESLICE) 4110 typedef struct _zes_sched_timeslice_properties_t 4111 { 4112 zes_structure_type_t stype; ///< [in] type of this structure 4113 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 4114 uint64_t interval; ///< [in,out] The average interval in microseconds that a submission for a 4115 ///< context will run on a hardware engine before being preempted out to 4116 ///< run a pending submission for another context. 4117 uint64_t yieldTimeout; ///< [in,out] The maximum time in microseconds that the scheduler will wait 4118 ///< to preempt a workload running on an engine before deciding to reset 4119 ///< the hardware engine and terminating the associated context. 4120 4121 } zes_sched_timeslice_properties_t; 4122 4123 /////////////////////////////////////////////////////////////////////////////// 4124 /// @brief Returns handles to scheduler components. 4125 /// 4126 /// @details 4127 /// - Each scheduler component manages the distribution of work across one 4128 /// or more accelerator engines. 4129 /// - If an application wishes to change the scheduler behavior for all 4130 /// accelerator engines of a specific type (e.g. compute), it should 4131 /// select all the handles where the structure member 4132 /// ::zes_sched_properties_t.engines contains that type. 4133 /// - The application may call this function from simultaneous threads. 4134 /// - The implementation of this function should be lock-free. 4135 /// 4136 /// @returns 4137 /// - ::ZE_RESULT_SUCCESS 4138 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4139 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4140 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4141 /// + `nullptr == hDevice` 4142 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4143 /// + `nullptr == pCount` 4144 ZE_APIEXPORT ze_result_t ZE_APICALL 4145 zesDeviceEnumSchedulers( 4146 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 4147 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 4148 ///< if count is zero, then the driver shall update the value with the 4149 ///< total number of components of this type that are available. 4150 ///< if count is greater than the number of components of this type that 4151 ///< are available, then the driver shall update the value with the correct 4152 ///< number of components. 4153 zes_sched_handle_t* phScheduler ///< [in,out][optional][range(0, *pCount)] array of handle of components of 4154 ///< this type. 4155 ///< if count is less than the number of components of this type that are 4156 ///< available, then the driver shall only retrieve that number of 4157 ///< component handles. 4158 ); 4159 4160 /////////////////////////////////////////////////////////////////////////////// 4161 /// @brief Get properties related to a scheduler component 4162 /// 4163 /// @details 4164 /// - The application may call this function from simultaneous threads. 4165 /// - The implementation of this function should be lock-free. 4166 /// 4167 /// @returns 4168 /// - ::ZE_RESULT_SUCCESS 4169 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4170 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4171 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4172 /// + `nullptr == hScheduler` 4173 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4174 /// + `nullptr == pProperties` 4175 ZE_APIEXPORT ze_result_t ZE_APICALL 4176 zesSchedulerGetProperties( 4177 zes_sched_handle_t hScheduler, ///< [in] Handle for the component. 4178 zes_sched_properties_t* pProperties ///< [in,out] Structure that will contain property data. 4179 ); 4180 4181 /////////////////////////////////////////////////////////////////////////////// 4182 /// @brief Get current scheduling mode in effect on a scheduler component. 4183 /// 4184 /// @details 4185 /// - The application may call this function from simultaneous threads. 4186 /// - The implementation of this function should be lock-free. 4187 /// 4188 /// @returns 4189 /// - ::ZE_RESULT_SUCCESS 4190 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4191 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4192 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4193 /// + `nullptr == hScheduler` 4194 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4195 /// + `nullptr == pMode` 4196 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 4197 /// + This scheduler component does not support scheduler modes. 4198 ZE_APIEXPORT ze_result_t ZE_APICALL 4199 zesSchedulerGetCurrentMode( 4200 zes_sched_handle_t hScheduler, ///< [in] Sysman handle for the component. 4201 zes_sched_mode_t* pMode ///< [in,out] Will contain the current scheduler mode. 4202 ); 4203 4204 /////////////////////////////////////////////////////////////////////////////// 4205 /// @brief Get scheduler config for mode ::ZES_SCHED_MODE_TIMEOUT 4206 /// 4207 /// @details 4208 /// - The application may call this function from simultaneous threads. 4209 /// - The implementation of this function should be lock-free. 4210 /// 4211 /// @returns 4212 /// - ::ZE_RESULT_SUCCESS 4213 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4214 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4215 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4216 /// + `nullptr == hScheduler` 4217 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4218 /// + `nullptr == pConfig` 4219 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 4220 /// + This scheduler component does not support scheduler modes. 4221 ZE_APIEXPORT ze_result_t ZE_APICALL 4222 zesSchedulerGetTimeoutModeProperties( 4223 zes_sched_handle_t hScheduler, ///< [in] Sysman handle for the component. 4224 ze_bool_t getDefaults, ///< [in] If TRUE, the driver will return the system default properties for 4225 ///< this mode, otherwise it will return the current properties. 4226 zes_sched_timeout_properties_t* pConfig ///< [in,out] Will contain the current parameters for this mode. 4227 ); 4228 4229 /////////////////////////////////////////////////////////////////////////////// 4230 /// @brief Get scheduler config for mode ::ZES_SCHED_MODE_TIMESLICE 4231 /// 4232 /// @details 4233 /// - The application may call this function from simultaneous threads. 4234 /// - The implementation of this function should be lock-free. 4235 /// 4236 /// @returns 4237 /// - ::ZE_RESULT_SUCCESS 4238 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4239 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4240 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4241 /// + `nullptr == hScheduler` 4242 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4243 /// + `nullptr == pConfig` 4244 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 4245 /// + This scheduler component does not support scheduler modes. 4246 ZE_APIEXPORT ze_result_t ZE_APICALL 4247 zesSchedulerGetTimesliceModeProperties( 4248 zes_sched_handle_t hScheduler, ///< [in] Sysman handle for the component. 4249 ze_bool_t getDefaults, ///< [in] If TRUE, the driver will return the system default properties for 4250 ///< this mode, otherwise it will return the current properties. 4251 zes_sched_timeslice_properties_t* pConfig ///< [in,out] Will contain the current parameters for this mode. 4252 ); 4253 4254 /////////////////////////////////////////////////////////////////////////////// 4255 /// @brief Change scheduler mode to ::ZES_SCHED_MODE_TIMEOUT or update scheduler 4256 /// mode parameters if already running in this mode. 4257 /// 4258 /// @details 4259 /// - This mode is optimized for multiple applications or contexts 4260 /// submitting work to the hardware. When higher priority work arrives, 4261 /// the scheduler attempts to pause the current executing work within some 4262 /// timeout interval, then submits the other work. 4263 /// - The application may call this function from simultaneous threads. 4264 /// - The implementation of this function should be lock-free. 4265 /// 4266 /// @returns 4267 /// - ::ZE_RESULT_SUCCESS 4268 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4269 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4270 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4271 /// + `nullptr == hScheduler` 4272 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4273 /// + `nullptr == pProperties` 4274 /// + `nullptr == pNeedReload` 4275 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 4276 /// + This scheduler component does not support scheduler modes. 4277 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 4278 /// + User does not have permissions to make this modification. 4279 ZE_APIEXPORT ze_result_t ZE_APICALL 4280 zesSchedulerSetTimeoutMode( 4281 zes_sched_handle_t hScheduler, ///< [in] Sysman handle for the component. 4282 zes_sched_timeout_properties_t* pProperties, ///< [in] The properties to use when configurating this mode. 4283 ze_bool_t* pNeedReload ///< [in,out] Will be set to TRUE if a device driver reload is needed to 4284 ///< apply the new scheduler mode. 4285 ); 4286 4287 /////////////////////////////////////////////////////////////////////////////// 4288 /// @brief Change scheduler mode to ::ZES_SCHED_MODE_TIMESLICE or update 4289 /// scheduler mode parameters if already running in this mode. 4290 /// 4291 /// @details 4292 /// - This mode is optimized to provide fair sharing of hardware execution 4293 /// time between multiple contexts submitting work to the hardware 4294 /// concurrently. 4295 /// - The application may call this function from simultaneous threads. 4296 /// - The implementation of this function should be lock-free. 4297 /// 4298 /// @returns 4299 /// - ::ZE_RESULT_SUCCESS 4300 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4301 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4302 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4303 /// + `nullptr == hScheduler` 4304 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4305 /// + `nullptr == pProperties` 4306 /// + `nullptr == pNeedReload` 4307 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 4308 /// + This scheduler component does not support scheduler modes. 4309 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 4310 /// + User does not have permissions to make this modification. 4311 ZE_APIEXPORT ze_result_t ZE_APICALL 4312 zesSchedulerSetTimesliceMode( 4313 zes_sched_handle_t hScheduler, ///< [in] Sysman handle for the component. 4314 zes_sched_timeslice_properties_t* pProperties, ///< [in] The properties to use when configurating this mode. 4315 ze_bool_t* pNeedReload ///< [in,out] Will be set to TRUE if a device driver reload is needed to 4316 ///< apply the new scheduler mode. 4317 ); 4318 4319 /////////////////////////////////////////////////////////////////////////////// 4320 /// @brief Change scheduler mode to ::ZES_SCHED_MODE_EXCLUSIVE 4321 /// 4322 /// @details 4323 /// - This mode is optimized for single application/context use-cases. It 4324 /// permits a context to run indefinitely on the hardware without being 4325 /// preempted or terminated. All pending work for other contexts must wait 4326 /// until the running context completes with no further submitted work. 4327 /// - The application may call this function from simultaneous threads. 4328 /// - The implementation of this function should be lock-free. 4329 /// 4330 /// @returns 4331 /// - ::ZE_RESULT_SUCCESS 4332 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4333 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4334 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4335 /// + `nullptr == hScheduler` 4336 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4337 /// + `nullptr == pNeedReload` 4338 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 4339 /// + This scheduler component does not support scheduler modes. 4340 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 4341 /// + User does not have permissions to make this modification. 4342 ZE_APIEXPORT ze_result_t ZE_APICALL 4343 zesSchedulerSetExclusiveMode( 4344 zes_sched_handle_t hScheduler, ///< [in] Sysman handle for the component. 4345 ze_bool_t* pNeedReload ///< [in,out] Will be set to TRUE if a device driver reload is needed to 4346 ///< apply the new scheduler mode. 4347 ); 4348 4349 /////////////////////////////////////////////////////////////////////////////// 4350 /// @brief Change scheduler mode to ::ZES_SCHED_MODE_COMPUTE_UNIT_DEBUG 4351 /// 4352 /// @details 4353 /// - This is a special mode that must ben enabled when debugging an 4354 /// application that uses this device e.g. using the Level0 Debug API. 4355 /// - It ensures that only one command queue can execute work on the 4356 /// hardware at a given time. Work is permitted to run as long as needed 4357 /// without enforcing any scheduler fairness policies. 4358 /// - The application may call this function from simultaneous threads. 4359 /// - The implementation of this function should be lock-free. 4360 /// 4361 /// @returns 4362 /// - ::ZE_RESULT_SUCCESS 4363 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4364 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4365 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4366 /// + `nullptr == hScheduler` 4367 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4368 /// + `nullptr == pNeedReload` 4369 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 4370 /// + This scheduler component does not support scheduler modes. 4371 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 4372 /// + User does not have permissions to make this modification. 4373 ZE_APIEXPORT ze_result_t ZE_APICALL 4374 zesSchedulerSetComputeUnitDebugMode( 4375 zes_sched_handle_t hScheduler, ///< [in] Sysman handle for the component. 4376 ze_bool_t* pNeedReload ///< [in,out] Will be set to TRUE if a device driver reload is needed to 4377 ///< apply the new scheduler mode. 4378 ); 4379 4380 #if !defined(__GNUC__) 4381 #pragma endregion 4382 #endif 4383 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Standby domains 4384 #if !defined(__GNUC__) 4385 #pragma region standby 4386 #endif 4387 /////////////////////////////////////////////////////////////////////////////// 4388 /// @brief Standby hardware components 4389 typedef enum _zes_standby_type_t 4390 { 4391 ZES_STANDBY_TYPE_GLOBAL = 0, ///< Control the overall standby policy of the device/sub-device 4392 ZES_STANDBY_TYPE_FORCE_UINT32 = 0x7fffffff 4393 4394 } zes_standby_type_t; 4395 4396 /////////////////////////////////////////////////////////////////////////////// 4397 /// @brief Standby hardware component properties 4398 typedef struct _zes_standby_properties_t 4399 { 4400 zes_structure_type_t stype; ///< [in] type of this structure 4401 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 4402 zes_standby_type_t type; ///< [out] Which standby hardware component this controls 4403 ze_bool_t onSubdevice; ///< [out] True if the resource is located on a sub-device; false means 4404 ///< that the resource is on the device of the calling Sysman handle 4405 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 4406 4407 } zes_standby_properties_t; 4408 4409 /////////////////////////////////////////////////////////////////////////////// 4410 /// @brief Standby promotion modes 4411 typedef enum _zes_standby_promo_mode_t 4412 { 4413 ZES_STANDBY_PROMO_MODE_DEFAULT = 0, ///< Best compromise between performance and energy savings. 4414 ZES_STANDBY_PROMO_MODE_NEVER = 1, ///< The device/component will never shutdown. This can improve performance 4415 ///< but uses more energy. 4416 ZES_STANDBY_PROMO_MODE_FORCE_UINT32 = 0x7fffffff 4417 4418 } zes_standby_promo_mode_t; 4419 4420 /////////////////////////////////////////////////////////////////////////////// 4421 /// @brief Get handle of standby controls 4422 /// 4423 /// @details 4424 /// - The application may call this function from simultaneous threads. 4425 /// - The implementation of this function should be lock-free. 4426 /// 4427 /// @returns 4428 /// - ::ZE_RESULT_SUCCESS 4429 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4430 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4431 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4432 /// + `nullptr == hDevice` 4433 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4434 /// + `nullptr == pCount` 4435 ZE_APIEXPORT ze_result_t ZE_APICALL 4436 zesDeviceEnumStandbyDomains( 4437 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 4438 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 4439 ///< if count is zero, then the driver shall update the value with the 4440 ///< total number of components of this type that are available. 4441 ///< if count is greater than the number of components of this type that 4442 ///< are available, then the driver shall update the value with the correct 4443 ///< number of components. 4444 zes_standby_handle_t* phStandby ///< [in,out][optional][range(0, *pCount)] array of handle of components of 4445 ///< this type. 4446 ///< if count is less than the number of components of this type that are 4447 ///< available, then the driver shall only retrieve that number of 4448 ///< component handles. 4449 ); 4450 4451 /////////////////////////////////////////////////////////////////////////////// 4452 /// @brief Get standby hardware component properties 4453 /// 4454 /// @details 4455 /// - The application may call this function from simultaneous threads. 4456 /// - The implementation of this function should be lock-free. 4457 /// 4458 /// @returns 4459 /// - ::ZE_RESULT_SUCCESS 4460 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4461 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4462 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4463 /// + `nullptr == hStandby` 4464 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4465 /// + `nullptr == pProperties` 4466 ZE_APIEXPORT ze_result_t ZE_APICALL 4467 zesStandbyGetProperties( 4468 zes_standby_handle_t hStandby, ///< [in] Handle for the component. 4469 zes_standby_properties_t* pProperties ///< [in,out] Will contain the standby hardware properties. 4470 ); 4471 4472 /////////////////////////////////////////////////////////////////////////////// 4473 /// @brief Get the current standby promotion mode 4474 /// 4475 /// @details 4476 /// - The application may call this function from simultaneous threads. 4477 /// - The implementation of this function should be lock-free. 4478 /// 4479 /// @returns 4480 /// - ::ZE_RESULT_SUCCESS 4481 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4482 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4483 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4484 /// + `nullptr == hStandby` 4485 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4486 /// + `nullptr == pMode` 4487 ZE_APIEXPORT ze_result_t ZE_APICALL 4488 zesStandbyGetMode( 4489 zes_standby_handle_t hStandby, ///< [in] Handle for the component. 4490 zes_standby_promo_mode_t* pMode ///< [in,out] Will contain the current standby mode. 4491 ); 4492 4493 /////////////////////////////////////////////////////////////////////////////// 4494 /// @brief Set standby promotion mode 4495 /// 4496 /// @details 4497 /// - The application may call this function from simultaneous threads. 4498 /// - The implementation of this function should be lock-free. 4499 /// 4500 /// @returns 4501 /// - ::ZE_RESULT_SUCCESS 4502 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4503 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4504 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4505 /// + `nullptr == hStandby` 4506 /// - ::ZE_RESULT_ERROR_INVALID_ENUMERATION 4507 /// + `::ZES_STANDBY_PROMO_MODE_NEVER < mode` 4508 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 4509 /// + User does not have permissions to make these modifications. 4510 ZE_APIEXPORT ze_result_t ZE_APICALL 4511 zesStandbySetMode( 4512 zes_standby_handle_t hStandby, ///< [in] Handle for the component. 4513 zes_standby_promo_mode_t mode ///< [in] New standby mode. 4514 ); 4515 4516 #if !defined(__GNUC__) 4517 #pragma endregion 4518 #endif 4519 // Intel 'oneAPI' Level-Zero Tool APIs for System Resource Management (Sysman) - Firmware management 4520 #if !defined(__GNUC__) 4521 #pragma region temperature 4522 #endif 4523 /////////////////////////////////////////////////////////////////////////////// 4524 /// @brief Temperature sensors 4525 typedef enum _zes_temp_sensors_t 4526 { 4527 ZES_TEMP_SENSORS_GLOBAL = 0, ///< The maximum temperature across all device sensors 4528 ZES_TEMP_SENSORS_GPU = 1, ///< The maximum temperature across all sensors in the GPU 4529 ZES_TEMP_SENSORS_MEMORY = 2, ///< The maximum temperature across all sensors in the local memory 4530 ZES_TEMP_SENSORS_GLOBAL_MIN = 3, ///< The minimum temperature across all device sensors 4531 ZES_TEMP_SENSORS_GPU_MIN = 4, ///< The minimum temperature across all sensors in the GPU 4532 ZES_TEMP_SENSORS_MEMORY_MIN = 5, ///< The minimum temperature across all sensors in the local device memory 4533 ZES_TEMP_SENSORS_FORCE_UINT32 = 0x7fffffff 4534 4535 } zes_temp_sensors_t; 4536 4537 /////////////////////////////////////////////////////////////////////////////// 4538 /// @brief Temperature sensor properties 4539 typedef struct _zes_temp_properties_t 4540 { 4541 zes_structure_type_t stype; ///< [in] type of this structure 4542 void* pNext; ///< [in,out][optional] pointer to extension-specific structure 4543 zes_temp_sensors_t type; ///< [out] Which part of the device the temperature sensor measures 4544 ze_bool_t onSubdevice; ///< [out] True if the resource is located on a sub-device; false means 4545 ///< that the resource is on the device of the calling Sysman handle 4546 uint32_t subdeviceId; ///< [out] If onSubdevice is true, this gives the ID of the sub-device 4547 double maxTemperature; ///< [out] Will contain the maximum temperature for the specific device in 4548 ///< degrees Celsius. 4549 ze_bool_t isCriticalTempSupported; ///< [out] Indicates if the critical temperature event 4550 ///< ::ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL is supported 4551 ze_bool_t isThreshold1Supported; ///< [out] Indicates if the temperature threshold 1 event 4552 ///< ::ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1 is supported 4553 ze_bool_t isThreshold2Supported; ///< [out] Indicates if the temperature threshold 2 event 4554 ///< ::ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2 is supported 4555 4556 } zes_temp_properties_t; 4557 4558 /////////////////////////////////////////////////////////////////////////////// 4559 /// @brief Temperature sensor threshold 4560 typedef struct _zes_temp_threshold_t 4561 { 4562 ze_bool_t enableLowToHigh; ///< [in,out] Trigger an event when the temperature crosses from below the 4563 ///< threshold to above. 4564 ze_bool_t enableHighToLow; ///< [in,out] Trigger an event when the temperature crosses from above the 4565 ///< threshold to below. 4566 double threshold; ///< [in,out] The threshold in degrees Celsius. 4567 4568 } zes_temp_threshold_t; 4569 4570 /////////////////////////////////////////////////////////////////////////////// 4571 /// @brief Temperature configuration - which events should be triggered and the 4572 /// trigger conditions. 4573 typedef struct _zes_temp_config_t 4574 { 4575 zes_structure_type_t stype; ///< [in] type of this structure 4576 const void* pNext; ///< [in][optional] pointer to extension-specific structure 4577 ze_bool_t enableCritical; ///< [in,out] Indicates if event ::ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL should 4578 ///< be triggered by the driver. 4579 zes_temp_threshold_t threshold1; ///< [in,out] Configuration controlling if and when event 4580 ///< ::ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1 should be triggered by the 4581 ///< driver. 4582 zes_temp_threshold_t threshold2; ///< [in,out] Configuration controlling if and when event 4583 ///< ::ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2 should be triggered by the 4584 ///< driver. 4585 4586 } zes_temp_config_t; 4587 4588 /////////////////////////////////////////////////////////////////////////////// 4589 /// @brief Get handle of temperature sensors 4590 /// 4591 /// @details 4592 /// - The application may call this function from simultaneous threads. 4593 /// - The implementation of this function should be lock-free. 4594 /// 4595 /// @returns 4596 /// - ::ZE_RESULT_SUCCESS 4597 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4598 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4599 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4600 /// + `nullptr == hDevice` 4601 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4602 /// + `nullptr == pCount` 4603 ZE_APIEXPORT ze_result_t ZE_APICALL 4604 zesDeviceEnumTemperatureSensors( 4605 zes_device_handle_t hDevice, ///< [in] Sysman handle of the device. 4606 uint32_t* pCount, ///< [in,out] pointer to the number of components of this type. 4607 ///< if count is zero, then the driver shall update the value with the 4608 ///< total number of components of this type that are available. 4609 ///< if count is greater than the number of components of this type that 4610 ///< are available, then the driver shall update the value with the correct 4611 ///< number of components. 4612 zes_temp_handle_t* phTemperature ///< [in,out][optional][range(0, *pCount)] array of handle of components of 4613 ///< this type. 4614 ///< if count is less than the number of components of this type that are 4615 ///< available, then the driver shall only retrieve that number of 4616 ///< component handles. 4617 ); 4618 4619 /////////////////////////////////////////////////////////////////////////////// 4620 /// @brief Get temperature sensor properties 4621 /// 4622 /// @details 4623 /// - The application may call this function from simultaneous threads. 4624 /// - The implementation of this function should be lock-free. 4625 /// 4626 /// @returns 4627 /// - ::ZE_RESULT_SUCCESS 4628 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4629 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4630 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4631 /// + `nullptr == hTemperature` 4632 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4633 /// + `nullptr == pProperties` 4634 ZE_APIEXPORT ze_result_t ZE_APICALL 4635 zesTemperatureGetProperties( 4636 zes_temp_handle_t hTemperature, ///< [in] Handle for the component. 4637 zes_temp_properties_t* pProperties ///< [in,out] Will contain the temperature sensor properties. 4638 ); 4639 4640 /////////////////////////////////////////////////////////////////////////////// 4641 /// @brief Get temperature configuration for this sensor - which events are 4642 /// triggered and the trigger conditions 4643 /// 4644 /// @details 4645 /// - The application may call this function from simultaneous threads. 4646 /// - The implementation of this function should be lock-free. 4647 /// 4648 /// @returns 4649 /// - ::ZE_RESULT_SUCCESS 4650 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4651 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4652 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4653 /// + `nullptr == hTemperature` 4654 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4655 /// + `nullptr == pConfig` 4656 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 4657 /// + Temperature thresholds are not supported on this temperature sensor. Generally this is only supported for temperature sensor ::ZES_TEMP_SENSORS_GLOBAL 4658 /// + One or both of the thresholds is not supported - check ::zes_temp_properties_t.isThreshold1Supported and ::zes_temp_properties_t.isThreshold2Supported 4659 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 4660 /// + User does not have permissions to request this feature. 4661 ZE_APIEXPORT ze_result_t ZE_APICALL 4662 zesTemperatureGetConfig( 4663 zes_temp_handle_t hTemperature, ///< [in] Handle for the component. 4664 zes_temp_config_t* pConfig ///< [in,out] Returns current configuration. 4665 ); 4666 4667 /////////////////////////////////////////////////////////////////////////////// 4668 /// @brief Set temperature configuration for this sensor - indicates which events 4669 /// are triggered and the trigger conditions 4670 /// 4671 /// @details 4672 /// - Events ::ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL will be triggered when 4673 /// temperature reaches the critical range. Use the function 4674 /// ::zesDeviceEventRegister() to start receiving this event. 4675 /// - Events ::ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1 and 4676 /// ::ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2 will be generated when 4677 /// temperature cross the thresholds set using this function. Use the 4678 /// function ::zesDeviceEventRegister() to start receiving these events. 4679 /// - Only one running process can set the temperature configuration at a 4680 /// time. If another process attempts to change the configuration, the 4681 /// error ::ZE_RESULT_ERROR_NOT_AVAILABLE will be returned. The function 4682 /// ::zesTemperatureGetConfig() will return the process ID currently 4683 /// controlling these settings. 4684 /// - The application may call this function from simultaneous threads. 4685 /// - The implementation of this function should be lock-free. 4686 /// 4687 /// @returns 4688 /// - ::ZE_RESULT_SUCCESS 4689 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4690 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4691 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4692 /// + `nullptr == hTemperature` 4693 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4694 /// + `nullptr == pConfig` 4695 /// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE 4696 /// + Temperature thresholds are not supported on this temperature sensor. Generally they are only supported for temperature sensor ::ZES_TEMP_SENSORS_GLOBAL 4697 /// + Enabling the critical temperature event is not supported - check ::zes_temp_properties_t.isCriticalTempSupported 4698 /// + One or both of the thresholds is not supported - check ::zes_temp_properties_t.isThreshold1Supported and ::zes_temp_properties_t.isThreshold2Supported 4699 /// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS 4700 /// + User does not have permissions to request this feature. 4701 /// - ::ZE_RESULT_ERROR_NOT_AVAILABLE 4702 /// + Another running process is controlling these settings. 4703 /// - ::ZE_RESULT_ERROR_INVALID_ARGUMENT 4704 /// + One or both the thresholds is above TjMax (see ::zesFrequencyOcGetTjMax()). Temperature thresholds must be below this value. 4705 ZE_APIEXPORT ze_result_t ZE_APICALL 4706 zesTemperatureSetConfig( 4707 zes_temp_handle_t hTemperature, ///< [in] Handle for the component. 4708 const zes_temp_config_t* pConfig ///< [in] New configuration. 4709 ); 4710 4711 /////////////////////////////////////////////////////////////////////////////// 4712 /// @brief Get the temperature from a specified sensor 4713 /// 4714 /// @details 4715 /// - The application may call this function from simultaneous threads. 4716 /// - The implementation of this function should be lock-free. 4717 /// 4718 /// @returns 4719 /// - ::ZE_RESULT_SUCCESS 4720 /// - ::ZE_RESULT_ERROR_UNINITIALIZED 4721 /// - ::ZE_RESULT_ERROR_DEVICE_LOST 4722 /// - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE 4723 /// + `nullptr == hTemperature` 4724 /// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER 4725 /// + `nullptr == pTemperature` 4726 ZE_APIEXPORT ze_result_t ZE_APICALL 4727 zesTemperatureGetState( 4728 zes_temp_handle_t hTemperature, ///< [in] Handle for the component. 4729 double* pTemperature ///< [in,out] Will contain the temperature read from the specified sensor 4730 ///< in degrees Celsius. 4731 ); 4732 4733 #if !defined(__GNUC__) 4734 #pragma endregion 4735 #endif 4736 4737 #if defined(__cplusplus) 4738 } // extern "C" 4739 #endif 4740 4741 #endif // _ZES_API_H