Documentation/driver-api/thermal/intel_dptf.rst GitHub 원문 ↗

Linux 6.18.37 · Driver API

Intel DPTF Sysfs Interface

Intel DPTF의 ACPI policy, thermal relationship table, RAPL power limit, platform control, RFIM 및 Meteor Lake workload hint interface를 설명하는 한국어 전문 번역입니다.

Source pathDocumentation/driver-api/thermal/intel_dptf.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약·해설

intel_dptf.rst:1-411

DPTF는 firmware, ACPI·PCI device, Linux driver, user space thermal manager를 연결합니다. 이 문서는 policy UUID와 thermal table IOCTL부터 RAPL power floor, platform target, RF interference mitigation, Meteor Lake workload hint까지 공개되는 interface의 경로·권한·값을 정리합니다.

문서 구성
원문 줄핵심 내용
1-29DPTF 목적과 구성
30-90ACPI policy UUID와 firmware interface
91-128Thermal relationship table, sensor, cooling driver
129-223RAPL power limit과 platform temperature control
224-348RFIM 개요와 FIVR·DVFS·DLVR 속성
349-358Power supply, battery, fan 관련 문서
359-411Meteor Lake workload type hint

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
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 <[email protected]>
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 ``production_mode`` (RO)
88 When different from zero, manufacturer locked thermal configuration
89 from further changes.
90
91 ACPI 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
117 DPTF ACPI Sensor drivers
118 -------------------------
119
120 DPTF Sensor drivers are presented as standard thermal sysfs thermal_zone.
121
122
123 DPTF ACPI Cooling drivers
124 --------------------------
125
126 DPTF cooling drivers are presented as standard thermal sysfs cooling_device.
127
128
129 DPTF Processor thermal PCI Driver interface
130 --------------------------------------------
131
132 :file:`/sys/bus/pci/devices/0000\:00\:04.0/power_limits/`
133
134 Refer to Documentation/power/powercap/powercap.rst for powercap
135 ABI.
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 ``power_floor_status`` (RO)
168 When set to 1, the power floor of the system in the current
169 configuration has been reached. It needs to be reconfigured to allow
170 power to be reduced any further.
171
172 ``power_floor_enable`` (RW)
173 When set to 1, enable reading and notification of the power floor
174 status. Notifications are triggered for the power_floor_status
175 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 throttle
181 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 type
187 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 using
192 this interface.
193
194 :file:`/sys/bus/pci/devices/0000\:00\:04.0/ptc_0_control`
195 :file:`/sys/bus/pci/devices/0000\:00\:04.0/ptc_1_control`
196 :file:`/sys/bus/pci/devices/0000\:00\:04.0/ptc_2_control`
197
198 All these controls needs admin privilege to update.
199
200 ``enable`` (RW)
201 1 for enable, 0 for disable. Shows the current enable status of
202 platform temperature control feature. User space can enable/disable
203 hardware controls.
204
205 ``temperature_target`` (RW)
206 Update a new temperature target in milli degree celsius for hardware to
207 use for the temperature control.
208
209 ``thermal_tolerance`` (RW)
210 This attribute ranges from 0 to 7, where 0 represents
211 the most aggressive control to avoid any temperature overshoots, and
212 7 represents a more graceful approach, favoring performance even at
213 the expense of temperature overshoots.
214 Note: This level may not scale linearly. For example, a value of 3 does
215 not necessarily imply a 50% improvement in performance compared to a
216 value of 0.
217
218 Given that this is platform temperature control, it is expected that a
219 single user-level manager owns and manages the controls. If multiple
220 user-level software applications attempt to write different targets, it
221 can lead to unexpected behavior.
222
223
224 DPTF Processor thermal RFIM interface
225 --------------------------------------------
226
227 RFIM interface allows adjustment of FIVR (Fully Integrated Voltage Regulator),
228 DDR (Double Data Rate) and DLVR (Digital Linear Voltage Regulator)
229 frequencies to avoid RF interference with WiFi and 5G.
230
231 Switching voltage regulators (VR) generate radiated EMI or RFI at the
232 fundamental frequency and its harmonics. Some harmonics may interfere
233 with very sensitive wireless receivers such as Wi-Fi and cellular that
234 are integrated into host systems like notebook PCs. One of mitigation
235 methods is requesting SOC integrated VR (IVR) switching frequency to a
236 small % and shift away the switching noise harmonic interference from
237 radio channels. OEM or ODMs can use the driver to control SOC IVR
238 operation within the range where it does not impact IVR performance.
239
240 Some products use DLVR instead of FIVR as switching voltage regulator.
241 In this case attributes of DLVR must be adjusted instead of FIVR.
242
243 While shifting the frequencies additional clock noise can be introduced,
244 which is compensated by adjusting Spread spectrum percent. This helps
245 to reduce the clock noise to meet regulatory compliance. This spreading
246 % increases bandwidth of signal transmission and hence reduces the
247 effects of interference, noise and signal fading.
248
249 DRAM devices of DDR IO interface and their power plane can generate EMI
250 at the data rates. Similar to IVR control mechanism, Intel offers a
251 mechanism by which DDR data rates can be changed if several conditions
252 are met: there is strong RFI interference because of DDR; CPU power
253 management has no other restriction in changing DDR data rates;
254 PC ODMs enable this feature (real time DDR RFI Mitigation referred to as
255 DDR-RFIM) for Wi-Fi from BIOS.
256
257
258 FIVR attributes
259
260 :file:`/sys/bus/pci/devices/0000\:00\:04.0/fivr/`
261
262 ``vco_ref_code_lo`` (RW)
263 The VCO reference code is an 11-bit field and controls the FIVR
264 switching frequency. This is the 3-bit LSB field.
265
266 ``vco_ref_code_hi`` (RW)
267 The VCO reference code is an 11-bit field and controls the FIVR
268 switching frequency. This is the 8-bit MSB field.
269
270 ``spread_spectrum_pct`` (RW)
271 Set the FIVR spread spectrum clocking percentage
272
273 ``spread_spectrum_clk_enable`` (RW)
274 Enable/disable of the FIVR spread spectrum clocking feature
275
276 ``rfi_vco_ref_code`` (RW)
277 This field is a read only status register which reflects the
278 current FIVR switching frequency
279
280 ``fivr_fffc_rev`` (RW)
281 This field indicated the revision of the FIVR HW.
282
283
284 DVFS attributes
285
286 :file:`/sys/bus/pci/devices/0000\:00\:04.0/dvfs/`
287
288 ``rfi_restriction_run_busy`` (RW)
289 Request the restriction of specific DDR data rate and set this
290 value 1. Self reset to 0 after operation.
291
292 ``rfi_restriction_err_code`` (RW)
293 0 :Request is accepted, 1:Feature disabled,
294 2: the request restricts more points than it is allowed
295
296 ``rfi_restriction_data_rate_Delta`` (RW)
297 Restricted DDR data rate for RFI protection: Lower Limit
298
299 ``rfi_restriction_data_rate_Base`` (RW)
300 Restricted DDR data rate for RFI protection: Upper Limit
301
302 ``ddr_data_rate_point_0`` (RO)
303 DDR data rate selection 1st point
304
305 ``ddr_data_rate_point_1`` (RO)
306 DDR data rate selection 2nd point
307
308 ``ddr_data_rate_point_2`` (RO)
309 DDR data rate selection 3rd point
310
311 ``ddr_data_rate_point_3`` (RO)
312 DDR data rate selection 4th point
313
314 ``rfi_disable (RW)``
315 Disable DDR rate change feature
316
317 DLVR attributes
318
319 :file:`/sys/bus/pci/devices/0000\:00\:04.0/dlvr/`
320
321 ``dlvr_hardware_rev`` (RO)
322 DLVR hardware revision.
323
324 ``dlvr_freq_mhz`` (RO)
325 Current DLVR PLL frequency in MHz.
326
327 ``dlvr_freq_select`` (RW)
328 Sets DLVR PLL clock frequency. Once set, and enabled via
329 dlvr_rfim_enable, the dlvr_freq_mhz will show the current
330 DLVR PLL frequency.
331
332 ``dlvr_pll_busy`` (RO)
333 PLL can't accept frequency change when set.
334
335 ``dlvr_rfim_enable`` (RW)
336 0: Disable RF frequency hopping, 1: Enable RF frequency hopping.
337
338 ``dlvr_spread_spectrum_pct`` (RW)
339 Sets DLVR spread spectrum percent value.
340
341 ``dlvr_control_mode`` (RW)
342 Specifies how frequencies are spread using spread spectrum.
343 0: Down spread,
344 1: Spread in the Center.
345
346 ``dlvr_control_lock`` (RW)
347 1: future writes are ignored.
348
349 DPTF Power supply and Battery Interface
350 ----------------------------------------
351
352 Refer to Documentation/ABI/testing/sysfs-platform-dptf
353
354 DPTF Fan Control
355 ----------------------------------------
356
357 Refer to Documentation/admin-guide/acpi/fan_performance_states.rst
358
359 Workload Type Hints
360 ----------------------------------------
361
362 The firmware in Meteor Lake processor generation is capable of identifying
363 workload type and passing hints regarding it to the OS. A special sysfs
364 interface is provided to allow user space to obtain workload type hints from
365 the firmware and control the rate at which they are provided.
366
367 User space can poll attribute "workload_type_index" for the current hint or
368 can receive a notification whenever the value of this attribute is updated.
369
370 file:`/sys/bus/pci/devices/0000:00:04.0/workload_hint/`
371 Segment 0, bus 0, device 4, function 0 is reserved for the processor thermal
372 device on all Intel client processors. So, the above path doesn't change
373 based on the processor generation.
374
375 ``workload_hint_enable`` (RW)
376 Enable firmware to send workload type hints to user space.
377
378 ``notification_delay_ms`` (RW)
379 Minimum delay in milliseconds before firmware will notify OS. This is
380 for the rate control of notifications. This delay is between changing
381 the workload type prediction in the firmware and notifying the OS about
382 the change. The default delay is 1024 ms. The delay of 0 is invalid.
383 The delay is rounded up to the nearest power of 2 to simplify firmware
384 programming of the delay value. The read of notification_delay_ms
385 attribute shows the effective value used.
386
387 ``workload_type_index`` (RO)
388 Predicted workload type index. User space can get notification of
389 change via existing sysfs attribute change notification mechanism.
390
391 The supported index values and their meaning for the Meteor Lake
392 processor generation are as follows:
393
394 0 - Idle: System performs no tasks, power and idle residency are
395 consistently low for long periods of time.
396
397 1 – Battery Life: Power is relatively low, but the processor may
398 still be actively performing a task, such as video playback for
399 a long period of time.
400
401 2 – Sustained: Power level that is relatively high for a long period
402 of time, with very few to no periods of idleness, which will
403 eventually exhaust RAPL Power Limit 1 and 2.
404
405 3 – Bursty: Consumes a relatively constant average amount of power, but
406 periods of relative idleness are interrupted by bursts of
407 activity. The bursts are relatively short and the periods of
408 relative idleness between them typically prevent RAPL Power
409 Limit 1 from being exhausted.
410
411 4 – Unknown: Can't classify.
412

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Intel DPTF 소개

