Thermal overview

Applicable for

STM32MP13x lines, STM32MP15x lines

1. Framework purpose[edit source]

The purpose of this article is to introduce the "Thermal framework".

Thermal framework is a subsystem made for handling thermal sensors and cooling devices, it is made of 3 subsystems:

thermal zone
cooling device
thermal-sensor via hwmon API or thermal API

2. System overview[edit source]

Thermal Framework

2.1. Component description[edit source]

thermal-zone is a container used to describe all thermal data for the platform
thermal framework offers an API to read temperature and to handle thresholds with interrupts.
hwmon framework offers an API to read temperature: no threshold, only polling.
cooling-device device is used to dissipate heat either:
- actively for example with a FAN controlled by GPIOs
- passively via OPP by forcing a lower CPU voltage or frequencies as a cooling state.

2.2. Thermal-zone role[edit source]

The thermal zone is also responsible for:

driving cooling devices depending on thermal sensor information,
handling a critical trip point that consist of calling shutdown,
polling thermal sensors that do not handle trip points with IRQs (that are implemented under hwmon framework).

A system may contains several thermal zones. For example one for CPU, one for GPU. Each zone is made of:

a thermal sensor with some polling periods descriptions,
some active or passive trip points with a temperature and hysteresis for each,
a cooling map that describe the action for each trip point.

2.3. API description[edit source]

The thermal API is not documented in the Linux Kernel documentation.

3. Configuration[edit source]

3.1. Kernel configuration[edit source]

The thermal API is activated by default in ST deliveries. Nevertheless, if a specific configuration is required, you can use Linux Menuconfig tool: Menuconfig or how to configure kernel and select:

[*] Device Drivers -->
    [*]   Thermal drivers (THERMAL [=y]) -->
        [*]   STMicroelectronics thermal drivers
    [*]   Hardware Monitoring support (HWMON [=y])

3.2. Device tree configuration[edit source]

The thermal zone is represented by the Thermal zone binding^[1]

The thermal sensor is represented by the Thermal sensor binding^[2]

The thermal cooling device is represented by the Thermal cooling device binding^[3]

4. How to use the Thermal framework[edit source]

5. Use cases[edit source]

A typical use case is to handle CPU overheat by calling shutdown when the temperature reaches a certain level. This is done in "critical" trip point. The example below makes that shutdown is called as soon as temperature reaches 105°C:

 trips {
   cpu-crit {
     temperature = <105000>;
     hysteresis = <0>;
     type = "critical";
 };

Another typical use case is passive power dissipation, consisting in limiting CPU frequency when the CPU is too hot. This is done in "passive" trip point. The example below sets the highest allowed OPP as OPP number 1 (one) as soon as the temperature is higher than 95°C:

 trips {
   cpu_alert: cpu-alert {
     temperature = <95000>;
     hysteresis = <10000>;
     type = "passive";
   };
 };
 cooling-maps {
   map0 {
     trip = <&cpu_alert>;
     cooling-device = <&cpu0 1 1>;
   };
 };

6. How to trace and debug the framework[edit source]

6.1. How to trace[edit source]

Dynamic debug can be enabled in the "thermal_sys" module like in the command below:

  echo 'module thermal_sys +ptmlf' > /sys/kernel/debug/dynamic_debug/control

6.2. How to debug[edit source]

When the thermal driver implements hwmon API, the temperature can be read from the sysfs like in the command below:

  cat /sys/devices/virtual/thermal/thermal_zone0/hwmon0/temp1_input

7. Generic source code location[edit source]

8. References[edit source]

[1] Documentation/devicetree/bindings/thermal/thermal-zones.yaml

[2] Documentation/devicetree/bindings/thermal/thermal-sensor.yaml

[3] Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml

[1]

[2]

[3]