382 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===============================================================4Intel(R) Dynamic Platform and Thermal Framework Sysfs Interface5===============================================================6 7:Copyright: © 2022 Intel Corporation8 9:Author: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>10 11Introduction12------------13 14Intel(R) Dynamic Platform and Thermal Framework (DPTF) is a platform15level hardware/software solution for power and thermal management.16 17As a container for multiple power/thermal technologies, DPTF provides18a coordinated approach for different policies to effect the hardware19state of a system.20 21Since it is a platform level framework, this has several components.22Some parts of the technology is implemented in the firmware and uses23ACPI and PCI devices to expose various features for monitoring and24control. Linux has a set of kernel drivers exposing hardware interface25to user space. This allows user space thermal solutions like26"Linux Thermal Daemon" to read platform specific thermal and power27tables to deliver adequate performance while keeping the system under28thermal limits.29 30DPTF ACPI Drivers interface31----------------------------32 33:file:`/sys/bus/platform/devices/<N>/uuids`, where <N>34=INT3400|INTC1040|INTC1041|INTC10A035 36``available_uuids`` (RO)37 A set of UUIDs strings presenting available policies38 which should be notified to the firmware when the39 user space can support those policies.40 41 UUID strings:42 43 "42A441D6-AE6A-462b-A84B-4A8CE79027D3" : Passive 144 45 "3A95C389-E4B8-4629-A526-C52C88626BAE" : Active46 47 "97C68AE7-15FA-499c-B8C9-5DA81D606E0A" : Critical48 49 "63BE270F-1C11-48FD-A6F7-3AF253FF3E2D" : Adaptive performance50 51 "5349962F-71E6-431D-9AE8-0A635B710AEE" : Emergency call52 53 "9E04115A-AE87-4D1C-9500-0F3E340BFE75" : Passive 254 55 "F5A35014-C209-46A4-993A-EB56DE7530A1" : Power Boss56 57 "6ED722A7-9240-48A5-B479-31EEF723D7CF" : Virtual Sensor58 59 "16CAF1B7-DD38-40ED-B1C1-1B8A1913D531" : Cooling mode60 61 "BE84BABF-C4D4-403D-B495-3128FD44dAC1" : HDC62 63``current_uuid`` (RW)64 User space can write strings from available UUIDs, one at a65 time.66 67:file:`/sys/bus/platform/devices/<N>/`, where <N>68=INT3400|INTC1040|INTC1041|INTC10A069 70``imok`` (WO)71 User space daemon write 1 to respond to firmware event72 for sending keep alive notification. User space receives73 THERMAL_EVENT_KEEP_ALIVE kobject uevent notification when74 firmware calls for user space to respond with imok ACPI75 method.76 77``odvp*`` (RO)78 Firmware thermal status variable values. Thermal tables79 calls for different processing based on these variable80 values.81 82``data_vault`` (RO)83 Binary thermal table. Refer to84 https:/github.com/intel/thermal_daemon for decoding85 thermal table.86 87``production_mode`` (RO)88 When different from zero, manufacturer locked thermal configuration89 from further changes.90 91ACPI Thermal Relationship table interface92------------------------------------------93 94:file:`/dev/acpi_thermal_rel`95 96 This device provides IOCTL interface to read standard ACPI97 thermal relationship tables via ACPI methods _TRT and _ART.98 These IOCTLs are defined in99 drivers/thermal/intel/int340x_thermal/acpi_thermal_rel.h100 101 IOCTLs:102 103 ACPI_THERMAL_GET_TRT_LEN: Get length of TRT table104 105 ACPI_THERMAL_GET_ART_LEN: Get length of ART table106 107 ACPI_THERMAL_GET_TRT_COUNT: Number of records in TRT table108 109 ACPI_THERMAL_GET_ART_COUNT: Number of records in ART table110 111 ACPI_THERMAL_GET_TRT: Read binary TRT table, length to read is112 provided via argument to ioctl().113 114 ACPI_THERMAL_GET_ART: Read binary ART table, length to read is115 provided via argument to ioctl().116 117DPTF ACPI Sensor drivers118-------------------------119 120DPTF Sensor drivers are presented as standard thermal sysfs thermal_zone.121 122 123DPTF ACPI Cooling drivers124--------------------------125 126DPTF cooling drivers are presented as standard thermal sysfs cooling_device.127 128 129DPTF Processor thermal PCI Driver interface130--------------------------------------------131 132:file:`/sys/bus/pci/devices/0000\:00\:04.0/power_limits/`133 134Refer to Documentation/power/powercap/powercap.rst for powercap135ABI.136 137``power_limit_0_max_uw`` (RO)138 Maximum powercap sysfs constraint_0_power_limit_uw for Intel RAPL139 140``power_limit_0_step_uw`` (RO)141 Power limit increment/decrements for Intel RAPL constraint 0 power limit142 143``power_limit_0_min_uw`` (RO)144 Minimum powercap sysfs constraint_0_power_limit_uw for Intel RAPL145 146``power_limit_0_tmin_us`` (RO)147 Minimum powercap sysfs constraint_0_time_window_us for Intel RAPL148 149``power_limit_0_tmax_us`` (RO)150 Maximum powercap sysfs constraint_0_time_window_us for Intel RAPL151 152``power_limit_1_max_uw`` (RO)153 Maximum powercap sysfs constraint_1_power_limit_uw for Intel RAPL154 155``power_limit_1_step_uw`` (RO)156 Power limit increment/decrements for Intel RAPL constraint 1 power limit157 158``power_limit_1_min_uw`` (RO)159 Minimum powercap sysfs constraint_1_power_limit_uw for Intel RAPL160 161``power_limit_1_tmin_us`` (RO)162 Minimum powercap sysfs constraint_1_time_window_us for Intel RAPL163 164``power_limit_1_tmax_us`` (RO)165 Maximum powercap sysfs constraint_1_time_window_us for Intel RAPL166 167``power_floor_status`` (RO)168 When set to 1, the power floor of the system in the current169 configuration has been reached. It needs to be reconfigured to allow170 power to be reduced any further.171 172``power_floor_enable`` (RW)173 When set to 1, enable reading and notification of the power floor174 status. Notifications are triggered for the power_floor_status175 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 throttle181 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 type187 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 using192 this interface.193 194DPTF Processor thermal RFIM interface195--------------------------------------------196 197RFIM interface allows adjustment of FIVR (Fully Integrated Voltage Regulator),198DDR (Double Data Rate) and DLVR (Digital Linear Voltage Regulator)199frequencies to avoid RF interference with WiFi and 5G.200 201Switching voltage regulators (VR) generate radiated EMI or RFI at the202fundamental frequency and its harmonics. Some harmonics may interfere203with very sensitive wireless receivers such as Wi-Fi and cellular that204are integrated into host systems like notebook PCs. One of mitigation205methods is requesting SOC integrated VR (IVR) switching frequency to a206small % and shift away the switching noise harmonic interference from207radio channels. OEM or ODMs can use the driver to control SOC IVR208operation within the range where it does not impact IVR performance.209 210Some products use DLVR instead of FIVR as switching voltage regulator.211In this case attributes of DLVR must be adjusted instead of FIVR.212 213While shifting the frequencies additional clock noise can be introduced,214which is compensated by adjusting Spread spectrum percent. This helps215to reduce the clock noise to meet regulatory compliance. This spreading216% increases bandwidth of signal transmission and hence reduces the217effects of interference, noise and signal fading.218 219DRAM devices of DDR IO interface and their power plane can generate EMI220at the data rates. Similar to IVR control mechanism, Intel offers a221mechanism by which DDR data rates can be changed if several conditions222are met: there is strong RFI interference because of DDR; CPU power223management has no other restriction in changing DDR data rates;224PC ODMs enable this feature (real time DDR RFI Mitigation referred to as225DDR-RFIM) for Wi-Fi from BIOS.226 227 228FIVR attributes229 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 FIVR234 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 FIVR238 switching frequency. This is the 8-bit MSB field.239 240``spread_spectrum_pct`` (RW)241 Set the FIVR spread spectrum clocking percentage242 243``spread_spectrum_clk_enable`` (RW)244 Enable/disable of the FIVR spread spectrum clocking feature245 246``rfi_vco_ref_code`` (RW)247 This field is a read only status register which reflects the248 current FIVR switching frequency249 250``fivr_fffc_rev`` (RW)251 This field indicated the revision of the FIVR HW.252 253 254DVFS attributes255 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 this260 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 allowed265 266``rfi_restriction_data_rate_Delta`` (RW)267 Restricted DDR data rate for RFI protection: Lower Limit268 269``rfi_restriction_data_rate_Base`` (RW)270 Restricted DDR data rate for RFI protection: Upper Limit271 272``ddr_data_rate_point_0`` (RO)273 DDR data rate selection 1st point274 275``ddr_data_rate_point_1`` (RO)276 DDR data rate selection 2nd point277 278``ddr_data_rate_point_2`` (RO)279 DDR data rate selection 3rd point280 281``ddr_data_rate_point_3`` (RO)282 DDR data rate selection 4th point283 284``rfi_disable (RW)``285 Disable DDR rate change feature286 287DLVR attributes288 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 via299 dlvr_rfim_enable, the dlvr_freq_mhz will show the current300 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 319DPTF Power supply and Battery Interface320----------------------------------------321 322Refer to Documentation/ABI/testing/sysfs-platform-dptf323 324DPTF Fan Control325----------------------------------------326 327Refer to Documentation/admin-guide/acpi/fan_performance_states.rst328 329Workload Type Hints330----------------------------------------331 332The firmware in Meteor Lake processor generation is capable of identifying333workload type and passing hints regarding it to the OS. A special sysfs334interface is provided to allow user space to obtain workload type hints from335the firmware and control the rate at which they are provided.336 337User space can poll attribute "workload_type_index" for the current hint or338can receive a notification whenever the value of this attribute is updated.339 340file:`/sys/bus/pci/devices/0000:00:04.0/workload_hint/`341Segment 0, bus 0, device 4, function 0 is reserved for the processor thermal342device on all Intel client processors. So, the above path doesn't change343based 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 is350 for the rate control of notifications. This delay is between changing351 the workload type prediction in the firmware and notifying the OS about352 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 firmware354 programming of the delay value. The read of notification_delay_ms355 attribute shows the effective value used.356 357``workload_type_index`` (RO)358 Predicted workload type index. User space can get notification of359 change via existing sysfs attribute change notification mechanism.360 361 The supported index values and their meaning for the Meteor Lake362 processor generation are as follows:363 364 0 - Idle: System performs no tasks, power and idle residency are365 consistently low for long periods of time.366 367 1 – Battery Life: Power is relatively low, but the processor may368 still be actively performing a task, such as video playback for369 a long period of time.370 371 2 – Sustained: Power level that is relatively high for a long period372 of time, with very few to no periods of idleness, which will373 eventually exhaust RAPL Power Limit 1 and 2.374 375 3 – Bursty: Consumes a relatively constant average amount of power, but376 periods of relative idleness are interrupted by bursts of377 activity. The bursts are relatively short and the periods of378 relative idleness between them typically prevent RAPL Power379 Limit 1 from being exhausted.380 381 4 – Unknown: Can't classify.382