1-29

이 문서는 `GPL-2.0` license가 적용되는 Intel(R) Dynamic Platform and Thermal Framework Sysfs Interface 설명서입니다. Copyright는 2022 Intel Corporation에 있으며 저자는 Srinivas Pandruvada입니다.

Intel(R) Dynamic Platform and Thermal Framework(DPTF)는 platform 수준에서 전력과 열을 관리하는 hardware/software solution입니다. 여러 power/thermal 기술을 담는 container로서, 서로 다른 policy가 system hardware state에 협조된 방식으로 영향을 주도록 합니다.

Platform framework인 DPTF는 여러 component로 구성됩니다. 일부 기술은 firmware에 구현되며 ACPI와 PCI device를 통해 monitoring 및 control 기능을 노출합니다. Linux kernel driver는 이 hardware interface를 user space에 제공합니다.

따라서 `Linux Thermal Daemon` 같은 user space thermal solution은 platform별 thermal·power table을 읽고, system을 thermal limit 이내로 유지하면서 적절한 performance를 제공할 수 있습니다.

DPTF 전력·열 관리 경로
Platform firmwareACPI and PCI devices
ACPI and PCI devicesLinux DPTF kernel drivers
Linux DPTF kernel driversSysfs and device interfaces
Sysfs and device interfacesLinux Thermal Daemon
Linux Thermal DaemonPerformance within thermal limits

