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 with‐
55 out associated cooling actions. In this case thermal conf.xml
56 can be used to tie the cooling devices to those zones.
57 - The best cooling method may not be in the thermal sysfs. In
59 this case thermal-conf.xml can be used to bind a zone to an
60 external cooling device.
61 - Specify thermal relationships. A zone can be influenced by
63 multiple source devices with varying degrees. In this case ther‐
64 mal-conf.xml can be used to define the relative influence for
65 apply compensation.
66
69 The configuration file format conforms to XML specifications. A set of
70 tags defined to define platform, sensors, zones, cooling devices and
71 trip points.
72 <ThermalConfiguration>
74 <Platform>
75 <Name>Example Platform Name</Name>
76 <!-- UUID is optional, if present this will be matched. Both product
77 name and UUID can contain wild card "*", which matches any
78 platform. -->
79 <UUID>Example UUID</UUID>
80 <!-- configuration file format conforms to XML specifications. A
81 set of tags defined to define platform, sensors, zones, cooling
82 devices and trip points. -->
83 <ProductName>Example Product Name</ProductName>
84 <Preference>QUIET|PERFORMANCE</Preference>
85 <!-- Quiet mode will only use passive cooling device. "PERFORMANCE"
86 will only select active devices. -->
87 <ThermalSensors>
88 <ThermalSensor>
89 <!-- New Sensor with a type and path -->
90 <Type>example_sensor_1</Type>
91 <Path>/some_path</Path>
92 <AsyncCapable>0</AsyncCapable>
93 </ThermalSensor>
94 <ThermalSensor>
95 <!-- Already present in thermal sysfs, enable this or
96 add/change config For example, here we are indicating
97 that sensor can do async events to avoid polling. -->
98 <Type>example_thermal_sysfs_sensor</Type>
99 <!-- If async capable, then we don't need to poll. -->
100 <AsyncCapable>1</AsyncCapable>
101 </ThermalSensor>
102 </ThermalSensors>
103 <ThermalZones>
104 <ThermalZone>
105 <Type>Example Zone type</Type>
106 <TripPoints>
107 <TripPoint>
108 <SensorType>example_sensor_1</SensorType>
109 <!-- Temperature at which to take action. -->
110 <Temperature> 75000 </Temperature>
111 <!-- max/passive/active If a MAX type is specified, then
112 daemon will use PID control to aggressively throttle
113 to avoid reaching this temp. -->
114 <type>max</type>
115 <!-- SEQUENTIAL | PARALLEL. When a trip point temp is
116 violated, then number of cooling devices can be
117 activated. If control type is SEQUENTIAL then, it
118 will exhaust first cooling device
119 before trying next. -->
120 <ControlType>SEQUENTIAL</ControlType>
121 <CoolingDevice>
122 <index>1</index>
123 <type>example_cooling_device</type>
124 <!-- Influence will be used order cooling devices. First
125 cooling device will be used, which has highest
126 influence. -->
127 <influence> 100 </influence>
128 <!-- Delay in using this cdev, this takes some time too
129 actually cool a zone. -->
130 <SamplingPeriod> 12 </SamplingPeriod>
131 <!-- Set a specific state of this cooling device when this
132 trip is violated. -->
133 <TargetState> 6 </TargetState>
134 </CoolingDevice>
135 </TripPoint>
136 </TripPoints>
137 </ThermalZone>
138 </ThermalZones>
139 <CoolingDevices>
140 <CoolingDevice>
141 <!-- Cooling device can be specified by a type and optionally
142 a sysfs path. If the type is already present in thermal
143 sysfs, there is no need of a path. Compensation can use
144 min/max and step size to increasing cool the system.
145 Debounce period can be used to force a waiting period
146 for action. -->
147 <Type>example_cooling_device</Type>
148 <MinState>0</MinState>
149 <IncDecStep>10</IncDecStep>
150 <ReadBack> 0 </ReadBack>
151 <MaxState>50</MaxState>
152 <DebouncePeriod>5000</DebouncePeriod>
153 <!-- If there are no PID parameters, compensation increase step
154 wise and exponentially (if single step is not able to
155 change trend).
156 Alternatively a PID parameters can be specified then next
157 step will use PID calculation using provided PID
158 constants. -->
159 <PidControl>
160 <kp>0.001</kp>
161 <kd>0.0001</kd>
162 <ki>0.0001</ki>
163 </PidControl>
164 <!-- Write some prefix attached to state value, like below the
165 prefix is "level ". It will preserve spaces as entered
166 when writing to sysfs. -->
167 <WritePrefix>level </WritePrefix>
168 </CoolingDevice>
169 </CoolingDevices>
170 </Platform>
171 </ThermalConfiguration>
172
174 Example 1: This is a very simple configuration, to change the passive
175 limit on the CPU. Instead of default, this new temperature 86C in the
176 configuration is used. This will start cooling, once the temperature
177 reaches 86C.
178 <?xml version="1.0"?>
180 <ThermalConfiguration>
181 <Platform>
182 <Name>Override CPU default passive</Name>
183 <ProductName>*</ProductName>
184 <Preference>QUIET</Preference>
185 <ThermalZones>
186 <ThermalZone>
187 <Type>cpu</Type>
188 <TripPoints>
189 <TripPoint>
190 <Temperature>86000</Temperature>
191 <type>passive</type>
192 </TripPoint>
193 </TripPoints>
194 </ThermalZone>
195 </ThermalZones>
196 </Platform>
197 </ThermalConfiguration>
198 Example 2: In this configuration, we are controlling backlight when
200 some sensor "SEN2" reaches 60C. Here "LCD" is a standard cooling
201 device, which uses Linux backlight sysfs interface. "LCD_Zone" is a
202 valid thermal zone in Linux thermal sysfs on the test platform, hence
203 we don't need to provide path for sysfs for "LCD_Zone". The Linux ther‐
204 mal sysfs is already parsed and loaded by thermald program.
205 <?xml version="1.0"?>
207 <ThermalConfiguration>
208 <Platform>
209 <Name>Change Backlight</Name>
210 <ProductName>*</ProductName>
211 <Preference>QUIET</Preference>
212 <ThermalZones>
213 <ThermalZone>
214 <Type>LCD_Zone</Type>
215 <TripPoints>
216 <TripPoint>
217 <SensorType>SEN2</SensorType>
218 <Temperature>60000</Temperature>
219 <type>passive</type>
220 <CoolingDevice>
221 <Type>LCD</Type>
222 </CoolingDevice>
223 </TripPoint>
224 </TripPoints>
225 </ThermalZone>
226 </ThermalZones>
227 </Platform>
228 </ThermalConfiguration>
229 Example 3: In this example Lenovo Thinkpad X220 and fan speed is con‐
231 trolled. Here a cooling device "_Fan", can be controlled via sysfs
232 /sys/devices/platform/thinkpad_hwmon/pwm1. When the x86_pkg_temp
233 reaches 45C, Fan is started with increasing speeds, if the temperature
234 can't be controlled at 45C.
235 <?xml version="1.0"?>
237 <ThermalConfiguration>
238 <Platform>
239 <Name>Lenovo ThinkPad X220</Name>
240 <ProductName>*</ProductName>
241 <Preference>QUIET</Preference>
242 <ThermalZones>
243 <ThermalZone>
244 <Type>x86_pkg_temp</Type>
245 <TripPoints>
246 <TripPoint>
247 <SensorType>x86_pkg_temp</SensorType>
248 <Temperature>45000</Temperature>
249 <type>passive</type>
250 <ControlType>SEQUENTIAL</ControlType>
251 <CoolingDevice>
252 <index>1</index>
253 <type>_Fan</type>
254 <influence> 100 </influence>
255 <SamplingPeriod> 12 </SamplingPeriod>
256 </CoolingDevice>
257 </TripPoint>
258 </TripPoints>
259 </ThermalZone>
260 </ThermalZones>
261 <CoolingDevices>
262 <CoolingDevice>
263 <Type>_Fan</Type>
264 <Path>/sys/devices/platform/thinkpad_hwmon/pwm1</Path>
265 <MinState>0</MinState>
266 <IncDecStep>30</IncDecStep>
267 <ReadBack> 0 </ReadBack>
268 <MaxState>255</MaxState>
269 <DebouncePeriod>5</DebouncePeriod>
270 </CoolingDevice>
271 </CoolingDevices>
272 </Platform>
273 </ThermalConfiguration>
274 Example 4: The following example shows how PID can be used. Here once
276 temperature exceeds 80C, compensation is calculated using PID using 80C
277 as set point of PID. The compensation depends on error from the set
278 point. Here the default built in processor cooling device is used with
279 min state as 0 and max state as 10.
280 <?xml version="1.0"?>
282 <ThermalConfiguration>
283 <Platform>
284 <Name>Use PID param </Name>
285 <ProductName>*</ProductName>
286 <Preference>QUIET</Preference>
287 <ThermalZones>
288 <ThermalZone>
289 <Type>x86_pkg_temp</Type>
290 <TripPoints>
291 <TripPoint>
292 <SensorType>x86_pkg_temp</SensorType>
293 <Temperature>80000</Temperature>
294 <type>passive</type>
295 <ControlType>SEQUENTIAL</ControlType>
296 <CoolingDevice>
297 <type>Processor</type>
298 </CoolingDevice>
299 </TripPoint>
300 </TripPoints>
301 </ThermalZone>
302 </ThermalZones>
303 <CoolingDevices>
304 <CoolingDevice>
305 <Type>Processor</Type>
306 <PidControl>
307 <kp>0.0002</kp>
308 <kd>0</kd>
309 <ki>0</ki>
310 </PidControl>
311 </CoolingDevice>
312 </CoolingDevices>
313 </Platform>
314 </ThermalConfiguration>
315 Example 5: The following example shows how to control Fan when the
317 sysfs expects some string prefix. For example instead of just write a
318 number to fan control sysfs, the interface requires "level " in front
319 of the speed index value.
320 <?xml version="1.0"?>
322 <ThermalConfiguration>
323 <Platform>
324 <Name>Use Fan control first then CPU throttle </Name>
325 <ProductName>*</ProductName>
326 <Preference>QUIET</Preference>
327 <ThermalZones>
328 <ThermalZone>
329 <Type>x86_pkg_temp</Type>
330 <TripPoints>
331 <TripPoint>
332 <SensorType>x86_pkg_temp</SensorType>
333 <Temperature>80000</Temperature>
334 <type>passive</type>
335 <ControlType>SEQUENTIAL</ControlType>
336 <CoolingDevice>
337 <type>_fan_</type>
338 </CoolingDevice>
339 </TripPoint>
340 </TripPoints>
341 </ThermalZone>
342 </ThermalZones>
343 <CoolingDevices>
344 <CoolingDevice>
345 <Type>_fan_</Type>
346 <Path>/proc/acpi/ibm/fan</Path>
347 <WritePrefix>level </WritePrefix>
348 <MinState>0</MinState>
349 <MaxState>5</MaxState>
350 <DebouncePeriod>10</DebouncePeriod>
351 </CoolingDevice>
352 </CoolingDevices>
353 </Platform>
354 </ThermalConfiguration>
355 Example 6: Similar to example 5, but write different speeds at differ‐
357 ent temperatures.
358 <?xml version="1.0"?>
360 <ThermalConfiguration>
361 <Platform>
362 <Name>Use Fan control first then CPU throttle </Name>
363 <ProductName>*</ProductName>
364 <Preference>QUIET</Preference>
365 <ThermalZones>
366 <ThermalZone>
367 <Type>x86_pkg_temp</Type>
368 <TripPoints>
369 <TripPoint>
370 <SensorType>x86_pkg_temp</SensorType>
371 <Temperature>80000</Temperature>
372 <type>passive</type>
373 <CoolingDevice>
374 <type>_fan_</type>
375 <TargetState>1</TargetState>
376 </CoolingDevice>
377 </TripPoint>
378 <TripPoint>
379 <SensorType>x86_pkg_temp</SensorType>
380 <Temperature>85000</Temperature>
381 <type>passive</type>
382 <CoolingDevice>
383 <type>_fan_</type>
384 <TargetState>2</TargetState>
385 </CoolingDevice>
386 </TripPoint>
387 </TripPoints>
388 </ThermalZone>
389 </ThermalZones>
390 <CoolingDevices>
391 <CoolingDevice>
392 <Type>_fan_</Type>
393 <Path>/proc/acpi/ibm/fan</Path>
394 <WritePrefix>level </WritePrefix>
395 <MinState>0</MinState>
396 <MaxState>5</MaxState>
397 <DebouncePeriod>10</DebouncePeriod>
398 </CoolingDevice>
399 </CoolingDevices>
400 </Platform>
401 </ThermalConfiguration>
402 18 Dec 2018 thermal-conf.xml(5)