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)
188and DDR (Double Data Rate)frequencies to avoid RF interference with WiFi and 5G.
189
190Switching voltage regulators (VR) generate radiated EMI or RFI at the
191fundamental frequency and its harmonics. Some harmonics may interfere
192with very sensitive wireless receivers such as Wi-Fi and cellular that
193are integrated into host systems like notebook PCs.  One of mitigation
194methods is requesting SOC integrated VR (IVR) switching frequency to a
195small % and shift away the switching noise harmonic interference from
196radio channels.  OEM or ODMs can use the driver to control SOC IVR
197operation within the range where it does not impact IVR performance.
198
199DRAM devices of DDR IO interface and their power plane can generate EMI
200at the data rates. Similar to IVR control mechanism, Intel offers a
201mechanism by which DDR data rates can be changed if several conditions
202are met: there is strong RFI interference because of DDR; CPU power
203management has no other restriction in changing DDR data rates;
204PC ODMs enable this feature (real time DDR RFI Mitigation referred to as
205DDR-RFIM) for Wi-Fi from BIOS.
206
207
208FIVR attributes
209
210:file:`/sys/bus/pci/devices/0000\:00\:04.0/fivr/`
211
212``vco_ref_code_lo`` (RW)
213	The VCO reference code is an 11-bit field and controls the FIVR
214	switching frequency. This is the 3-bit LSB field.
215
216``vco_ref_code_hi`` (RW)
217	The VCO reference code is an 11-bit field and controls the FIVR
218	switching frequency. This is the 8-bit MSB field.
219
220``spread_spectrum_pct`` (RW)
221	Set the FIVR spread spectrum clocking percentage
222
223``spread_spectrum_clk_enable`` (RW)
224	Enable/disable of the FIVR spread spectrum clocking feature
225
226``rfi_vco_ref_code`` (RW)
227	This field is a read only status register which reflects the
228	current FIVR switching frequency
229
230``fivr_fffc_rev`` (RW)
231	This field indicated the revision of the FIVR HW.
232
233
234DVFS attributes
235
236:file:`/sys/bus/pci/devices/0000\:00\:04.0/dvfs/`
237
238``rfi_restriction_run_busy`` (RW)
239	Request the restriction of specific DDR data rate and set this
240	value 1. Self reset to 0 after operation.
241
242``rfi_restriction_err_code`` (RW)
243	0 :Request is accepted, 1:Feature disabled,
244	2: the request restricts more points than it is allowed
245
246``rfi_restriction_data_rate_Delta`` (RW)
247	Restricted DDR data rate for RFI protection: Lower Limit
248
249``rfi_restriction_data_rate_Base`` (RW)
250	Restricted DDR data rate for RFI protection: Upper Limit
251
252``ddr_data_rate_point_0`` (RO)
253	DDR data rate selection 1st point
254
255``ddr_data_rate_point_1`` (RO)
256	DDR data rate selection 2nd point
257
258``ddr_data_rate_point_2`` (RO)
259	DDR data rate selection 3rd point
260
261``ddr_data_rate_point_3`` (RO)
262	DDR data rate selection 4th point
263
264``rfi_disable (RW)``
265	Disable DDR rate change feature
266
267DPTF Power supply and Battery Interface
268----------------------------------------
269
270Refer to Documentation/ABI/testing/sysfs-platform-dptf
271
272DPTF Fan Control
273----------------------------------------
274
275Refer to Documentation/admin-guide/acpi/fan_performance_states.rst
276