Documentation/driver-api/thermal/intel_dptf.rst

   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 <srinivas.pandruvada@linux.intel.com>
  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 DPTF Processor thermal RFIM interface
 195 --------------------------------------------
 196
 197 RFIM interface allows adjustment of FIVR (Fully Integrated Voltage Regulator),
 198 DDR (Double Data Rate) and DLVR (Digital Linear Voltage Regulator)
 199 frequencies to avoid RF interference with WiFi and 5G.
 200
 201 Switching voltage regulators (VR) generate radiated EMI or RFI at the
 202 fundamental frequency and its harmonics. Some harmonics may interfere
 203 with very sensitive wireless receivers such as Wi-Fi and cellular that
 204 are integrated into host systems like notebook PCs.  One of mitigation
 205 methods is requesting SOC integrated VR (IVR) switching frequency to a
 206 small % and shift away the switching noise harmonic interference from
 207 radio channels.  OEM or ODMs can use the driver to control SOC IVR
 208 operation within the range where it does not impact IVR performance.
 209
 210 Some products use DLVR instead of FIVR as switching voltage regulator.
 211 In this case attributes of DLVR must be adjusted instead of FIVR.
 212
 213 While shifting the frequencies additional clock noise can be introduced,
 214 which is compensated by adjusting Spread spectrum percent. This helps
 215 to reduce the clock noise to meet regulatory compliance. This spreading
 216 % increases bandwidth of signal transmission and hence reduces the
 217 effects of interference, noise and signal fading.
 218
 219 DRAM devices of DDR IO interface and their power plane can generate EMI
 220 at the data rates. Similar to IVR control mechanism, Intel offers a
 221 mechanism by which DDR data rates can be changed if several conditions
 222 are met: there is strong RFI interference because of DDR; CPU power
 223 management has no other restriction in changing DDR data rates;
 224 PC ODMs enable this feature (real time DDR RFI Mitigation referred to as
 225 DDR-RFIM) for Wi-Fi from BIOS.
 226
 227
 228 FIVR attributes
 229
 230 :file:`/sys/bus/pci/devices/0000\:00\:04.0/fivr/`
 231
 232 ``vco_ref_code_lo`` (RW)
 233         The VCO reference code is an 11-bit field and controls the FIVR
 234         switching frequency. This is the 3-bit LSB field.
 235
 236 ``vco_ref_code_hi`` (RW)
 237         The VCO reference code is an 11-bit field and controls the FIVR
 238         switching frequency. This is the 8-bit MSB field.
 239
 240 ``spread_spectrum_pct`` (RW)
 241         Set the FIVR spread spectrum clocking percentage
 242
 243 ``spread_spectrum_clk_enable`` (RW)
 244         Enable/disable of the FIVR spread spectrum clocking feature
 245
 246 ``rfi_vco_ref_code`` (RW)
 247         This field is a read only status register which reflects the
 248         current FIVR switching frequency
 249
 250 ``fivr_fffc_rev`` (RW)
 251         This field indicated the revision of the FIVR HW.
 252
 253
 254 DVFS attributes
 255
 256 :file:`/sys/bus/pci/devices/0000\:00\:04.0/dvfs/`
 257
 258 ``rfi_restriction_run_busy`` (RW)
 259         Request the restriction of specific DDR data rate and set this
 260         value 1. Self reset to 0 after operation.
 261
 262 ``rfi_restriction_err_code`` (RW)
 263         0 :Request is accepted, 1:Feature disabled,
 264         2: the request restricts more points than it is allowed
 265
 266 ``rfi_restriction_data_rate_Delta`` (RW)
 267         Restricted DDR data rate for RFI protection: Lower Limit
 268
 269 ``rfi_restriction_data_rate_Base`` (RW)
 270         Restricted DDR data rate for RFI protection: Upper Limit
 271
 272 ``ddr_data_rate_point_0`` (RO)
 273         DDR data rate selection 1st point
 274
 275 ``ddr_data_rate_point_1`` (RO)
 276         DDR data rate selection 2nd point
 277
 278 ``ddr_data_rate_point_2`` (RO)
 279         DDR data rate selection 3rd point
 280
 281 ``ddr_data_rate_point_3`` (RO)
 282         DDR data rate selection 4th point
 283
 284 ``rfi_disable (RW)``
 285         Disable DDR rate change feature
 286
 287 DLVR attributes
 288
 289 :file:`/sys/bus/pci/devices/0000\:00\:04.0/dlvr/`
 290
 291 ``dlvr_hardware_rev`` (RO)
 292         DLVR hardware revision.
 293
 294 ``dlvr_freq_mhz`` (RO)
 295         Current DLVR PLL frequency in MHz.
 296
 297 ``dlvr_freq_select`` (RW)
 298         Sets DLVR PLL clock frequency. Once set, and enabled via
 299         dlvr_rfim_enable, the dlvr_freq_mhz will show the current
 300         DLVR PLL frequency.
 301
 302 ``dlvr_pll_busy`` (RO)
 303         PLL can't accept frequency change when set.
 304
 305 ``dlvr_rfim_enable`` (RW)
 306         0: Disable RF frequency hopping, 1: Enable RF frequency hopping.
 307
 308 ``dlvr_spread_spectrum_pct`` (RW)
 309         Sets DLVR spread spectrum percent value.
 310
 311 ``dlvr_control_mode`` (RW)
 312         Specifies how frequencies are spread using spread spectrum.
 313         0: Down spread,
 314         1: Spread in the Center.
 315
 316 ``dlvr_control_lock`` (RW)
 317     1: future writes are ignored.
 318
 319 DPTF Power supply and Battery Interface
 320 ----------------------------------------
 321
 322 Refer to Documentation/ABI/testing/sysfs-platform-dptf
 323
 324 DPTF Fan Control
 325 ----------------------------------------
 326
 327 Refer to Documentation/admin-guide/acpi/fan_performance_states.rst
 328
 329 Workload Type Hints
 330 ----------------------------------------
 331
 332 The firmware in Meteor Lake processor generation is capable of identifying
 333 workload type and passing hints regarding it to the OS. A special sysfs
 334 interface is provided to allow user space to obtain workload type hints from
 335 the firmware and control the rate at which they are provided.
 336
 337 User space can poll attribute "workload_type_index" for the current hint or
 338 can receive a notification whenever the value of this attribute is updated.
 339
 340 file:`/sys/bus/pci/devices/0000:00:04.0/workload_hint/`
 341 Segment 0, bus 0, device 4, function 0 is reserved for the processor thermal
 342 device on all Intel client processors. So, the above path doesn't change
 343 based on the processor generation.
 344
 345 ``workload_hint_enable`` (RW)
 346         Enable firmware to send workload type hints to user space.
 347
 348 ``notification_delay_ms`` (RW)
 349         Minimum delay in milliseconds before firmware will notify OS. This is
 350         for the rate control of notifications. This delay is between changing
 351         the workload type prediction in the firmware and notifying the OS about
 352         the change. The default delay is 1024 ms. The delay of 0 is invalid.
 353         The delay is rounded up to the nearest power of 2 to simplify firmware
 354         programming of the delay value. The read of notification_delay_ms
 355         attribute shows the effective value used.
 356
 357 ``workload_type_index`` (RO)
 358         Predicted workload type index. User space can get notification of
 359         change via existing sysfs attribute change notification mechanism.
 360
 361         The supported index values and their meaning for the Meteor Lake
 362         processor generation are as follows:
 363
 364         0 -  Idle: System performs no tasks, power and idle residency are
 365                 consistently low for long periods of time.
 366
 367         1 – Battery Life: Power is relatively low, but the processor may
 368                 still be actively performing a task, such as video playback for
 369                 a long period of time.
 370
 371         2 – Sustained: Power level that is relatively high for a long period
 372                 of time, with very few to no periods of idleness, which will
 373                 eventually exhaust RAPL Power Limit 1 and 2.
 374
 375         3 – Bursty: Consumes a relatively constant average amount of power, but
 376                 periods of relative idleness are interrupted by bursts of
 377                 activity. The bursts are relatively short and the periods of
 378                 relative idleness between them typically prevent RAPL Power
 379                 Limit 1 from being exhausted.
 380
 381         4 – Unknown: Can't classify.