Firmware에서 user space thermal policy까지 이어지는 DPTF 구성입니다.

.. SPDX-License-Identifier: GPL-2.0

===============================================================
Intel(R) Dynamic Platform and Thermal Framework Sysfs Interface
===============================================================

:Copyright: © 2022 Intel Corporation

:Author: Srinivas Pandruvada <[email protected]>

Introduction
------------

Intel(R) Dynamic Platform and Thermal Framework (DPTF) is a platform
level hardware/software solution for power and thermal management.

As a container for multiple power/thermal technologies, DPTF provides
a coordinated approach for different policies to effect the hardware
state of a system.

Since it is a platform level framework, this has several components.
Some parts of the technology is implemented in the firmware and uses
ACPI and PCI devices to expose various features for monitoring and
control. Linux has a set of kernel drivers exposing hardware interface
to user space. This allows user space thermal solutions like
"Linux Thermal Daemon" to read platform specific thermal and power
tables to deliver adequate performance while keeping the system under
thermal limits.

DPTF ACPI driver interface

30-90

`/sys/bus/platform/devices/<N>/uuids`에서 `<N>`은 `INT3400`, `INTC1040`, `INTC1041`, `INTC10A0` 중 하나입니다. Read-only `available_uuids`는 user space가 지원할 수 있을 때 firmware에 알려야 하는 사용 가능 policy UUID 문자열 집합입니다.

Read-write `current_uuid`에는 `available_uuids`의 문자열을 한 번에 하나씩 쓸 수 있습니다.

같은 platform device directory의 write-only `imok`에는 user space daemon이 1을 써서 firmware keep-alive event에 응답합니다. Firmware가 `imok` ACPI method를 통한 응답을 요구하면 user space는 `THERMAL_EVENT_KEEP_ALIVE` kobject uevent notification을 받습니다.

Read-only `odvp*`는 firmware thermal status variable 값입니다. Thermal table은 이 variable 값에 따라 서로 다른 처리를 요구합니다. Read-only `data_vault`는 binary thermal table이며 `https:/github.com/intel/thermal_daemon`을 참조해 decode합니다.

Read-only `production_mode`가 0이 아니면 제조업체가 thermal configuration을 잠가 추가 변경을 막은 상태입니다.

DPTF ACPI policy UUID와 sysfs 속성
이름권한정책 또는 의미
`42A441D6-AE6A-462b-A84B-4A8CE79027D3`UUIDPassive 1
`3A95C389-E4B8-4629-A526-C52C88626BAE`UUIDActive
`97C68AE7-15FA-499c-B8C9-5DA81D606E0A`UUIDCritical
`63BE270F-1C11-48FD-A6F7-3AF253FF3E2D`UUIDAdaptive performance
`5349962F-71E6-431D-9AE8-0A635B710AEE`UUIDEmergency call
`9E04115A-AE87-4D1C-9500-0F3E340BFE75`UUIDPassive 2
`F5A35014-C209-46A4-993A-EB56DE7530A1`UUIDPower Boss
`6ED722A7-9240-48A5-B479-31EEF723D7CF`UUIDVirtual Sensor
`16CAF1B7-DD38-40ED-B1C1-1B8A1913D531`UUIDCooling mode
`BE84BABF-C4D4-403D-B495-3128FD44dAC1`UUIDHDC
`available_uuids`RO사용 가능한 policy UUID 집합
`current_uuid`RW현재 선택할 policy UUID
`imok`WOFirmware keep-alive에 1로 응답
`odvp*` / `data_vault` / `production_mode`ROStatus variable / binary table / configuration lock

