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
  88 ACPI Thermal Relationship table interface
  89 ------------------------------------------
  90
  91 :file:`/dev/acpi_thermal_rel`
  92
  93         This device provides IOCTL interface to read standard ACPI
  94         thermal relationship tables via ACPI methods _TRT and _ART.
  95         These IOCTLs are defined in
  96         drivers/thermal/intel/int340x_thermal/acpi_thermal_rel.h
  97
  98         IOCTLs:
  99
 100         ACPI_THERMAL_GET_TRT_LEN: Get length of TRT table
 101
 102         ACPI_THERMAL_GET_ART_LEN: Get length of ART table
 103
 104         ACPI_THERMAL_GET_TRT_COUNT: Number of records in TRT table
 105
 106         ACPI_THERMAL_GET_ART_COUNT: Number of records in ART table
 107
 108         ACPI_THERMAL_GET_TRT: Read binary TRT table, length to read is
 109         provided via argument to ioctl().
 110
 111         ACPI_THERMAL_GET_ART: Read binary ART table, length to read is
 112         provided via argument to ioctl().
 113
 114 DPTF ACPI Sensor drivers
 115 -------------------------
 116
 117 DPTF Sensor drivers are presented as standard thermal sysfs thermal_zone.
 118
 119
 120 DPTF ACPI Cooling drivers
 121 --------------------------
 122
 123 DPTF cooling drivers are presented as standard thermal sysfs cooling_device.
 124
 125
 126 DPTF Processor thermal PCI Driver interface
 127 --------------------------------------------
 128
 129 :file:`/sys/bus/pci/devices/0000\:00\:04.0/power_limits/`
 130
 131 Refer to Documentation/power/powercap/powercap.rst for powercap
 132 ABI.
 133
 134 ``power_limit_0_max_uw`` (RO)
 135         Maximum powercap sysfs constraint_0_power_limit_uw for Intel RAPL
 136
 137 ``power_limit_0_step_uw`` (RO)
 138         Power limit increment/decrements for Intel RAPL constraint 0 power limit
 139
 140 ``power_limit_0_min_uw`` (RO)
 141         Minimum powercap sysfs constraint_0_power_limit_uw for Intel RAPL
 142
 143 ``power_limit_0_tmin_us`` (RO)
 144         Minimum powercap sysfs constraint_0_time_window_us for Intel RAPL
 145
 146 ``power_limit_0_tmax_us`` (RO)
 147         Maximum powercap sysfs constraint_0_time_window_us for Intel RAPL
 148
 149 ``power_limit_1_max_uw`` (RO)
 150         Maximum powercap sysfs constraint_1_power_limit_uw for Intel RAPL
 151
 152 ``power_limit_1_step_uw`` (RO)
 153         Power limit increment/decrements for Intel RAPL constraint 1 power limit
 154
 155 ``power_limit_1_min_uw`` (RO)
 156         Minimum powercap sysfs constraint_1_power_limit_uw for Intel RAPL
 157
 158 ``power_limit_1_tmin_us`` (RO)
 159         Minimum powercap sysfs constraint_1_time_window_us for Intel RAPL
 160
 161 ``power_limit_1_tmax_us`` (RO)
 162         Maximum powercap sysfs constraint_1_time_window_us for Intel RAPL
 163
 164 :file:`/sys/bus/pci/devices/0000\:00\:04.0/`
 165
 166 ``tcc_offset_degree_celsius`` (RW)
 167         TCC offset from the critical temperature where hardware will throttle
 168         CPU.
 169
 170 :file:`/sys/bus/pci/devices/0000\:00\:04.0/workload_request`
 171
 172 ``workload_available_types`` (RO)
 173         Available workload types. User space can specify one of the workload type
 174         it is currently executing via workload_type. For example: idle, bursty,
 175         sustained etc.
 176
 177 ``workload_type`` (RW)
 178         User space can specify any one of the available workload type using
 179         this interface.
 180
 181 DPTF Processor thermal RFIM interface
 182 --------------------------------------------
 183
 184 RFIM interface allows adjustment of FIVR (Fully Integrated Voltage Regulator)
 185 and DDR (Double Data Rate)frequencies to avoid RF interference with WiFi and 5G.
 186
 187 Switching voltage regulators (VR) generate radiated EMI or RFI at the
 188 fundamental frequency and its harmonics. Some harmonics may interfere
 189 with very sensitive wireless receivers such as Wi-Fi and cellular that
 190 are integrated into host systems like notebook PCs.  One of mitigation
 191 methods is requesting SOC integrated VR (IVR) switching frequency to a
 192 small % and shift away the switching noise harmonic interference from
 193 radio channels.  OEM or ODMs can use the driver to control SOC IVR
 194 operation within the range where it does not impact IVR performance.
 195
 196 DRAM devices of DDR IO interface and their power plane can generate EMI
 197 at the data rates. Similar to IVR control mechanism, Intel offers a
 198 mechanism by which DDR data rates can be changed if several conditions
 199 are met: there is strong RFI interference because of DDR; CPU power
 200 management has no other restriction in changing DDR data rates;
 201 PC ODMs enable this feature (real time DDR RFI Mitigation referred to as
 202 DDR-RFIM) for Wi-Fi from BIOS.
 203
 204
 205 FIVR attributes
 206
 207 :file:`/sys/bus/pci/devices/0000\:00\:04.0/fivr/`
 208
 209 ``vco_ref_code_lo`` (RW)
 210         The VCO reference code is an 11-bit field and controls the FIVR
 211         switching frequency. This is the 3-bit LSB field.
 212
 213 ``vco_ref_code_hi`` (RW)
 214         The VCO reference code is an 11-bit field and controls the FIVR
 215         switching frequency. This is the 8-bit MSB field.
 216
 217 ``spread_spectrum_pct`` (RW)
 218         Set the FIVR spread spectrum clocking percentage
 219
 220 ``spread_spectrum_clk_enable`` (RW)
 221         Enable/disable of the FIVR spread spectrum clocking feature
 222
 223 ``rfi_vco_ref_code`` (RW)
 224         This field is a read only status register which reflects the
 225         current FIVR switching frequency
 226
 227 ``fivr_fffc_rev`` (RW)
 228         This field indicated the revision of the FIVR HW.
 229
 230
 231 DVFS attributes
 232
 233 :file:`/sys/bus/pci/devices/0000\:00\:04.0/dvfs/`
 234
 235 ``rfi_restriction_run_busy`` (RW)
 236         Request the restriction of specific DDR data rate and set this
 237         value 1. Self reset to 0 after operation.
 238
 239 ``rfi_restriction_err_code`` (RW)
 240         0 :Request is accepted, 1:Feature disabled,
 241         2: the request restricts more points than it is allowed
 242
 243 ``rfi_restriction_data_rate_Delta`` (RW)
 244         Restricted DDR data rate for RFI protection: Lower Limit
 245
 246 ``rfi_restriction_data_rate_Base`` (RW)
 247         Restricted DDR data rate for RFI protection: Upper Limit
 248
 249 ``ddr_data_rate_point_0`` (RO)
 250         DDR data rate selection 1st point
 251
 252 ``ddr_data_rate_point_1`` (RO)
 253         DDR data rate selection 2nd point
 254
 255 ``ddr_data_rate_point_2`` (RO)
 256         DDR data rate selection 3rd point
 257
 258 ``ddr_data_rate_point_3`` (RO)
 259         DDR data rate selection 4th point
 260
 261 ``rfi_disable (RW)``
 262         Disable DDR rate change feature
 263
 264 DPTF Power supply and Battery Interface
 265 ----------------------------------------
 266
 267 Refer to Documentation/ABI/testing/sysfs-platform-dptf
 268
 269 DPTF Fan Control
 270 ----------------------------------------
 271
 272 Refer to Documentation/admin-guide/acpi/fan_performance_states.rst