Provided by: thermald_1.5-2ubuntu4_amd64 
NAME
thermal-conf.xml - Configuration file for thermal daemon
SYNOPSIS
$(TDCONFDIR)/etc/thermald/thermal-conf.xml
DESCRIPTION
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.
The terminology used in this file confirms 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.
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.
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:
- rapl_controller
- intel_pstate
- cpufreq
- LCD
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:
- 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.
- 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.
- 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.
- 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.
FILE FORMAT
The configuration file format confirms to XML specifications. A set of tags defined to
define platform, sensors, zones, cooling devices and trip points.
<ThermalConfiguration>
<Platform>
<Name>Example Platform Name</Name>
<!--UUID is optional, if present this will be matched. Both product name and UUID can
contain wild card "*", which matches any platform.-->
<UUID>Example UUID</UUID>
configuration file format confirms to XML specifications. A set of tags defined to
define platform, sensors, zones, cooling
devices and trip points.
<ThermalConfiguration>
<Platform>
<ProductName>Example Product Name</ProductName>
<Preference>QUIET|PERFORMANCE</Preference>
<!-Quiet mode will only use passive cooling device. "PERFORMANCE" will only select
active devices .-->
<ThermalSensors>
<ThermalSensor>
<!-- New Sensor with a type and path -->
<Type>example_sensor_1</Type>
<Path>/some_path</Path>
<AsyncCapable>0</AsyncCapable>
</ThermalSensor>
<ThermalSensor>
<!-- Already present in thermal sysfs, enable this or add/change config For
example, here we are indicating that sensor can do async events to avoid polling
-->
<Type>example_thermal_sysfs_sensor</Type>
<!-- If async capable, then we don't need to poll -->
<AsyncCapable>1</AsyncCapable>
</ThermalSensor>
</ThermalSensors>
<ThermalZones>
<ThermalZone>
<Type>Example Zone type</Type>
<TripPoints>
<TripPoint>
<SensorType>example_sensor_1</SensorType>
<!-- Temperature at which to take action -->
<Temperature> 75000 </Temperature>
<!-- max/passive/active If a MAX type is specified, then daemon
will use PID control to aggressively throttle to avoid reaching this temp.-->
<type>max</type>
<!-- SEQUENTIAL | PARALLEL. When a trip point temp is violated,
then number of cooling devices can be activated. If control type is SEQUENTIAL then, it
will exhaust first cooling device before trying next. -->
<ControlType>SEQUENTIAL</ControlType>
<CoolingDevice>
<index>1</index>
<type>example_cooling_device</type>
<!-- Influence will be used order cooling devices. First
cooling device will be used, which has highest influence. -->
<influence> 100 </influence>
<!-- Delay in using this cdev, this takes some time too
actually cool a zone -->
<SamplingPeriod> 12 </SamplingPeriod>
<!-- Set a specific state of this cooling device when this
trip is violated -->
<TargetState> 6 </TargetState>
</CoolingDevice>
</TripPoint>
</TripPoints>
</ThermalZone>
</ThermalZones>
<CoolingDevices>
<CoolingDevice>
<!-- Cooling device can be specified by a type and optionally a sysfs path.
If the type is already present in thermal sysfs, there is no need of a path. Compensation
can use min/max and step size to increasing cool the system. Debounce period can be used
to force a waiting period for action. -->
<Type>example_cooling_device</Type>
<MinState>0</MinState>
<IncDecStep>10</IncDecStep>
<ReadBack> 0 </ReadBack>
<MaxState>50</MaxState>
<DebouncePeriod>5000</DebouncePeriod>
<!-- If there are no PID parameters, compensation increase step wise and
exponentially (if single step is not able to change trend). Alternatively a PID parameters
can be specified then next step will use PID calculation using provided PID constants. -->
<PidControl>
<kp>0.001</kp>
<kd>0.0001</kd>
<ki>0.0001</ki>
</PidControl>
</CoolingDevice>
</CoolingDevices>
</Platform>
</ThermalConfiguration>
EXAMPLE CONFIGURATIONS
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.
<?xml version="1.0"?>
<ThermalConfiguration>
<Platform>
<Name>Overide CPU default passive</Name>
<ProductName>*</ProductName>
<Preference>QUIET</Preference>
<ThermalZones>
<ThermalZone>
<Type>cpu</Type>
<TripPoints>
<TripPoint>
<Temperature>86000</Temperature>
<type>passive</type>
</TripPoint>
</TripPoints>
</ThermalZone>
</ThermalZones>
</Platform>
</ThermalConfiguration>
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. "SEN2" is a valid thermal zone in Linux thermal sysfs on the test platform,
hence we don't need to provide path for sysfs for "SEN2". The Linux thermal sysfs is
already parsed and loaded by thermald program.
<?xml version="1.0"?>
<ThermalConfiguration>
<Platform>
<Name>Change Backlight</Name>
<ProductName>*</ProductName>
<Preference>QUIET</Preference>
<ThermalZones>
<ThermalZone>
<Type>LCD_Zone</Type>
<TripPoints>
<TripPoint>
<SensorType>SEN2</SensorType>
<Temperature>60000</Temperature>
<type>passive</type>
<CoolingDevice>
<Type>LCD</Type>
</CoolingDevice>
</TripPoint>
</TripPoints>
</ThermalZone>
</ThermalZones>
</Platform>
</ThermalConfiguration>
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.
<?xml version="1.0"?>
<ThermalConfiguration>
<Platform>
<Name>Lenovo ThinkPad X220</Name>
<ProductName>*</ProductName>
<Preference>QUIET</Preference>
<ThermalZones>
<ThermalZone>
<Type>x86_pkg_temp</Type>
<TripPoints>
<TripPoint>
<SensorType>x86_pkg_temp</SensorType>
<Temperature>45000</Temperature>
<type>passive</type>
<ControlType>SEQUENTIAL</ControlType>
<CoolingDevice>
<index>1</index>
<type>_Fan</type>
<influence>
100 </influence>
<SamplingPeriod>
12 </SamplingPeriod>
</CoolingDevice>
</TripPoint>
</TripPoints>
</ThermalZone>
</ThermalZones>
<CoolingDevices>
<CoolingDevice>
<Type>_Fan</Type>
<Path>/sys/devices/platform/thinkpad_hwmon/pwm1</Path>
<MinState>0</MinState>
<IncDecStep>30</IncDecStep>
<ReadBack> 0 </ReadBack>
<MaxState>255</MaxState>
<DebouncePeriod>5</DebouncePeriod>
</CoolingDevice>
</CoolingDevices>
</Platform>
</ThermalConfiguration>