DPTF ACPI Drivers interface
----------------------------

:file:`/sys/bus/platform/devices/<N>/uuids`, where <N>
=INT3400|INTC1040|INTC1041|INTC10A0

``available_uuids`` (RO)
        A set of UUIDs strings presenting available policies
        which should be notified to the firmware when the
        user space can support those policies.

        UUID strings:

        "42A441D6-AE6A-462b-A84B-4A8CE79027D3" : Passive 1

        "3A95C389-E4B8-4629-A526-C52C88626BAE" : Active

        "97C68AE7-15FA-499c-B8C9-5DA81D606E0A" : Critical

        "63BE270F-1C11-48FD-A6F7-3AF253FF3E2D" : Adaptive performance

        "5349962F-71E6-431D-9AE8-0A635B710AEE" : Emergency call

        "9E04115A-AE87-4D1C-9500-0F3E340BFE75" : Passive 2

        "F5A35014-C209-46A4-993A-EB56DE7530A1" : Power Boss

        "6ED722A7-9240-48A5-B479-31EEF723D7CF" : Virtual Sensor

        "16CAF1B7-DD38-40ED-B1C1-1B8A1913D531" : Cooling mode

        "BE84BABF-C4D4-403D-B495-3128FD44dAC1" : HDC

``current_uuid`` (RW)
        User space can write strings from available UUIDs, one at a
        time.

:file:`/sys/bus/platform/devices/<N>/`, where <N>
=INT3400|INTC1040|INTC1041|INTC10A0

``imok`` (WO)
        User space daemon write 1 to respond to firmware event
        for sending keep alive notification. User space receives
        THERMAL_EVENT_KEEP_ALIVE kobject uevent notification when
        firmware calls for user space to respond with imok ACPI
        method.

``odvp*`` (RO)
        Firmware thermal status variable values. Thermal tables
        calls for different processing based on these variable
        values.

``data_vault`` (RO)
        Binary thermal table. Refer to
        https:/github.com/intel/thermal_daemon for decoding
        thermal table.

``production_mode`` (RO)
        When different from zero, manufacturer locked thermal configuration
        from further changes.

ACPI Thermal Relationship table interface

91-116

`/dev/acpi_thermal_rel` device는 표준 ACPI method `_TRT`와 `_ART`를 통해 ACPI thermal relationship table을 읽는 IOCTL interface를 제공합니다.

IOCTL 정의는 `drivers/thermal/intel/int340x_thermal/acpi_thermal_rel.h`에 있습니다. Length 및 record count를 조회한 뒤 binary table을 읽으며, 읽을 길이는 `ioctl()` argument로 전달합니다.

ACPI thermal relationship IOCTL
IOCTL동작
`ACPI_THERMAL_GET_TRT_LEN`TRT table 길이 조회
`ACPI_THERMAL_GET_ART_LEN`ART table 길이 조회
`ACPI_THERMAL_GET_TRT_COUNT`TRT table record 수 조회
`ACPI_THERMAL_GET_ART_COUNT`ART table record 수 조회
`ACPI_THERMAL_GET_TRT`Argument로 지정한 길이만큼 binary TRT table 읽기
`ACPI_THERMAL_GET_ART`Argument로 지정한 길이만큼 binary ART table 읽기

ACPI Thermal Relationship table interface
------------------------------------------

:file:`/dev/acpi_thermal_rel`

        This device provides IOCTL interface to read standard ACPI
        thermal relationship tables via ACPI methods _TRT and _ART.
        These IOCTLs are defined in
        drivers/thermal/intel/int340x_thermal/acpi_thermal_rel.h

        IOCTLs:

        ACPI_THERMAL_GET_TRT_LEN: Get length of TRT table

        ACPI_THERMAL_GET_ART_LEN: Get length of ART table

        ACPI_THERMAL_GET_TRT_COUNT: Number of records in TRT table

        ACPI_THERMAL_GET_ART_COUNT: Number of records in ART table

        ACPI_THERMAL_GET_TRT: Read binary TRT table, length to read is
        provided via argument to ioctl().

        ACPI_THERMAL_GET_ART: Read binary ART table, length to read is
        provided via argument to ioctl().

DPTF ACPI sensor와 cooling driver

117-128

DPTF Sensor driver는 표준 thermal sysfs의 `thermal_zone`으로 표시됩니다.

DPTF cooling driver는 표준 thermal sysfs의 `cooling_device`로 표시됩니다.

DPTF 표준 thermal sysfs 표현
Driver 종류표준 sysfs 객체
DPTF ACPI Sensor driver`thermal_zone`
DPTF ACPI Cooling driver`cooling_device`

DPTF ACPI Sensor drivers
-------------------------

DPTF Sensor drivers are presented as standard thermal sysfs thermal_zone.


DPTF ACPI Cooling drivers
--------------------------

DPTF cooling drivers are presented as standard thermal sysfs cooling_device.

Processor thermal PCI power limit interface

129-176

Processor thermal PCI driver의 power limit 속성은 `/sys/bus/pci/devices/0000:00:04.0/power_limits/` 아래에 있습니다. Powercap ABI는 `Documentation/power/powercap/powercap.rst`를 참조합니다.

Intel RAPL constraint 0과 1 각각에 대해 power limit의 최대값, 증감 step, 최소값, time window의 최소·최대값을 read-only로 제공합니다. Power 단위는 micro-watt(`uw`), time window 단위는 microsecond(`us`)입니다.

