Difference between revisions of "Thermal overview"

[quality revision] [pending revision]
m (Component description)
 
Under construction.png Coming soon This article is under construction and will be available end of 2022



1 Framework purpose[edit]

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]

File:Thermal framework.png
Thermal Framework

2.1 Component description[edit]

  • 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]

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]

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

3 Configuration[edit]

3.1 Kernal configuration[edit]

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 Devicetree configuration[edit]

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]

5 Use cases[edit]

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]

6.1 How to trace[edit]

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]

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]

8 References[edit]

{{UnderConstruction}}
|This article is under construction and will be available end of 2022}}
{{ReviewsComments|-- [[User:Nathalie Sangouard|Nathalie Sangouard]] ([[User talk:Nathalie Sangouard|talk]]) 18:27, 23 May 2022 (CEST)<br />Article to be updated in V3 also when it will be available for V4 :[[stm32mpuv3:Thermal overview]] }}<noinclude>

[[Category:Power and Thermal|1]]
{{PublicationRequestId | | 2019-01-28 | Automatic approval (article under construction)}}
{{ArticleBasedOnModel| Framework overview article model}}</noinclude>


== Framework purpose ==

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

== System Overview ==

[[File:thermal_framework.png|thumb|center|766px|link=|alt=Alternate text|Thermal Framework]]

=== Component description ===

* 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.

=== thermal-zone role ===

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.

===API description===
The Thermal API is not documented in the Linux Kernel documentation.

==Configuration ==
===Kernal configuration ===
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 | Menuconfig or how to configure kernel ]] and select:
<pre>

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


===Devicetree configuration ===

The thermal zone is represented by the ''Thermal zone binding''<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/thermal/thermal-zones.yaml | Documentation/devicetree/bindings/thermal/thermal-zones.yaml}}</ref>


The thermal sensor is represented by the ''Thermal sensor binding''<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/thermal/thermal-sensor.yaml | Documentation/devicetree/bindings/thermal/thermal-sensor.yaml}}</ref>


The thermal cooling device is represented by the ''Thermal cooling device binding''<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml | Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml}}</ref>


== How to use the Thermal framework==

== Use cases==
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>;
    };
  };

==How to trace and debug the framework==

=== How to trace ===
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

=== How to debug ===
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

==Generic source code location==
*{{CodeSource | Linux kernel | drivers/thermal | thermal core and drivers}}
*{{CodeSource | Linux kernel | drivers/thermal/thermal_core.h | thermal interface}}
*{{CodeSource | Linux kernel | drivers/hwmon | hwmon drivers}}
*{{CodeSource | Linux kernel | drivers/thermal/st | stm32 thermal drivers}}

==References==<references />
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{UnderConstruction}}
+
{{UnderConstruction|This article is under construction and will be available end of 2022}}
 
+
{{ReviewsComments|-- [[User:Nathalie Sangouard|Nathalie Sangouard]] ([[User talk:Nathalie Sangouard|talk]]) 18:27, 23 May 2022 (CEST)<br />Article to be updated in V3 also when it will be available for V4 :[[stm32mpuv3:Thermal overview]] }}
 
<noinclude>
 
<noinclude>
 
[[Category:Power and Thermal|1]]
 
[[Category:Power and Thermal|1]]
Line 6: Line 6:
 
{{ArticleBasedOnModel| Framework overview article model}}
 
{{ArticleBasedOnModel| Framework overview article model}}
 
</noinclude>
 
</noinclude>
  +
  +
== Framework purpose ==
  +
  +
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
  +
  +
== System Overview ==
  +
  +
[[File:thermal_framework.png|thumb|center|766px|link=|alt=Alternate text|Thermal Framework]]
  +
  +
=== Component description ===
  +
  +
* 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.
  +
  +
=== thermal-zone role ===
  +
  +
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.
  +
  +
===API description===
  +
The Thermal API is not documented in the Linux Kernel documentation.
  +
  +
==Configuration ==
  +
===Kernal configuration ===
  +
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 | Menuconfig or how to configure kernel ]] and select:
  +
  +
  +
<pre>
  +
[*] Device Drivers -->
  +
    [*]  Thermal drivers (THERMAL [=y]) -->
  +
        [*]  STMicroelectronics thermal drivers
  +
    [*]  Hardware Monitoring support (HWMON [=y])
  +
</pre>
  +
  +
===Devicetree configuration ===
  +
  +
The thermal zone is represented by the ''Thermal zone binding''<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/thermal/thermal-zones.yaml | Documentation/devicetree/bindings/thermal/thermal-zones.yaml}}</ref>
  +
  +
The thermal sensor is represented by the ''Thermal sensor binding''<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/thermal/thermal-sensor.yaml | Documentation/devicetree/bindings/thermal/thermal-sensor.yaml}}</ref>
  +
  +
The thermal cooling device is represented by the ''Thermal cooling device binding''<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml | Documentation/devicetree/bindings/thermal/thermal-cooling-devices.yaml}}</ref>
  +
  +
== How to use the Thermal framework==
  +
  +
== Use cases==
  +
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>;
  +
    };
  +
  };
  +
  +
  +
==How to trace and debug the framework==
  +
  +
=== How to trace ===
  +
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
  +
  +
=== How to debug ===
  +
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
  +
  +
==Generic source code location==
  +
*{{CodeSource | Linux kernel | drivers/thermal | thermal core and drivers}}
  +
*{{CodeSource | Linux kernel | drivers/thermal/thermal_core.h | thermal interface}}
  +
*{{CodeSource | Linux kernel | drivers/hwmon | hwmon drivers}}
  +
*{{CodeSource | Linux kernel | drivers/thermal/st | stm32 thermal drivers}}
  +
  +
==References==
  +
<references />