1thermal-conf.xml(5) File Formats Manual thermal-conf.xml(5)
2
6 thermal-conf.xml - Configuration file for thermal daemon
7
9 $(TDCONFDIR)/etc/thermald/thermal-conf.xml
10
13 thermal-conf.xml is a configuration file for the thermal daemon. It is
14 used to configure thermal sensors, zone and cooling devices.The loca‐
15 tion of this file depends on the configuration option used during build
16 time.
17 The terminology used in this file conforms to "Advanced Configuration
19 and Power Interface Specification". The ACPI thermal model is based
20 around conceptual platform regions called thermal zones that physically
21 contain devices, thermal sensors, and cooling controls. For example of
22 a thermal zone can be a CPU or a laptop cover. A zone can contain mul‐
23 tiple sensors for monitoring temperature. A cooling device provides
24 interface to reduce the temperature of a source device, which causes
25 increase in the temperature. An example of a cooling device is a FAN or
26 some Linux driver which can throttle the source device.
27 A thermal zone configuration includes one or more trip points. A trip
29 point is a temperature at which a cooling device needs to be activated.
30 A cooling device can be either active or passive. An example of an
32 active device is a FAN, which will not reduce performance at the cost
33 of consuming more power and noise. A passive device uses performance
34 throttling to control temperature. In addition to cooling devices
35 present in the thermal sysfs, the following cooling devices are built
36 into the thermald, which can be used as valid cooling device type:
37 - rapl_controller
39 - intel_pstate
41 - cpufreq
43 - LCD
45 The thermal sysfs under Linux (/sys/class/thermal) provides a way to
47 represent per platform ACPI configuration. The kernel thermal governor
48 uses this data to keep the platform thermals under control. But there
49 are some limitations, which thermald tries to resolve. For example:
50 - If the ACPI data is not optimized or buggy. In this case thermal-
52 conf.xml can be used to correct the behavior without change in BIOS.
53 - There may be thermal zones exposed by the thermal sysfs without asso‐
55 ciated cooling actions. In this case thermal conf.xml can be used to
56 tie the cooling devices to those zones.
57 - The best cooling method may not be in the thermal sysfs. In this case
59 thermal-conf.xml can be used to bind a zone to an external cooling
60 device.
61 - Specify thermal relationships. A zone can be influenced by multiple
63 source devices with varying degrees. In this case thermal-conf.xml can
64 be used to define the relative influence for apply compensation.
65
68 The configuration file format conforms to XML specifications. A set of
69 tags defined to define platform, sensors, zones, cooling devices and
70 trip points.
71 <ThermalConfiguration>
73 <Platform>
75 <Name>Example Platform Name</Name>
77 <!--UUID is optional, if present this will be matched. Both prod‐
79 uct name and UUID can contain wild card "*", which matches any plat‐
80 form.-->
81 <UUID>Example UUID</UUID>
83 configuration file format conforms to XML specifications. A set of
85 tags defined to define platform, sensors, zones, cooling
86 devices and trip points.
87 <ThermalConfiguration>
89 <Platform>
91 <ProductName>Example Product Name</ProductName>
94 <Preference>QUIET|PERFORMANCE</Preference>
96 <!-Quiet mode will only use passive cooling device. "PERFORMANCE"
98 will only select active devices .-->
99 <ThermalSensors>
101 <ThermalSensor>
103 <!-- New Sensor with a type and path -->
105 <Type>example_sensor_1</Type>
107 <Path>/some_path</Path>
109 <AsyncCapable>0</AsyncCapable>
111 </ThermalSensor>
113 <ThermalSensor>
115 <!-- Already present in thermal sysfs, enable this or
117 add/change config For example, here we are indicating that sensor can
118 do async events to avoid polling
119 -->
120 <Type>example_thermal_sysfs_sensor</Type>
122 <!-- If async capable, then we don't need to poll -->
124 <AsyncCapable>1</AsyncCapable>
126 </ThermalSensor>
128 </ThermalSensors>
130 <ThermalZones>
132 <ThermalZone>
134 <Type>Example Zone type</Type>
136 <TripPoints>
138 <TripPoint>
140 <SensorType>example_sensor_1</SensorType>
142 <!-- Temperature at which to take action -->
144 <Temperature> 75000 </Temperature>
146 <!-- max/passive/active If a MAX type is spec‐
148 ified, then daemon will use PID control to aggressively throttle to
149 avoid reaching this temp.-->
150 <type>max</type>
152 <!-- SEQUENTIAL | PARALLEL. When a trip point
154 temp is violated, then number of cooling devices can be activated. If
155 control type is SEQUENTIAL then, it will exhaust first cooling device
156 before trying next. -->
157 <ControlType>SEQUENTIAL</ControlType>
159 <CoolingDevice>
161 <index>1</index>
163 <type>example_cooling_device</type>
165 <!-- Influence will be used order cooling
167 devices. First cooling device will be used, which has highest influ‐
168 ence. -->
169 <influence> 100 </influence>
171 <!-- Delay in using this cdev, this takes
173 some time too actually cool a zone -->
174 <SamplingPeriod> 12 </SamplingPeriod>
176 <!-- Set a specific state of this cooling
178 device when this trip is violated -->
179 <TargetState> 6 </TargetState>
181 </CoolingDevice>
183 </TripPoint>
185 </TripPoints>
187 </ThermalZone>
189 </ThermalZones>
191 <CoolingDevices>
193 <CoolingDevice>
195 <!-- Cooling device can be specified by a type and
197 optionally a sysfs path. If the type is already present in thermal
198 sysfs, there is no need of a path. Compensation can use min/max and
199 step size to increasing cool the system. Debounce period can be used to
200 force a waiting period for action. -->
201 <Type>example_cooling_device</Type>
203 <MinState>0</MinState>
205 <IncDecStep>10</IncDecStep>
207 <ReadBack> 0 </ReadBack>
209 <MaxState>50</MaxState>
211 <DebouncePeriod>5000</DebouncePeriod>
213 <!-- If there are no PID parameters, compensation
215 increase step wise and exponentially (if single step is not able to
216 change trend). Alternatively a PID parameters can be specified then
217 next step will use PID calculation using provided PID constants. -->
218 <PidControl>
220 <kp>0.001</kp>
222 <kd>0.0001</kd>
224 <ki>0.0001</ki>
226 </PidControl>
228 <!-- Write some prefix attached to state value, like
230 below the prefix is "level ". It will preserve spaces as entered when
231 writing to sysfs -->
232 <WritePrefix>level </WritePrefix>
233 </CoolingDevice>
234 </CoolingDevices>
236 </Platform>
238 </ThermalConfiguration>
240
242 Example 1: This is a very simple configuration, to change the passive
243 limit on the CPU. Instead of default, this new temperature 86C in the
244 configuration is used. This will start cooling, once the temperature
245 reaches 86C.
246 <?xml version="1.0"?>
248 <ThermalConfiguration>
250 <Platform>
252 <Name>Overide CPU default passive</Name>
254 <ProductName>*</ProductName>
256 <Preference>QUIET</Preference>
258 <ThermalZones>
260 <ThermalZone>
262 <Type>cpu</Type>
264 <TripPoints>
266 <TripPoint>
268 <Tempera‐
270 ture>86000</Temperature>
271 <type>pas‐
273 sive</type>
274 </TripPoint>
276 </TripPoints>
278 </ThermalZone>
280 </ThermalZones>
282 </Platform>
284 </ThermalConfiguration>
286 Example 2: In this configuration, we are controlling backlight when
288 some sensor "SEN2" reaches 60C. Here "LCD" is a standard cooling
289 device, which uses Linux backlight sysfs interface. "LCD_Zone" is a
290 valid thermal zone in Linux thermal sysfs on the test platform, hence
291 we don't need to provide path for sysfs for "LCD_Zone". The Linux ther‐
292 mal sysfs is already parsed and loaded by thermald program.
293 <?xml version="1.0"?>
295 <ThermalConfiguration>
297 <Platform>
299 <Name>Change Backlight</Name>
301 <ProductName>*</ProductName>
303 <Preference>QUIET</Preference>
305 <ThermalZones>
307 <ThermalZone>
309 <Type>LCD_Zone</Type>
311 <TripPoints>
313 <TripPoint>
315 <SensorType>SEN2</SensorType>
317 <Temperature>60000</Temperature>
319 <type>passive</type>
321 <CoolingDevice>
323 <Type>LCD</Type>
325 </CoolingDevice>
327 </TripPoint>
329 </TripPoints>
331 </ThermalZone>
333 </ThermalZones>
335 </Platform>
337 </ThermalConfiguration>
339 Example 3: In this example Lenovo Thinkpad X220 and fan speed is con‐
341 trolled. Here a cooling device "_Fan", can be controlled via sysfs
342 /sys/devices/platform/thinkpad_hwmon/pwm1. When the x86_pkg_temp
343 reaches 45C, Fan is started with increasing speeds, if the tem‐
344 perature can't be controlled at 45C.
345 <?xml version="1.0"?>
347 <ThermalConfiguration>
349 <Platform>
351 <Name>Lenovo ThinkPad X220</Name>
353 <ProductName>*</ProductName>
355 <Preference>QUIET</Preference>
357 <ThermalZones>
359 <ThermalZone>
361 <Type>x86_pkg_temp</Type>
363 <TripPoints>
365 <TripPoint>
367 <Sen‐
369 sorType>x86_pkg_temp</SensorType>
370 <Tem‐
372 perature>45000</Temperature>
373 <type>pas‐
375 sive</type>
376 <Con‐
378 trolType>SEQUENTIAL</ControlType>
379 <Cool‐
381 ingDevice>
382 <index>1</index>
384 <type>_Fan</type>
386 <influ‐
388 ence> 100 </influence>
389 <Sam‐
391 plingPeriod> 12 </SamplingPeriod>
392 </Cool‐
394 ingDevice>
395 </TripPoint>
397 </TripPoints>
399 </ThermalZone>
401 </ThermalZones>
403 <CoolingDevices>
405 <CoolingDevice>
407 <Type>_Fan</Type>
409 <Path>/sys/devices/plat‐
411 form/thinkpad_hwmon/pwm1</Path>
412 <MinState>0</MinState>
414 <IncDecStep>30</IncDecStep>
416 <ReadBack> 0 </ReadBack>
418 <MaxState>255</MaxState>
420 <DebouncePeriod>5</DebouncePeriod>
422 </CoolingDevice>
424 </CoolingDevices>
426 </Platform>
428 </ThermalConfiguration>
430 Example 4: The following example shows how PID can be used. Here once
432 temperature exceeds 80C, compensation is calculated using PID using 80C
433 as set point of PID. The compensation depends on error from the set
434 point. Here the default built in processor cooling device is used with
435 min state as 0 and max state as 10.
436 <?xml version="1.0"?>
438 <ThermalConfiguration>
440 <Platform>
442 <Name>Use PID param </Name>
444 <ProductName>*</ProductName>
446 <Preference>QUIET</Preference>
448 <ThermalZones>
450 <ThermalZone>
452 <Type>x86_pkg_temp</Type>
454 <TripPoints>
456 <TripPoint>
458 <Sen‐
460 sorType>x86_pkg_temp</SensorType>
461 <Tem‐
463 perature>80000</Temperature>
464 <type>pas‐
466 sive</type>
467 <Con‐
469 trolType>SEQUENTIAL</ControlType>
470 <Cool‐
472 ingDevice>
473 <type>Processor</type>
475 </Cool‐
477 ingDevice>
478 </TripPoint>
480 </TripPoints>
482 </ThermalZone>
484 </ThermalZones>
486 <CoolingDevices>
488 <CoolingDevice>
490 <Type>Processor</Type>
492 <PidControl>
494 <kp>0.0002</kp>
496 <kd>0</kd>
498 <ki>0</ki>
500 </PidControl>
502 </CoolingDevice>
504 </CoolingDevices>
506 </Platform>
508 </ThermalConfiguration>
510 Example 5: The following example shows how to control Fan when
513 the sysfs expects some string prefix. For example instead of
514 just write a number to fan control sysfs, the interface requires
515 "level " in front of the speed index value.
516 <?xml version="1.0"?>
518 <ThermalConfiguration>
520 <Platform>
522 <Name>Use Fan control first then CPU throttle </Name>
524 <ProductName>*</ProductName>
526 <Preference>QUIET</Preference>
528 <ThermalZones>
530 <ThermalZone>
532 <Type>x86_pkg_temp</Type>
534 <TripPoints>
536 <Trip‐
538 Point>
539 <Sen‐
541 sorType>x86_pkg_temp</SensorType>
542 <Tem‐
544 perature>80000</Temperature>
545 <type>pas‐
547 sive</type>
548 <Con‐
550 trolType>SEQUENTIAL</ControlType>
551 <Cool‐
553 ingDevice>
554 <type>_fan_</type>
556 </Cool‐
558 ingDevice>
559 </Trip‐
561 Point>
562 </TripPoints>
564 </ThermalZone>
566 </ThermalZones>
568 <CoolingDevices>
570 <CoolingDevice>
572 <Type>_fan_</Type>
574 <Path>/proc/acpi/ibm/fan</Path>
576 <WritePrefix>level </WritePrefix>
578 <MinState>0</MinState>
580 <MaxState>5</MaxState>
582 <DebouncePeriod>10</DebouncePeriod>
584 </CoolingDevice>
586 </CoolingDevices>
588 </Platform>
590 </ThermalConfiguration>
592 Example 6: Similar to example 5, but write different speeds at
594 different temperatures.
595 <?xml version="1.0"?>
597 <ThermalConfiguration>
599 <Platform>
601 <Name>Use Fan control first then CPU throttle </Name>
603 <ProductName>*</ProductName>
605 <Preference>QUIET</Preference>
607 <ThermalZones>
609 <ThermalZone>
611 <Type>x86_pkg_temp</Type>
613 <TripPoints>
615 <Trip‐
617 Point>
618 <Sen‐
620 sorType>x86_pkg_temp</SensorType>
621 <Tem‐
623 perature>80000</Temperature>
624 <type>pas‐
626 sive</type>
627 <Cool‐
629 ingDevice>
630 <type>_fan_</type>
632 <Tar‐
634 getState>1</TargetState>
635 </Cool‐
637 ingDevice>
638 </Trip‐
640 Point>
641 <Trip‐
643 Point>
644 <Sen‐
646 sorType>x86_pkg_temp</SensorType>
647 <Tem‐
649 perature>85000</Temperature>
650 <type>pas‐
652 sive</type>
653 <Cool‐
655 ingDevice>
656 <type>_fan_</type>
658 <Tar‐
660 getState>2</TargetState>
661 </Cool‐
663 ingDevice>
664 </Trip‐
666 Point>
667 </TripPoints>
669 </ThermalZone>
671 </ThermalZones>
673 <CoolingDevices>
675 <CoolingDevice>
677 <Type>_fan_</Type>
679 <Path>/proc/acpi/ibm/fan</Path>
681 <WritePrefix>level </WritePrefix>
683 <MinState>0</MinState>
685 <MaxState>5</MaxState>
687 <DebouncePeriod>10</DebouncePeriod>
689 </CoolingDevice>
691 </CoolingDevices>
693 </Platform>
695 </ThermalConfiguration>
697