Read-only `power_floor_status`가 1이면 현재 configuration에서 system power floor에 도달한 것입니다. 전력을 더 줄이려면 configuration을 바꿔야 합니다.

Read-write `power_floor_enable`을 1로 설정하면 power floor status 읽기와 notification을 활성화합니다. Notification은 `power_floor_status` 값이 변할 때 발생합니다.

Intel RAPL power limit 속성
속성권한의미
`power_limit_0_max_uw` / `power_limit_0_min_uw`ROConstraint 0 power limit 최대/최소
`power_limit_0_step_uw`ROConstraint 0 power limit 증감 단위
`power_limit_0_tmin_us` / `power_limit_0_tmax_us`ROConstraint 0 time window 최소/최대
`power_limit_1_max_uw` / `power_limit_1_min_uw`ROConstraint 1 power limit 최대/최소
`power_limit_1_step_uw`ROConstraint 1 power limit 증감 단위
`power_limit_1_tmin_us` / `power_limit_1_tmax_us`ROConstraint 1 time window 최소/최대
`power_floor_status`RO1이면 현재 system power floor 도달
`power_floor_enable`RW1이면 status 읽기와 변경 notification 활성화

DPTF Processor thermal PCI Driver interface
--------------------------------------------

:file:`/sys/bus/pci/devices/0000\:00\:04.0/power_limits/`

Refer to Documentation/power/powercap/powercap.rst for powercap
ABI.

``power_limit_0_max_uw`` (RO)
        Maximum powercap sysfs constraint_0_power_limit_uw for Intel RAPL

``power_limit_0_step_uw`` (RO)
        Power limit increment/decrements for Intel RAPL constraint 0 power limit

``power_limit_0_min_uw`` (RO)
        Minimum powercap sysfs constraint_0_power_limit_uw for Intel RAPL

``power_limit_0_tmin_us`` (RO)
        Minimum powercap sysfs constraint_0_time_window_us for Intel RAPL

``power_limit_0_tmax_us`` (RO)
        Maximum powercap sysfs constraint_0_time_window_us for Intel RAPL

``power_limit_1_max_uw`` (RO)
        Maximum powercap sysfs constraint_1_power_limit_uw for Intel RAPL

``power_limit_1_step_uw`` (RO)
        Power limit increment/decrements for Intel RAPL constraint 1 power limit

``power_limit_1_min_uw`` (RO)
        Minimum powercap sysfs constraint_1_power_limit_uw for Intel RAPL

``power_limit_1_tmin_us`` (RO)
        Minimum powercap sysfs constraint_1_time_window_us for Intel RAPL

``power_limit_1_tmax_us`` (RO)
        Maximum powercap sysfs constraint_1_time_window_us for Intel RAPL

``power_floor_status`` (RO)
        When set to 1, the power floor of the system in the current
        configuration has been reached.  It needs to be reconfigured to allow
        power to be reduced any further.

``power_floor_enable`` (RW)
        When set to 1, enable reading and notification of the power floor
        status. Notifications are triggered for the power_floor_status
        attribute value changes.

TCC, workload request와 platform temperature control

177-223

PCI thermal device root의 read-write `tcc_offset_degree_celsius`는 hardware가 CPU throttling을 시작하는 critical temperature로부터의 TCC offset입니다.

`workload_request` interface의 read-only `workload_available_types`는 `idle`, `bursty`, `sustained` 같은 사용 가능한 workload type을 제공합니다. User space는 현재 실행 중인 유형 하나를 read-write `workload_type`으로 지정합니다.

`ptc_0_control`, `ptc_1_control`, `ptc_2_control`의 모든 control을 갱신하려면 admin privilege가 필요합니다. `enable`은 1로 platform temperature control hardware를 활성화하고 0으로 비활성화합니다.

`temperature_target`은 hardware가 temperature control에 사용할 새 target을 milli degree Celsius 단위로 설정합니다.

`thermal_tolerance`의 범위는 0부터 7입니다. 0은 temperature overshoot를 피하는 가장 공격적인 control이고, 7은 overshoot를 감수하면서 performance를 선호하는 완만한 방식입니다. 이 level은 선형 비율이 아니므로 3이 0보다 performance가 반드시 50% 향상됨을 뜻하지 않습니다.

Platform temperature control은 하나의 user-level manager가 소유하고 관리해야 합니다. 여러 application이 서로 다른 target을 쓰면 예상하지 못한 동작이 발생할 수 있습니다.

Processor thermal platform control
경로 또는 속성권한동작
`tcc_offset_degree_celsius`RWCritical temperature 기준 TCC offset
`workload_available_types`RO사용 가능한 workload type
`workload_type`RW현재 workload type 지정
`ptc_0_control` / `ptc_1_control` / `ptc_2_control`AdminPlatform temperature control group
`enable`RW1 enable, 0 disable
`temperature_target`RWTarget temperature, milli degree Celsius
`thermal_tolerance`RW0 aggressive에서 7 performance-favoring까지

:file:`/sys/bus/pci/devices/0000\:00\:04.0/`

``tcc_offset_degree_celsius`` (RW)
        TCC offset from the critical temperature where hardware will throttle
        CPU.

:file:`/sys/bus/pci/devices/0000\:00\:04.0/workload_request`

``workload_available_types`` (RO)
        Available workload types. User space can specify one of the workload type
        it is currently executing via workload_type. For example: idle, bursty,
        sustained etc.

