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``production_mode`` (RO)
88	When different from zero, manufacturer locked thermal configuration
89	from further changes.
90
91ACPI 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
117DPTF ACPI Sensor drivers
118-------------------------
119
120DPTF Sensor drivers are presented as standard thermal sysfs thermal_zone.
121
122
123DPTF ACPI Cooling drivers
124--------------------------
125
126DPTF cooling drivers are presented as standard thermal sysfs cooling_device.
127
128
129DPTF Processor thermal PCI Driver interface
130--------------------------------------------
131
132:file:`/sys/bus/pci/devices/0000\:00\:04.0/power_limits/`
133
134Refer to Documentation/power/powercap/powercap.rst for powercap
135ABI.
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:file:`/sys/bus/pci/devices/0000\:00\:04.0/`
168
169``tcc_offset_degree_celsius`` (RW)
170	TCC offset from the critical temperature where hardware will throttle
171	CPU.
172
173:file:`/sys/bus/pci/devices/0000\:00\:04.0/workload_request`
174
175``workload_available_types`` (RO)
176	Available workload types. User space can specify one of the workload type
177	it is currently executing via workload_type. For example: idle, bursty,
178	sustained etc.
179
180``workload_type`` (RW)
181	User space can specify any one of the available workload type using
182	this interface.
183
184DPTF Processor thermal RFIM interface
185--------------------------------------------
186
187RFIM interface allows adjustment of FIVR (Fully Integrated Voltage Regulator),
188DDR (Double Data Rate) and DLVR (Digital Linear Voltage Regulator)
189frequencies to avoid RF interference with WiFi and 5G.
190
191Switching voltage regulators (VR) generate radiated EMI or RFI at the
192fundamental frequency and its harmonics. Some harmonics may interfere
193with very sensitive wireless receivers such as Wi-Fi and cellular that
194are integrated into host systems like notebook PCs.  One of mitigation
195methods is requesting SOC integrated VR (IVR) switching frequency to a
196small % and shift away the switching noise harmonic interference from
197radio channels.  OEM or ODMs can use the driver to control SOC IVR
198operation within the range where it does not impact IVR performance.
199
200Some products use DLVR instead of FIVR as switching voltage regulator.
201In this case attributes of DLVR must be adjusted instead of FIVR.
202
203While shifting the frequencies additional clock noise can be introduced,
204which is compensated by adjusting Spread spectrum percent. This helps
205to reduce the clock noise to meet regulatory compliance. This spreading
206% increases bandwidth of signal transmission and hence reduces the
207effects of interference, noise and signal fading.
208
209DRAM devices of DDR IO interface and their power plane can generate EMI
210at the data rates. Similar to IVR control mechanism, Intel offers a
211mechanism by which DDR data rates can be changed if several conditions
212are met: there is strong RFI interference because of DDR; CPU power
213management has no other restriction in changing DDR data rates;
214PC ODMs enable this feature (real time DDR RFI Mitigation referred to as
215DDR-RFIM) for Wi-Fi from BIOS.
216
217
218FIVR attributes
219
220:file:`/sys/bus/pci/devices/0000\:00\:04.0/fivr/`
221
222``vco_ref_code_lo`` (RW)
223	The VCO reference code is an 11-bit field and controls the FIVR
224	switching frequency. This is the 3-bit LSB field.
225
226``vco_ref_code_hi`` (RW)
227	The VCO reference code is an 11-bit field and controls the FIVR
228	switching frequency. This is the 8-bit MSB field.
229
230``spread_spectrum_pct`` (RW)
231	Set the FIVR spread spectrum clocking percentage
232
233``spread_spectrum_clk_enable`` (RW)
234	Enable/disable of the FIVR spread spectrum clocking feature
235
236``rfi_vco_ref_code`` (RW)
237	This field is a read only status register which reflects the
238	current FIVR switching frequency
239
240``fivr_fffc_rev`` (RW)
241	This field indicated the revision of the FIVR HW.
242
243
244DVFS attributes
245
246:file:`/sys/bus/pci/devices/0000\:00\:04.0/dvfs/`
247
248``rfi_restriction_run_busy`` (RW)
249	Request the restriction of specific DDR data rate and set this
250	value 1. Self reset to 0 after operation.
251
252``rfi_restriction_err_code`` (RW)
253	0 :Request is accepted, 1:Feature disabled,
254	2: the request restricts more points than it is allowed
255
256``rfi_restriction_data_rate_Delta`` (RW)
257	Restricted DDR data rate for RFI protection: Lower Limit
258
259``rfi_restriction_data_rate_Base`` (RW)
260	Restricted DDR data rate for RFI protection: Upper Limit
261
262``ddr_data_rate_point_0`` (RO)
263	DDR data rate selection 1st point
264
265``ddr_data_rate_point_1`` (RO)
266	DDR data rate selection 2nd point
267
268``ddr_data_rate_point_2`` (RO)
269	DDR data rate selection 3rd point
270
271``ddr_data_rate_point_3`` (RO)
272	DDR data rate selection 4th point
273
274``rfi_disable (RW)``
275	Disable DDR rate change feature
276
277DLVR attributes
278
279:file:`/sys/bus/pci/devices/0000\:00\:04.0/dlvr/`
280
281``dlvr_hardware_rev`` (RO)
282	DLVR hardware revision.
283
284``dlvr_freq_mhz`` (RO)
285	Current DLVR PLL frequency in MHz.
286
287``dlvr_freq_select`` (RW)
288	Sets DLVR PLL clock frequency. Once set, and enabled via
289	dlvr_rfim_enable, the dlvr_freq_mhz will show the current
290	DLVR PLL frequency.
291
292``dlvr_pll_busy`` (RO)
293	PLL can't accept frequency change when set.
294
295``dlvr_rfim_enable`` (RW)
296	0: Disable RF frequency hopping, 1: Enable RF frequency hopping.
297
298``dlvr_spread_spectrum_pct`` (RW)
299	Sets DLVR spread spectrum percent value.
300
301``dlvr_control_mode`` (RW)
302        Specifies how frequencies are spread using spread spectrum.
303        0: Down spread,
304        1: Spread in the Center.
305
306``dlvr_control_lock`` (RW)
307    1: future writes are ignored.
308
309DPTF Power supply and Battery Interface
310----------------------------------------
311
312Refer to Documentation/ABI/testing/sysfs-platform-dptf
313
314DPTF Fan Control
315----------------------------------------
316
317Refer to Documentation/admin-guide/acpi/fan_performance_states.rst
318