1.. SPDX-License-Identifier: GPL-2.0
2
3===============================================================
4Intel(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
11Introduction
12------------
13
14Intel(R) Dynamic Platform and Thermal Framework (DPTF) is a platform
15level hardware/software solution for power and thermal management.
16
17As a container for multiple power/thermal technologies, DPTF provides
18a coordinated approach for different policies to effect the hardware
19state 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 uses
23ACPI and PCI devices to expose various features for monitoring and
24control. Linux has a set of kernel drivers exposing hardware interface
25to user space. This allows user space thermal solutions like
26"Linux Thermal Daemon" to read platform specific thermal and power
27tables to deliver adequate performance while keeping the system under
28thermal limits.
29
30DPTF 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
88ACPI 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
114DPTF ACPI Sensor drivers
115-------------------------
116
117DPTF Sensor drivers are presented as standard thermal sysfs thermal_zone.
118
119
120DPTF ACPI Cooling drivers
121--------------------------
122
123DPTF cooling drivers are presented as standard thermal sysfs cooling_device.
124
125
126DPTF Processor thermal PCI Driver interface
127--------------------------------------------
128
129:file:`/sys/bus/pci/devices/0000\:00\:04.0/power_limits/`
130
131Refer to Documentation/power/powercap/powercap.rst for powercap
132ABI.
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
181DPTF Processor thermal RFIM interface
182--------------------------------------------
183
184RFIM interface allows adjustment of FIVR (Fully Integrated Voltage Regulator)
185and DDR (Double Data Rate)frequencies to avoid RF interference with WiFi and 5G.
186
187Switching voltage regulators (VR) generate radiated EMI or RFI at the
188fundamental frequency and its harmonics. Some harmonics may interfere
189with very sensitive wireless receivers such as Wi-Fi and cellular that
190are integrated into host systems like notebook PCs.  One of mitigation
191methods is requesting SOC integrated VR (IVR) switching frequency to a
192small % and shift away the switching noise harmonic interference from
193radio channels.  OEM or ODMs can use the driver to control SOC IVR
194operation within the range where it does not impact IVR performance.
195
196DRAM devices of DDR IO interface and their power plane can generate EMI
197at the data rates. Similar to IVR control mechanism, Intel offers a
198mechanism by which DDR data rates can be changed if several conditions
199are met: there is strong RFI interference because of DDR; CPU power
200management has no other restriction in changing DDR data rates;
201PC ODMs enable this feature (real time DDR RFI Mitigation referred to as
202DDR-RFIM) for Wi-Fi from BIOS.
203
204
205FIVR 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
231DVFS 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
264DPTF Power supply and Battery Interface
265----------------------------------------
266
267Refer to Documentation/ABI/testing/sysfs-platform-dptf
268
269DPTF Fan Control
270----------------------------------------
271
272Refer to Documentation/admin-guide/acpi/fan_performance_states.rst
273