``workload_type`` (RW)
        User space can specify any one of the available workload type using
        this interface.

:file:`/sys/bus/pci/devices/0000\:00\:04.0/ptc_0_control`
:file:`/sys/bus/pci/devices/0000\:00\:04.0/ptc_1_control`
:file:`/sys/bus/pci/devices/0000\:00\:04.0/ptc_2_control`

All these controls needs admin privilege to update.

``enable`` (RW)
        1 for enable, 0 for disable. Shows the current enable status of
        platform temperature control feature. User space can enable/disable
        hardware controls.

``temperature_target`` (RW)
        Update a new temperature target in milli degree celsius for hardware to
        use for the temperature control.

``thermal_tolerance`` (RW)
        This attribute ranges from 0 to 7, where 0 represents
        the most aggressive control to avoid any temperature overshoots, and
        7 represents a more graceful approach, favoring performance even at
        the expense of temperature overshoots.
        Note: This level may not scale linearly. For example, a value of 3 does
        not necessarily imply a 50% improvement in performance compared to a
        value of 0.

Given that this is platform temperature control, it is expected that a
single user-level manager owns and manages the controls. If multiple
user-level software applications attempt to write different targets, it
can lead to unexpected behavior.

Processor thermal RFIM interface

224-257

RFIM interface는 WiFi와 5G의 RF interference를 피하기 위해 FIVR(Fully Integrated Voltage Regulator), DDR(Double Data Rate), DLVR(Digital Linear Voltage Regulator) frequency를 조정합니다.

Switching voltage regulator는 fundamental frequency와 harmonic에서 방사 EMI 또는 RFI를 생성합니다. 일부 harmonic은 notebook PC 같은 host system에 통합된 민감한 Wi-Fi 및 cellular receiver를 방해할 수 있습니다.

완화 방법 하나는 SoC integrated VR(IVR) switching frequency를 작은 비율만큼 이동시켜 switching noise harmonic을 radio channel에서 벗어나게 하는 것입니다. OEM 또는 ODM은 IVR performance에 영향을 주지 않는 범위에서 driver로 SoC IVR 동작을 제어할 수 있습니다.

일부 제품은 FIVR 대신 DLVR을 switching voltage regulator로 사용하므로, 이 경우 FIVR가 아니라 DLVR 속성을 조정해야 합니다.

Frequency 이동 과정에서 추가 clock noise가 생길 수 있으며 spread spectrum percentage로 이를 보상합니다. Signal transmission bandwidth를 넓혀 interference, noise, signal fading의 영향을 줄이고 regulatory compliance를 충족합니다.

DDR IO interface의 DRAM device와 power plane도 data rate에서 EMI를 만들 수 있습니다. DDR-RFIM은 DDR로 인한 강한 RFI가 있고, CPU power management가 DDR data rate 변경을 제한하지 않으며, PC ODM이 BIOS에서 Wi-Fi용 기능을 활성화한 경우 DDR data rate를 변경합니다.

RF interference 완화 경로
FIVR or DLVR switching harmonicsWi-Fi and 5G interference
Shift IVR switching frequency by a small percentageMove harmonic away from radio channel
Frequency shiftAdditional clock noise
Adjust spread spectrum percentReduce interference and meet compliance
DDR-generated RFI with BIOS enableRestrict or change DDR data rate

RFIM이 voltage regulator와 DDR frequency를 조정하는 이유와 조건입니다.

DPTF Processor thermal RFIM interface
--------------------------------------------

RFIM interface allows adjustment of FIVR (Fully Integrated Voltage Regulator),
DDR (Double Data Rate) and DLVR (Digital Linear Voltage Regulator)
frequencies to avoid RF interference with WiFi and 5G.

Switching voltage regulators (VR) generate radiated EMI or RFI at the
fundamental frequency and its harmonics. Some harmonics may interfere
with very sensitive wireless receivers such as Wi-Fi and cellular that
are integrated into host systems like notebook PCs.  One of mitigation
methods is requesting SOC integrated VR (IVR) switching frequency to a
small % and shift away the switching noise harmonic interference from
radio channels.  OEM or ODMs can use the driver to control SOC IVR
operation within the range where it does not impact IVR performance.

Some products use DLVR instead of FIVR as switching voltage regulator.
In this case attributes of DLVR must be adjusted instead of FIVR.

While shifting the frequencies additional clock noise can be introduced,
which is compensated by adjusting Spread spectrum percent. This helps
to reduce the clock noise to meet regulatory compliance. This spreading
% increases bandwidth of signal transmission and hence reduces the
effects of interference, noise and signal fading.

DRAM devices of DDR IO interface and their power plane can generate EMI
at the data rates. Similar to IVR control mechanism, Intel offers a
mechanism by which DDR data rates can be changed if several conditions
are met: there is strong RFI interference because of DDR; CPU power
management has no other restriction in changing DDR data rates;
PC ODMs enable this feature (real time DDR RFI Mitigation referred to as
DDR-RFIM) for Wi-Fi from BIOS.

FIVR 속성

258-283

FIVR 속성은 `/sys/bus/pci/devices/0000:00:04.0/fivr/`에 있습니다. VCO reference code는 FIVR switching frequency를 제어하는 11-bit field이며 low 3-bit와 high 8-bit로 나뉩니다.

Spread spectrum percentage와 clocking enable을 설정할 수 있습니다. `rfi_vco_ref_code`는 원문에서 RW로 표기되어 있지만 설명상 현재 FIVR switching frequency를 반영하는 read-only status register입니다. `fivr_fffc_rev`는 FIVR hardware revision을 나타냅니다.

