| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
=============================================================== |
| 4 |
Intel(R) Dynamic Platform and Thermal Framework Sysfs Interface |
| 5 |
=============================================================== |
| 6 |
|
| 7 |
:Copyright: © 2022 Intel Corporation |
| 8 |
|
| 9 |
:Author: Srinivas Pandruvada <[email protected]> |
| 10 |
|
| 11 |
Introduction |
| 12 |
------------ |
| 13 |
|
| 14 |
Intel(R) Dynamic Platform and Thermal Framework (DPTF) is a platform |
| 15 |
level hardware/software solution for power and thermal management. |
| 16 |
|
| 17 |
As a container for multiple power/thermal technologies, DPTF provides |
| 18 |
a coordinated approach for different policies to effect the hardware |
| 19 |
state of a system. |
| 20 |
|
| 21 |
Since it is a platform level framework, this has several components. |
| 22 |
Some parts of the technology is implemented in the firmware and uses |
| 23 |
ACPI and PCI devices to expose various features for monitoring and |
| 24 |
control. Linux has a set of kernel drivers exposing hardware interface |
| 25 |
to user space. This allows user space thermal solutions like |
| 26 |
"Linux Thermal Daemon" to read platform specific thermal and power |
| 27 |
tables to deliver adequate performance while keeping the system under |
| 28 |
thermal limits. |
| 29 |
|
| 30 |
DPTF ACPI Drivers interface |
| 31 |
---------------------------- |
| 32 |
|
| 33 |
:file:`/sys/bus/platform/devices/<N>/uuids`, where <N> |
| 34 |
=INT3400|INTC1040|INTC1041|INTC10A0 |
| 35 |
|
| 36 |
``available_uuids`` (RO) |
| 37 |
A set of UUIDs strings presenting available policies |
| 38 |
which should be notified to the firmware when the |
| 39 |
user space can support those policies. |
| 40 |
|
| 41 |
UUID strings: |
| 42 |
|
| 43 |
"42A441D6-AE6A-462b-A84B-4A8CE79027D3" : Passive 1 |
| 44 |
|
| 45 |
"3A95C389-E4B8-4629-A526-C52C88626BAE" : Active |
| 46 |
|
| 47 |
"97C68AE7-15FA-499c-B8C9-5DA81D606E0A" : Critical |
| 48 |
|
| 49 |
"63BE270F-1C11-48FD-A6F7-3AF253FF3E2D" : Adaptive performance |
| 50 |
|
| 51 |
"5349962F-71E6-431D-9AE8-0A635B710AEE" : Emergency call |
| 52 |
|
| 53 |
"9E04115A-AE87-4D1C-9500-0F3E340BFE75" : Passive 2 |
| 54 |
|
| 55 |
"F5A35014-C209-46A4-993A-EB56DE7530A1" : Power Boss |
| 56 |
|
| 57 |
"6ED722A7-9240-48A5-B479-31EEF723D7CF" : Virtual Sensor |
| 58 |
|
| 59 |
"16CAF1B7-DD38-40ED-B1C1-1B8A1913D531" : Cooling mode |
| 60 |
|
| 61 |
"BE84BABF-C4D4-403D-B495-3128FD44dAC1" : HDC |
| 62 |
|
| 63 |
``current_uuid`` (RW) |
| 64 |
User space can write strings from available UUIDs, one at a |
| 65 |
time. |
| 66 |
|
| 67 |
:file:`/sys/bus/platform/devices/<N>/`, where <N> |
| 68 |
=INT3400|INTC1040|INTC1041|INTC10A0 |
| 69 |
|
| 70 |
``imok`` (WO) |
| 71 |
User space daemon write 1 to respond to firmware event |
| 72 |
for sending keep alive notification. User space receives |
| 73 |
THERMAL_EVENT_KEEP_ALIVE kobject uevent notification when |
| 74 |
firmware calls for user space to respond with imok ACPI |
| 75 |
method. |
| 76 |
|
| 77 |
``odvp*`` (RO) |
| 78 |
Firmware thermal status variable values. Thermal tables |
| 79 |
calls for different processing based on these variable |
| 80 |
values. |
| 81 |
|
| 82 |
``data_vault`` (RO) |
| 83 |
Binary thermal table. Refer to |
| 84 |
https:/github.com/intel/thermal_daemon for decoding |
| 85 |
thermal table. |
| 86 |
|
| 87 |
``production_mode`` (RO) |
| 88 |
When different from zero, manufacturer locked thermal configuration |
| 89 |
from further changes. |
| 90 |
|
| 91 |
ACPI Thermal Relationship table interface |
| 92 |
------------------------------------------ |
| 93 |
|
| 94 |
:file:`/dev/acpi_thermal_rel` |
| 95 |
|
| 96 |
This device provides IOCTL interface to read standard ACPI |
| 97 |
thermal relationship tables via ACPI methods _TRT and _ART. |
| 98 |
These IOCTLs are defined in |
| 99 |
drivers/thermal/intel/int340x_thermal/acpi_thermal_rel.h |
| 100 |
|
| 101 |
IOCTLs: |
| 102 |
|
| 103 |
ACPI_THERMAL_GET_TRT_LEN: Get length of TRT table |
| 104 |
|
| 105 |
ACPI_THERMAL_GET_ART_LEN: Get length of ART table |
| 106 |
|
| 107 |
ACPI_THERMAL_GET_TRT_COUNT: Number of records in TRT table |
| 108 |
|
| 109 |
ACPI_THERMAL_GET_ART_COUNT: Number of records in ART table |
| 110 |
|
| 111 |
ACPI_THERMAL_GET_TRT: Read binary TRT table, length to read is |
| 112 |
provided via argument to ioctl(). |
| 113 |
|
| 114 |
ACPI_THERMAL_GET_ART: Read binary ART table, length to read is |
| 115 |
provided via argument to ioctl(). |
| 116 |
|
| 117 |
DPTF ACPI Sensor drivers |
| 118 |
------------------------- |
| 119 |
|
| 120 |
DPTF Sensor drivers are presented as standard thermal sysfs thermal_zone. |
| 121 |
|
| 122 |
|
| 123 |
DPTF ACPI Cooling drivers |
| 124 |
-------------------------- |
| 125 |
|
| 126 |
DPTF cooling drivers are presented as standard thermal sysfs cooling_device. |
| 127 |
|
| 128 |
|
| 129 |
DPTF Processor thermal PCI Driver interface |
| 130 |
-------------------------------------------- |
| 131 |
|
| 132 |
:file:`/sys/bus/pci/devices/0000\:00\:04.0/power_limits/` |
| 133 |
|
| 134 |
Refer to Documentation/power/powercap/powercap.rst for powercap |
| 135 |
ABI. |
| 136 |
|
| 137 |
``power_limit_0_max_uw`` (RO) |
| 138 |
Maximum powercap sysfs constraint_0_power_limit_uw for Intel RAPL |
| 139 |
|
| 140 |
``power_limit_0_step_uw`` (RO) |
| 141 |
Power limit increment/decrements for Intel RAPL constraint 0 power limit |
| 142 |
|
| 143 |
``power_limit_0_min_uw`` (RO) |
| 144 |
Minimum powercap sysfs constraint_0_power_limit_uw for Intel RAPL |
| 145 |
|
| 146 |
``power_limit_0_tmin_us`` (RO) |
| 147 |
Minimum powercap sysfs constraint_0_time_window_us for Intel RAPL |
| 148 |
|
| 149 |
``power_limit_0_tmax_us`` (RO) |
| 150 |
Maximum powercap sysfs constraint_0_time_window_us for Intel RAPL |
| 151 |
|
| 152 |
``power_limit_1_max_uw`` (RO) |
| 153 |
Maximum powercap sysfs constraint_1_power_limit_uw for Intel RAPL |
| 154 |
|
| 155 |
``power_limit_1_step_uw`` (RO) |
| 156 |
Power limit increment/decrements for Intel RAPL constraint 1 power limit |
| 157 |
|
| 158 |
``power_limit_1_min_uw`` (RO) |
| 159 |
Minimum powercap sysfs constraint_1_power_limit_uw for Intel RAPL |
| 160 |
|
| 161 |
``power_limit_1_tmin_us`` (RO) |
| 162 |
Minimum powercap sysfs constraint_1_time_window_us for Intel RAPL |
| 163 |
|
| 164 |
``power_limit_1_tmax_us`` (RO) |
| 165 |
Maximum powercap sysfs constraint_1_time_window_us for Intel RAPL |
| 166 |
|
| 167 |
``power_floor_status`` (RO) |
| 168 |
When set to 1, the power floor of the system in the current |
| 169 |
configuration has been reached. It needs to be reconfigured to allow |
| 170 |
power to be reduced any further. |
| 171 |
|
| 172 |
``power_floor_enable`` (RW) |
| 173 |
When set to 1, enable reading and notification of the power floor |
| 174 |
status. Notifications are triggered for the power_floor_status |
| 175 |
attribute value changes. |
| 176 |
|
| 177 |
:file:`/sys/bus/pci/devices/0000\:00\:04.0/` |
| 178 |
|
| 179 |
``tcc_offset_degree_celsius`` (RW) |
| 180 |
TCC offset from the critical temperature where hardware will throttle |
| 181 |
CPU. |
| 182 |
|
| 183 |
:file:`/sys/bus/pci/devices/0000\:00\:04.0/workload_request` |
| 184 |
|
| 185 |
``workload_available_types`` (RO) |
| 186 |
Available workload types. User space can specify one of the workload type |
| 187 |
it is currently executing via workload_type. For example: idle, bursty, |
| 188 |
sustained etc. |
| 189 |
|
| 190 |
``workload_type`` (RW) |
| 191 |
User space can specify any one of the available workload type using |
| 192 |
this interface. |
| 193 |
|
| 194 |
:file:`/sys/bus/pci/devices/0000\:00\:04.0/ptc_0_control` |
| 195 |
:file:`/sys/bus/pci/devices/0000\:00\:04.0/ptc_1_control` |
| 196 |
:file:`/sys/bus/pci/devices/0000\:00\:04.0/ptc_2_control` |
| 197 |
|
| 198 |
All these controls needs admin privilege to update. |
| 199 |
|
| 200 |
``enable`` (RW) |
| 201 |
1 for enable, 0 for disable. Shows the current enable status of |
| 202 |
platform temperature control feature. User space can enable/disable |
| 203 |
hardware controls. |
| 204 |
|
| 205 |
``temperature_target`` (RW) |
| 206 |
Update a new temperature target in milli degree celsius for hardware to |
| 207 |
use for the temperature control. |
| 208 |
|
| 209 |
``thermal_tolerance`` (RW) |
| 210 |
This attribute ranges from 0 to 7, where 0 represents |
| 211 |
the most aggressive control to avoid any temperature overshoots, and |
| 212 |
7 represents a more graceful approach, favoring performance even at |
| 213 |
the expense of temperature overshoots. |
| 214 |
Note: This level may not scale linearly. For example, a value of 3 does |
| 215 |
not necessarily imply a 50% improvement in performance compared to a |
| 216 |
value of 0. |
| 217 |
|
| 218 |
Given that this is platform temperature control, it is expected that a |
| 219 |
single user-level manager owns and manages the controls. If multiple |
| 220 |
user-level software applications attempt to write different targets, it |
| 221 |
can lead to unexpected behavior. |
| 222 |
|
| 223 |
|
| 224 |
DPTF Processor thermal RFIM interface |
| 225 |
-------------------------------------------- |
| 226 |
|
| 227 |
RFIM interface allows adjustment of FIVR (Fully Integrated Voltage Regulator), |
| 228 |
DDR (Double Data Rate) and DLVR (Digital Linear Voltage Regulator) |
| 229 |
frequencies to avoid RF interference with WiFi and 5G. |
| 230 |
|
| 231 |
Switching voltage regulators (VR) generate radiated EMI or RFI at the |
| 232 |
fundamental frequency and its harmonics. Some harmonics may interfere |
| 233 |
with very sensitive wireless receivers such as Wi-Fi and cellular that |
| 234 |
are integrated into host systems like notebook PCs. One of mitigation |
| 235 |
methods is requesting SOC integrated VR (IVR) switching frequency to a |
| 236 |
small % and shift away the switching noise harmonic interference from |
| 237 |
radio channels. OEM or ODMs can use the driver to control SOC IVR |
| 238 |
operation within the range where it does not impact IVR performance. |
| 239 |
|
| 240 |
Some products use DLVR instead of FIVR as switching voltage regulator. |
| 241 |
In this case attributes of DLVR must be adjusted instead of FIVR. |
| 242 |
|
| 243 |
While shifting the frequencies additional clock noise can be introduced, |
| 244 |
which is compensated by adjusting Spread spectrum percent. This helps |
| 245 |
to reduce the clock noise to meet regulatory compliance. This spreading |
| 246 |
% increases bandwidth of signal transmission and hence reduces the |
| 247 |
effects of interference, noise and signal fading. |
| 248 |
|
| 249 |
DRAM devices of DDR IO interface and their power plane can generate EMI |
| 250 |
at the data rates. Similar to IVR control mechanism, Intel offers a |
| 251 |
mechanism by which DDR data rates can be changed if several conditions |
| 252 |
are met: there is strong RFI interference because of DDR; CPU power |
| 253 |
management has no other restriction in changing DDR data rates; |
| 254 |
PC ODMs enable this feature (real time DDR RFI Mitigation referred to as |
| 255 |
DDR-RFIM) for Wi-Fi from BIOS. |
| 256 |
|
| 257 |
|
| 258 |
FIVR attributes |
| 259 |
|
| 260 |
:file:`/sys/bus/pci/devices/0000\:00\:04.0/fivr/` |
| 261 |
|
| 262 |
``vco_ref_code_lo`` (RW) |
| 263 |
The VCO reference code is an 11-bit field and controls the FIVR |
| 264 |
switching frequency. This is the 3-bit LSB field. |
| 265 |
|
| 266 |
``vco_ref_code_hi`` (RW) |
| 267 |
The VCO reference code is an 11-bit field and controls the FIVR |
| 268 |
switching frequency. This is the 8-bit MSB field. |
| 269 |
|
| 270 |
``spread_spectrum_pct`` (RW) |
| 271 |
Set the FIVR spread spectrum clocking percentage |
| 272 |
|
| 273 |
``spread_spectrum_clk_enable`` (RW) |
| 274 |
Enable/disable of the FIVR spread spectrum clocking feature |
| 275 |
|
| 276 |
``rfi_vco_ref_code`` (RW) |
| 277 |
This field is a read only status register which reflects the |
| 278 |
current FIVR switching frequency |
| 279 |
|
| 280 |
``fivr_fffc_rev`` (RW) |
| 281 |
This field indicated the revision of the FIVR HW. |
| 282 |
|
| 283 |
|
| 284 |
DVFS attributes |
| 285 |
|
| 286 |
:file:`/sys/bus/pci/devices/0000\:00\:04.0/dvfs/` |
| 287 |
|
| 288 |
``rfi_restriction_run_busy`` (RW) |
| 289 |
Request the restriction of specific DDR data rate and set this |
| 290 |
value 1. Self reset to 0 after operation. |
| 291 |
|
| 292 |
``rfi_restriction_err_code`` (RW) |
| 293 |
0 :Request is accepted, 1:Feature disabled, |
| 294 |
2: the request restricts more points than it is allowed |
| 295 |
|
| 296 |
``rfi_restriction_data_rate_Delta`` (RW) |
| 297 |
Restricted DDR data rate for RFI protection: Lower Limit |
| 298 |
|
| 299 |
``rfi_restriction_data_rate_Base`` (RW) |
| 300 |
Restricted DDR data rate for RFI protection: Upper Limit |
| 301 |
|
| 302 |
``ddr_data_rate_point_0`` (RO) |
| 303 |
DDR data rate selection 1st point |
| 304 |
|
| 305 |
``ddr_data_rate_point_1`` (RO) |
| 306 |
DDR data rate selection 2nd point |
| 307 |
|
| 308 |
``ddr_data_rate_point_2`` (RO) |
| 309 |
DDR data rate selection 3rd point |
| 310 |
|
| 311 |
``ddr_data_rate_point_3`` (RO) |
| 312 |
DDR data rate selection 4th point |
| 313 |
|
| 314 |
``rfi_disable (RW)`` |
| 315 |
Disable DDR rate change feature |
| 316 |
|
| 317 |
DLVR attributes |
| 318 |
|
| 319 |
:file:`/sys/bus/pci/devices/0000\:00\:04.0/dlvr/` |
| 320 |
|
| 321 |
``dlvr_hardware_rev`` (RO) |
| 322 |
DLVR hardware revision. |
| 323 |
|
| 324 |
``dlvr_freq_mhz`` (RO) |
| 325 |
Current DLVR PLL frequency in MHz. |
| 326 |
|
| 327 |
``dlvr_freq_select`` (RW) |
| 328 |
Sets DLVR PLL clock frequency. Once set, and enabled via |
| 329 |
dlvr_rfim_enable, the dlvr_freq_mhz will show the current |
| 330 |
DLVR PLL frequency. |
| 331 |
|
| 332 |
``dlvr_pll_busy`` (RO) |
| 333 |
PLL can't accept frequency change when set. |
| 334 |
|
| 335 |
``dlvr_rfim_enable`` (RW) |
| 336 |
0: Disable RF frequency hopping, 1: Enable RF frequency hopping. |
| 337 |
|
| 338 |
``dlvr_spread_spectrum_pct`` (RW) |
| 339 |
Sets DLVR spread spectrum percent value. |
| 340 |
|
| 341 |
``dlvr_control_mode`` (RW) |
| 342 |
Specifies how frequencies are spread using spread spectrum. |
| 343 |
0: Down spread, |
| 344 |
1: Spread in the Center. |
| 345 |
|
| 346 |
``dlvr_control_lock`` (RW) |
| 347 |
1: future writes are ignored. |
| 348 |
|
| 349 |
DPTF Power supply and Battery Interface |
| 350 |
---------------------------------------- |
| 351 |
|
| 352 |
Refer to Documentation/ABI/testing/sysfs-platform-dptf |
| 353 |
|
| 354 |
DPTF Fan Control |
| 355 |
---------------------------------------- |
| 356 |
|
| 357 |
Refer to Documentation/admin-guide/acpi/fan_performance_states.rst |
| 358 |
|
| 359 |
Workload Type Hints |
| 360 |
---------------------------------------- |
| 361 |
|
| 362 |
The firmware in Meteor Lake processor generation is capable of identifying |
| 363 |
workload type and passing hints regarding it to the OS. A special sysfs |
| 364 |
interface is provided to allow user space to obtain workload type hints from |
| 365 |
the firmware and control the rate at which they are provided. |
| 366 |
|
| 367 |
User space can poll attribute "workload_type_index" for the current hint or |
| 368 |
can receive a notification whenever the value of this attribute is updated. |
| 369 |
|
| 370 |
file:`/sys/bus/pci/devices/0000:00:04.0/workload_hint/` |
| 371 |
Segment 0, bus 0, device 4, function 0 is reserved for the processor thermal |
| 372 |
device on all Intel client processors. So, the above path doesn't change |
| 373 |
based on the processor generation. |
| 374 |
|
| 375 |
``workload_hint_enable`` (RW) |
| 376 |
Enable firmware to send workload type hints to user space. |
| 377 |
|
| 378 |
``workload_slow_hint_enable`` (RW) |
| 379 |
Enable firmware to send slow workload type hints to user space. |
| 380 |
|
| 381 |
``notification_delay_ms`` (RW) |
| 382 |
Minimum delay in milliseconds before firmware will notify OS. This is |
| 383 |
for the rate control of notifications. This delay is between changing |
| 384 |
the workload type prediction in the firmware and notifying the OS about |
| 385 |
the change. The default delay is 1024 ms. The delay of 0 is invalid. |
| 386 |
The delay is rounded up to the nearest power of 2 to simplify firmware |
| 387 |
programming of the delay value. The read of notification_delay_ms |
| 388 |
attribute shows the effective value used. |
| 389 |
|
| 390 |
``workload_type_index`` (RO) |
| 391 |
Predicted workload type index. User space can get notification of |
| 392 |
change via existing sysfs attribute change notification mechanism. |
| 393 |
|
| 394 |
The supported index values and their meaning for the Meteor Lake |
| 395 |
processor generation are as follows: |
| 396 |
|
| 397 |
0 - Idle: System performs no tasks, power and idle residency are |
| 398 |
consistently low for long periods of time. |
| 399 |
|
| 400 |
1 – Battery Life: Power is relatively low, but the processor may |
| 401 |
still be actively performing a task, such as video playback for |
| 402 |
a long period of time. |
| 403 |
|
| 404 |
2 – Sustained: Power level that is relatively high for a long period |
| 405 |
of time, with very few to no periods of idleness, which will |
| 406 |
eventually exhaust RAPL Power Limit 1 and 2. |
| 407 |
|
| 408 |
3 – Bursty: Consumes a relatively constant average amount of power, but |
| 409 |
periods of relative idleness are interrupted by bursts of |
| 410 |
activity. The bursts are relatively short and the periods of |
| 411 |
relative idleness between them typically prevent RAPL Power |
| 412 |
Limit 1 from being exhausted. |
| 413 |
|
| 414 |
4 – Unknown: Can't classify. |
| 415 |
|
| 416 |
On processors starting from Panther Lake additional hints are provided. |
| 417 |
The hardware analyzes workload residencies over an extended period to |
| 418 |
determine whether the workload classification tends toward idle/battery |
| 419 |
life states or sustained/performance states. Based on this long-term |
| 420 |
analysis, it classifies: |
| 421 |
|
| 422 |
Power Classification: If the workload exhibits more idle or battery life |
| 423 |
residencies, it is classified as "power". |
| 424 |
|
| 425 |
Performance Classification: If the workload exhibits more sustained or |
| 426 |
performance residencies, it is classified as "performance". |
| 427 |
|
| 428 |
This approach enables applications to ignore short-term workload |
| 429 |
fluctuations and instead respond to longer-term power vs. performance |
| 430 |
trends. |
| 431 |
|
| 432 |
Residency thresholds for this classification are CPU generation-specific. |
| 433 |
Classification is reported via bit 4 of the workload_type_index: |
| 434 |
|
| 435 |
Bit 4 = 1: Power classification |
| 436 |
|
| 437 |
Bit 4 = 0: Performance classification |