.\" thermal-conf.xml(5) manual page
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public Licence along
.\" with this manual; if not, write to the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
.\"
.\" Copyright (C) 2012 Intel Corporation. All rights reserved.
.\"
.TH thermal-conf.xml "5" "Dec 18, 2018"
.SH NAME
thermal-conf.xml \- Configuration file for thermal daemon
.SH SYNOPSIS
$(TDCONFDIR)/etc/thermald/thermal-conf.xml
.SH DESCRIPTION
.B thermal-conf.xml
is a configuration file for the thermal daemon. It is used to configure
thermal sensors, zone and cooling devices. The location of this file depends
on the configuration option used during build time.
.PP
The terminology used in this file conforms to "Advanced Configuration and Power
Interface Specification". The ACPI thermal model is based around conceptual
platform regions called thermal zones that physically contain devices, thermal
sensors, and cooling controls. For example of a thermal zone can be a CPU or a
laptop cover. A zone can contain multiple sensors for monitoring temperature. A
cooling device provides interface to reduce the temperature of a source device,
which causes increase in the temperature. An example of a cooling device is a
FAN or some Linux driver which can throttle the source device.
.PP
A thermal zone configuration includes one or more trip points. A trip point is
a temperature at which a cooling device needs to be activated.
.PP
A cooling device can be either active or passive. An example of an active
device is a FAN, which will not reduce performance at the cost of consuming
more power and noise. A passive device uses performance throttling to control
temperature. In addition to cooling devices present in the thermal sysfs, the
following cooling devices are built into the thermald, which can be used as
valid cooling device type:
.IP \(bu 2
rapl_controller
.IP \(bu 2
intel_pstate
.IP \(bu 2
cpufreq
.IP \(bu 2
LCD
.PP
The thermal sysfs under Linux (/sys/class/thermal) provides a way to represent
per platform ACPI configuration. The kernel thermal governor uses this data to
keep the platform thermals under control. But there are some limitations, which
thermald tries to resolve. For example:
.IP \(bu 2
If the ACPI data is not optimized or buggy. In this case thermal-conf.xml
can be used to correct the behavior without change in BIOS.
.IP \(bu 2
There may be thermal zones exposed by the thermal sysfs without associated
cooling actions. In this case thermal conf.xml can be used to tie the cooling
devices to those zones.
.IP \(bu 2
The best cooling method may not be in the thermal sysfs. In this case
thermal-conf.xml can be used to bind a zone to an external cooling device.
.IP \(bu 2
Specify thermal relationships. A zone can be influenced by multiple source
devices with varying degrees. In this case thermal-conf.xml can be used to
define the relative influence for apply compensation.
.SH FILE FORMAT
The configuration file format conforms to XML specifications. A set of tags
defined to define platform, sensors, zones, cooling devices and trip points.
.sp 1
.EX
Example Platform Name
Example UUID
Example Product Name
QUIET|PERFORMANCE
example_sensor_1
/some_path
0
example_thermal_sysfs_sensor
1
Example Zone type
example_sensor_1
75000
max
SEQUENTIAL
1
example_cooling_device
100
12
6
example_cooling_device
0
10
0
50
5000
0.001
0.0001
0.0001
level
.EE
.SH EXAMPLE CONFIGURATIONS
.B Example 1:
This is a very simple configuration, to change the passive limit on the
CPU. Instead of default, this new temperature 86C in the configuration is
used. This will start cooling, once the temperature reaches 86C.
.sp 1
.EX
Override CPU default passive
*
QUIET
cpu
86000
passive
.EE
.PP
.B Example 2:
In this configuration, we are controlling backlight when some sensor "SEN2"
reaches 60C. Here "LCD" is a standard cooling device, which uses Linux
backlight sysfs interface. "LCD_Zone" is a valid thermal zone in Linux
thermal sysfs on the test platform, hence we don't need to provide path for
sysfs for "LCD_Zone". The Linux thermal sysfs is already parsed and loaded
by the thermald program.
.sp 1
.EX
Change Backlight
*
QUIET
LCD_Zone
SEN2
60000
passive
LCD
.EE
.PP
.B Example 3:
In this example Lenovo Thinkpad X220 and fan speed is controlled. Here a
cooling device "_Fan", can be controlled via sysfs
/sys/devices/platform/thinkpad_hwmon/pwm1. When the x86_pkg_temp reaches 45C,
Fan is started with increasing speeds, if the temperature can't be
controlled at 45C.
.sp 1
.EX
Lenovo ThinkPad X220
*
QUIET
x86_pkg_temp
x86_pkg_temp
45000
passive
SEQUENTIAL
1
_Fan
100
12
_Fan
/sys/devices/platform/thinkpad_hwmon/pwm1
0
30
0
255
5
.EE
.PP
.B Example 4:
The following example shows how PID can be used. Here once temperature
exceeds 80C, compensation is calculated using PID using 80C as set point of
PID. The compensation depends on error from the set point. Here the default
built in processor cooling device is used with min state as 0 and max state
as 10.
.sp 1
.EX
Use PID param
*
QUIET
x86_pkg_temp
x86_pkg_temp
80000
passive
SEQUENTIAL
Processor
Processor
0.0002
0
0
.EE
.PP
.B Example 5:
The following example shows how to control Fan when the sysfs expects some
string prefix. For example instead of just write a number to fan control
sysfs, the interface requires "level " in front of the speed index value.
.sp 1
.EX
Use Fan control first then CPU throttle
*
QUIET
x86_pkg_temp
x86_pkg_temp
80000
passive
SEQUENTIAL
_fan_
_fan_
/proc/acpi/ibm/fan
level
0
5
10
.EE
.PP
Example 6: Similar to example 5, but write different speeds at
different temperatures.
.sp 1
.EX
Use Fan control first then CPU throttle
*
QUIET
x86_pkg_temp
x86_pkg_temp
80000
passive
_fan_
1
x86_pkg_temp
85000
passive
_fan_
2
_fan_
/proc/acpi/ibm/fan
level
0
5
10
.EE
.PP
Example 7: Use RAPL power limits to control.
.sp 1
.EX
TEST
Example_RAPL_Power
QUIET
0
15000
2000
20
30
1000
TestZone
SEN3
50000
Passive
B0D4
3
2147483647
SEN3
52000
Passive
B0D4
3
8500000
SEN3
60000
Passive
B0D4
3
4500000
SEN3
65000
Passive
B0D4
3
.EE