FIVR RFIM 속성
속성권한의미
`vco_ref_code_lo`RW11-bit VCO reference code의 3-bit LSB
`vco_ref_code_hi`RW11-bit VCO reference code의 8-bit MSB
`spread_spectrum_pct`RWFIVR spread spectrum clocking percentage
`spread_spectrum_clk_enable`RWFIVR spread spectrum clocking enable/disable
`rfi_vco_ref_code`RW 표기현재 FIVR switching frequency status
`fivr_fffc_rev`RWFIVR hardware revision

FIVR attributes

:file:`/sys/bus/pci/devices/0000\:00\:04.0/fivr/`

``vco_ref_code_lo`` (RW)
        The VCO reference code is an 11-bit field and controls the FIVR
        switching frequency. This is the 3-bit LSB field.

``vco_ref_code_hi`` (RW)
        The VCO reference code is an 11-bit field and controls the FIVR
        switching frequency. This is the 8-bit MSB field.

``spread_spectrum_pct`` (RW)
        Set the FIVR spread spectrum clocking percentage

``spread_spectrum_clk_enable`` (RW)
        Enable/disable of the FIVR spread spectrum clocking feature

``rfi_vco_ref_code`` (RW)
        This field is a read only status register which reflects the
        current FIVR switching frequency

``fivr_fffc_rev`` (RW)
        This field indicated the revision of the FIVR HW.

DVFS 속성

284-316

DVFS 속성은 `/sys/bus/pci/devices/0000:00:04.0/dvfs/`에 있습니다.

특정 DDR data rate 제한을 요청하려면 `rfi_restriction_run_busy`를 1로 설정합니다. Operation 후 자동으로 0으로 reset됩니다. `rfi_restriction_err_code`는 0이면 request accepted, 1이면 feature disabled, 2이면 허용된 수보다 더 많은 point를 제한한 request임을 뜻합니다.

RFI protection을 위한 restricted DDR data rate의 lower limit은 `rfi_restriction_data_rate_Delta`, upper limit은 `rfi_restriction_data_rate_Base`입니다.

Read-only `ddr_data_rate_point_0`부터 `ddr_data_rate_point_3`까지는 DDR data rate selection의 첫째부터 넷째 point를 제공합니다. `rfi_disable`은 DDR rate change feature를 비활성화합니다.

DVFS DDR-RFIM 속성
속성권한의미
`rfi_restriction_run_busy`RW1로 DDR rate 제한 요청, 완료 후 0으로 self-reset
`rfi_restriction_err_code`RW0 accepted, 1 disabled, 2 too many restricted points
`rfi_restriction_data_rate_Delta`RWRestricted DDR data rate lower limit
`rfi_restriction_data_rate_Base`RWRestricted DDR data rate upper limit
`ddr_data_rate_point_0` ... `ddr_data_rate_point_3`RODDR data rate selection 1st ... 4th point
`rfi_disable`RWDDR rate change feature 비활성화

DVFS attributes

:file:`/sys/bus/pci/devices/0000\:00\:04.0/dvfs/`

``rfi_restriction_run_busy`` (RW)
        Request the restriction of specific DDR data rate and set this
        value 1. Self reset to 0 after operation.

``rfi_restriction_err_code`` (RW)
        0 :Request is accepted, 1:Feature disabled,
        2: the request restricts more points than it is allowed

``rfi_restriction_data_rate_Delta`` (RW)
        Restricted DDR data rate for RFI protection: Lower Limit

``rfi_restriction_data_rate_Base`` (RW)
        Restricted DDR data rate for RFI protection: Upper Limit

``ddr_data_rate_point_0`` (RO)
        DDR data rate selection 1st point

``ddr_data_rate_point_1`` (RO)
        DDR data rate selection 2nd point

``ddr_data_rate_point_2`` (RO)
        DDR data rate selection 3rd point

``ddr_data_rate_point_3`` (RO)
        DDR data rate selection 4th point

``rfi_disable (RW)``
        Disable DDR rate change feature

DLVR 속성

317-348

DLVR 속성은 `/sys/bus/pci/devices/0000:00:04.0/dlvr/`에 있습니다. Read-only `dlvr_hardware_rev`는 hardware revision, `dlvr_freq_mhz`는 현재 DLVR PLL frequency를 MHz 단위로 표시합니다.

`dlvr_freq_select`로 DLVR PLL clock frequency를 설정하고 `dlvr_rfim_enable`로 활성화하면 `dlvr_freq_mhz`가 현재 frequency를 보여 줍니다. `dlvr_pll_busy`가 설정되어 있으면 PLL은 frequency change를 받을 수 없습니다.

`dlvr_rfim_enable`은 0이면 RF frequency hopping을 끄고 1이면 켭니다. `dlvr_spread_spectrum_pct`는 spread spectrum percentage를 설정합니다.

`dlvr_control_mode` 0은 down spread, 1은 center spread를 선택합니다. `dlvr_control_lock`을 1로 설정하면 이후 write는 무시됩니다.

DLVR RFIM 속성
속성권한의미
`dlvr_hardware_rev`RODLVR hardware revision
`dlvr_freq_mhz`RO현재 DLVR PLL frequency, MHz
`dlvr_freq_select`RWDLVR PLL clock frequency 설정
`dlvr_pll_busy`RO설정 중이면 frequency change 거부
`dlvr_rfim_enable`RW0 hopping disable, 1 enable
`dlvr_spread_spectrum_pct`RWDLVR spread spectrum percentage
`dlvr_control_mode`RW0 down spread, 1 center spread
`dlvr_control_lock`RW1이면 이후 write 무시

DLVR attributes

:file:`/sys/bus/pci/devices/0000\:00\:04.0/dlvr/`

``dlvr_hardware_rev`` (RO)
        DLVR hardware revision.

``dlvr_freq_mhz`` (RO)
        Current DLVR PLL frequency in MHz.

``dlvr_freq_select`` (RW)
        Sets DLVR PLL clock frequency. Once set, and enabled via
        dlvr_rfim_enable, the dlvr_freq_mhz will show the current
        DLVR PLL frequency.

``dlvr_pll_busy`` (RO)
        PLL can't accept frequency change when set.

``dlvr_rfim_enable`` (RW)
        0: Disable RF frequency hopping, 1: Enable RF frequency hopping.

``dlvr_spread_spectrum_pct`` (RW)
        Sets DLVR spread spectrum percent value.

``dlvr_control_mode`` (RW)
        Specifies how frequencies are spread using spread spectrum.
        0: Down spread,
        1: Spread in the Center.

``dlvr_control_lock`` (RW)
    1: future writes are ignored.

Meteor Lake workload type hint

359-411

Meteor Lake processor generation의 firmware는 workload type을 식별해 OS에 hint를 전달할 수 있습니다. 전용 sysfs interface를 통해 user space는 이 hint를 얻고 제공 rate를 제어합니다.

User space는 현재 hint를 얻기 위해 `workload_type_index`를 polling하거나, 해당 attribute 값이 갱신될 때마다 notification을 받을 수 있습니다.

경로는 `/sys/bus/pci/devices/0000:00:04.0/workload_hint/`입니다. 모든 Intel client processor에서 segment 0, bus 0, device 4, function 0이 processor thermal device용으로 예약되므로 processor generation에 따라 경로가 바뀌지 않습니다.

Read-write `workload_hint_enable`은 firmware가 workload type hint를 user space로 보내도록 활성화합니다.

Read-write `notification_delay_ms`는 firmware가 OS에 알리기 전의 최소 delay로 notification rate를 제어합니다. Firmware의 workload prediction 변경과 OS notification 사이의 시간이며 default는 1024 ms, 0은 invalid입니다. Firmware programming을 단순화하기 위해 가장 가까운 2의 거듭제곱으로 올림하며 read 값은 실제 적용된 값을 보여 줍니다.

Read-only `workload_type_index`는 예측한 workload type index입니다. 기존 sysfs attribute change notification mechanism으로 변경 notification을 받을 수 있습니다.

Meteor Lake workload type index
Index유형의미
0IdleTask가 없고 power 및 idle residency가 오랫동안 일관되게 낮음
1Battery LifePower는 비교적 낮지만 장시간 video playback 같은 task를 활발히 수행할 수 있음
2SustainedIdle이 거의 없이 높은 power가 오래 지속되어 결국 RAPL Power Limit 1과 2를 소진
3Bursty평균 power는 비교적 일정하지만 짧은 activity burst 사이의 idle이 보통 RAPL Power Limit 1 소진을 막음
4Unknown분류할 수 없음

`workload_type_index` 변경은 sysfs notification으로 전달됩니다.

Workload Type Hints
----------------------------------------

The firmware in Meteor Lake processor generation is capable of identifying
workload type and passing hints regarding it to the OS. A special sysfs
interface is provided to allow user space to obtain workload type hints from
the firmware and control the rate at which they are provided.

User space can poll attribute "workload_type_index" for the current hint or
can receive a notification whenever the value of this attribute is updated.

file:`/sys/bus/pci/devices/0000:00:04.0/workload_hint/`
Segment 0, bus 0, device 4, function 0 is reserved for the processor thermal
device on all Intel client processors. So, the above path doesn't change
based on the processor generation.

``workload_hint_enable`` (RW)
        Enable firmware to send workload type hints to user space.

``notification_delay_ms`` (RW)
        Minimum delay in milliseconds before firmware will notify OS. This is
        for the rate control of notifications. This delay is between changing
        the workload type prediction in the firmware and notifying the OS about
        the change. The default delay is 1024 ms. The delay of 0 is invalid.
        The delay is rounded up to the nearest power of 2 to simplify firmware
        programming of the delay value. The read of notification_delay_ms
        attribute shows the effective value used.

``workload_type_index`` (RO)
        Predicted workload type index. User space can get notification of
        change via existing sysfs attribute change notification mechanism.

        The supported index values and their meaning for the Meteor Lake
        processor generation are as follows:

        0 -  Idle: System performs no tasks, power and idle residency are
                consistently low for long periods of time.

        1 – Battery Life: Power is relatively low, but the processor may
                still be actively performing a task, such as video playback for
                a long period of time.

        2 – Sustained: Power level that is relatively high for a long period
                of time, with very few to no periods of idleness, which will
                eventually exhaust RAPL Power Limit 1 and 2.

        3 – Bursty: Consumes a relatively constant average amount of power, but
                periods of relative idleness are interrupted by bursts of
                activity. The bursts are relatively short and the periods of
                relative idleness between them typically prevent RAPL Power
                Limit 1 from being exhausted.

        4 – Unknown: Can't classify.