mirror of
https://github.com/torvalds/linux.git
synced 2026-05-03 14:02:43 -04:00
87f67d1747
Document the critical-action property to describe the thermal action the OS should perform after the critical temperature is reached. The possible values are "shutdown" and "reboot". The motivation for introducing the critical-action property is that different systems may need different thermal actions when the critical temperature is reached. For example, in a desktop PC, it is desired that a shutdown happens after the critical temperature is reached. However, in some embedded cases, such behavior does not suit well, as the board may be unattended in the field and rebooting may be a better approach. The bootloader may also benefit from this new property as it can check the SoC temperature and in case the temperature is above the critical point, it can trigger a shutdown or reboot accordingly. Signed-off-by: Fabio Estevam <festevam@denx.de> Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> Signed-off-by: Daniel Lezcano <daniel.lezcano@linaro.org> Link: https://lore.kernel.org/r/20231129124330.519423-1-festevam@gmail.com
361 lines
14 KiB
YAML
361 lines
14 KiB
YAML
# SPDX-License-Identifier: (GPL-2.0)
|
|
# Copyright 2020 Linaro Ltd.
|
|
%YAML 1.2
|
|
---
|
|
$id: http://devicetree.org/schemas/thermal/thermal-zones.yaml#
|
|
$schema: http://devicetree.org/meta-schemas/base.yaml#
|
|
|
|
title: Thermal zone
|
|
|
|
maintainers:
|
|
- Daniel Lezcano <daniel.lezcano@linaro.org>
|
|
|
|
description: |
|
|
Thermal management is achieved in devicetree by describing the sensor hardware
|
|
and the software abstraction of cooling devices and thermal zones required to
|
|
take appropriate action to mitigate thermal overloads.
|
|
|
|
The following node types are used to completely describe a thermal management
|
|
system in devicetree:
|
|
- thermal-sensor: device that measures temperature, has SoC-specific bindings
|
|
- cooling-device: device used to dissipate heat either passively or actively
|
|
- thermal-zones: a container of the following node types used to describe all
|
|
thermal data for the platform
|
|
|
|
This binding describes the thermal-zones.
|
|
|
|
The polling-delay properties of a thermal-zone are bound to the maximum dT/dt
|
|
(temperature derivative over time) in two situations for a thermal zone:
|
|
1. when passive cooling is activated (polling-delay-passive)
|
|
2. when the zone just needs to be monitored (polling-delay) or when
|
|
active cooling is activated.
|
|
|
|
The maximum dT/dt is highly bound to hardware power consumption and
|
|
dissipation capability. The delays should be chosen to account for said
|
|
max dT/dt, such that a device does not cross several trip boundaries
|
|
unexpectedly between polls. Choosing the right polling delays shall avoid
|
|
having the device in temperature ranges that may damage the silicon structures
|
|
and reduce silicon lifetime.
|
|
|
|
properties:
|
|
$nodename:
|
|
const: thermal-zones
|
|
description:
|
|
A /thermal-zones node is required in order to use the thermal framework to
|
|
manage input from the various thermal zones in the system in order to
|
|
mitigate thermal overload conditions. It does not represent a real device
|
|
in the system, but acts as a container to link a thermal sensor device,
|
|
platform-data regarding temperature thresholds and the mitigation actions
|
|
to take when the temperature crosses those thresholds.
|
|
|
|
patternProperties:
|
|
"^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$":
|
|
type: object
|
|
description:
|
|
Each thermal zone node contains information about how frequently it
|
|
must be checked, the sensor responsible for reporting temperature for
|
|
this zone, one sub-node containing the various trip points for this
|
|
zone and one sub-node containing all the zone cooling-maps.
|
|
|
|
properties:
|
|
polling-delay:
|
|
$ref: /schemas/types.yaml#/definitions/uint32
|
|
description:
|
|
The maximum number of milliseconds to wait between polls when
|
|
checking this thermal zone. Setting this to 0 disables the polling
|
|
timers setup by the thermal framework and assumes that the thermal
|
|
sensors in this zone support interrupts.
|
|
|
|
polling-delay-passive:
|
|
$ref: /schemas/types.yaml#/definitions/uint32
|
|
description:
|
|
The maximum number of milliseconds to wait between polls when
|
|
checking this thermal zone while doing passive cooling. Setting
|
|
this to 0 disables the polling timers setup by the thermal
|
|
framework and assumes that the thermal sensors in this zone
|
|
support interrupts.
|
|
|
|
critical-action:
|
|
$ref: /schemas/types.yaml#/definitions/string
|
|
description: |
|
|
The action the OS should perform after the critical temperature is reached.
|
|
By default the system will shutdown as a safe action to prevent damage
|
|
to the hardware, if the property is not set.
|
|
The shutdown action should be always the default and preferred one.
|
|
Choose 'reboot' with care, as the hardware may be in thermal stress,
|
|
thus leading to infinite reboots that may cause damage to the hardware.
|
|
Make sure the firmware/bootloader will act as the last resort and take
|
|
over the thermal control.
|
|
|
|
enum:
|
|
- shutdown
|
|
- reboot
|
|
|
|
thermal-sensors:
|
|
$ref: /schemas/types.yaml#/definitions/phandle-array
|
|
maxItems: 1
|
|
description:
|
|
The thermal sensor phandle and sensor specifier used to monitor this
|
|
thermal zone.
|
|
|
|
coefficients:
|
|
$ref: /schemas/types.yaml#/definitions/uint32-array
|
|
description:
|
|
An array of integers containing the coefficients of a linear equation
|
|
that binds all the sensors listed in this thermal zone.
|
|
|
|
The linear equation used is as follows,
|
|
z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn
|
|
where c0, c1, .., cn are the coefficients.
|
|
|
|
Coefficients default to 1 in case this property is not specified. The
|
|
coefficients are ordered and are matched with sensors by means of the
|
|
sensor ID. Additional coefficients are interpreted as constant offset.
|
|
|
|
sustainable-power:
|
|
$ref: /schemas/types.yaml#/definitions/uint32
|
|
description:
|
|
An estimate of the sustainable power (in mW) that this thermal zone
|
|
can dissipate at the desired control temperature. For reference, the
|
|
sustainable power of a 4-inch phone is typically 2000mW, while on a
|
|
10-inch tablet is around 4500mW.
|
|
|
|
trips:
|
|
type: object
|
|
description:
|
|
This node describes a set of points in the temperature domain at
|
|
which the thermal framework needs to take action. The actions to
|
|
be taken are defined in another node called cooling-maps.
|
|
|
|
patternProperties:
|
|
"^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
|
|
type: object
|
|
|
|
properties:
|
|
temperature:
|
|
$ref: /schemas/types.yaml#/definitions/int32
|
|
minimum: -273000
|
|
maximum: 200000
|
|
description:
|
|
An integer expressing the trip temperature in millicelsius.
|
|
|
|
hysteresis:
|
|
$ref: /schemas/types.yaml#/definitions/uint32
|
|
description:
|
|
An unsigned integer expressing the hysteresis delta with
|
|
respect to the trip temperature property above, also in
|
|
millicelsius. Any cooling action initiated by the framework is
|
|
maintained until the temperature falls below
|
|
(trip temperature - hysteresis). This potentially prevents a
|
|
situation where the trip gets constantly triggered soon after
|
|
cooling action is removed.
|
|
|
|
type:
|
|
$ref: /schemas/types.yaml#/definitions/string
|
|
enum:
|
|
- active # enable active cooling e.g. fans
|
|
- passive # enable passive cooling e.g. throttling cpu
|
|
- hot # send notification to driver
|
|
- critical # send notification to driver, trigger shutdown
|
|
description: |
|
|
There are four valid trip types: active, passive, hot,
|
|
critical.
|
|
|
|
The critical trip type is used to set the maximum
|
|
temperature threshold above which the HW becomes
|
|
unstable and underlying firmware might even trigger a
|
|
reboot. Hitting the critical threshold triggers a system
|
|
shutdown.
|
|
|
|
The hot trip type can be used to send a notification to
|
|
the thermal driver (if a .notify callback is registered).
|
|
The action to be taken is left to the driver.
|
|
|
|
The passive trip type can be used to slow down HW e.g. run
|
|
the CPU, GPU, bus at a lower frequency.
|
|
|
|
The active trip type can be used to control other HW to
|
|
help in cooling e.g. fans can be sped up or slowed down
|
|
|
|
required:
|
|
- temperature
|
|
- hysteresis
|
|
- type
|
|
additionalProperties: false
|
|
|
|
additionalProperties: false
|
|
|
|
cooling-maps:
|
|
type: object
|
|
additionalProperties: false
|
|
description:
|
|
This node describes the action to be taken when a thermal zone
|
|
crosses one of the temperature thresholds described in the trips
|
|
node. The action takes the form of a mapping relation between a
|
|
trip and the target cooling device state.
|
|
|
|
patternProperties:
|
|
"^map[-a-zA-Z0-9]*$":
|
|
type: object
|
|
|
|
properties:
|
|
trip:
|
|
$ref: /schemas/types.yaml#/definitions/phandle
|
|
description:
|
|
A phandle of a trip point node within this thermal zone.
|
|
|
|
cooling-device:
|
|
$ref: /schemas/types.yaml#/definitions/phandle-array
|
|
description:
|
|
A list of cooling device phandles along with the minimum
|
|
and maximum cooling state specifiers for each cooling
|
|
device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
|
|
cooling-device phandle limit specifier lets the framework
|
|
use the minimum and maximum cooling state for that cooling
|
|
device automatically.
|
|
|
|
contribution:
|
|
$ref: /schemas/types.yaml#/definitions/uint32
|
|
description:
|
|
The cooling contribution to the thermal zone of the referred
|
|
cooling device at the referred trip point. The contribution is
|
|
a ratio of the sum of all cooling contributions within a
|
|
thermal zone.
|
|
|
|
required:
|
|
- trip
|
|
- cooling-device
|
|
additionalProperties: false
|
|
|
|
required:
|
|
- polling-delay
|
|
- polling-delay-passive
|
|
- thermal-sensors
|
|
- trips
|
|
|
|
additionalProperties: false
|
|
|
|
additionalProperties: false
|
|
|
|
examples:
|
|
- |
|
|
#include <dt-bindings/interrupt-controller/arm-gic.h>
|
|
#include <dt-bindings/thermal/thermal.h>
|
|
|
|
// Example 1: SDM845 TSENS
|
|
soc {
|
|
#address-cells = <2>;
|
|
#size-cells = <2>;
|
|
|
|
/* ... */
|
|
|
|
tsens0: thermal-sensor@c263000 {
|
|
compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
|
|
reg = <0 0x0c263000 0 0x1ff>, /* TM */
|
|
<0 0x0c222000 0 0x1ff>; /* SROT */
|
|
#qcom,sensors = <13>;
|
|
interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
|
|
<GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
|
|
interrupt-names = "uplow", "critical";
|
|
#thermal-sensor-cells = <1>;
|
|
};
|
|
|
|
tsens1: thermal-sensor@c265000 {
|
|
compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
|
|
reg = <0 0x0c265000 0 0x1ff>, /* TM */
|
|
<0 0x0c223000 0 0x1ff>; /* SROT */
|
|
#qcom,sensors = <8>;
|
|
interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
|
|
<GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
|
|
interrupt-names = "uplow", "critical";
|
|
#thermal-sensor-cells = <1>;
|
|
};
|
|
};
|
|
|
|
/* ... */
|
|
|
|
thermal-zones {
|
|
cpu0-thermal {
|
|
polling-delay-passive = <250>;
|
|
polling-delay = <1000>;
|
|
|
|
thermal-sensors = <&tsens0 1>;
|
|
|
|
trips {
|
|
cpu0_alert0: trip-point0 {
|
|
temperature = <90000>;
|
|
hysteresis = <2000>;
|
|
type = "passive";
|
|
};
|
|
|
|
cpu0_alert1: trip-point1 {
|
|
temperature = <95000>;
|
|
hysteresis = <2000>;
|
|
type = "passive";
|
|
};
|
|
|
|
cpu0_crit: cpu_crit {
|
|
temperature = <110000>;
|
|
hysteresis = <1000>;
|
|
type = "critical";
|
|
};
|
|
};
|
|
|
|
cooling-maps {
|
|
map0 {
|
|
trip = <&cpu0_alert0>;
|
|
/* Corresponds to 1400MHz in OPP table */
|
|
cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
|
|
<&CPU2 3 3>, <&CPU3 3 3>;
|
|
};
|
|
|
|
map1 {
|
|
trip = <&cpu0_alert1>;
|
|
/* Corresponds to 1000MHz in OPP table */
|
|
cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
|
|
<&CPU2 5 5>, <&CPU3 5 5>;
|
|
};
|
|
};
|
|
};
|
|
|
|
/* ... */
|
|
|
|
cluster0-thermal {
|
|
polling-delay-passive = <250>;
|
|
polling-delay = <1000>;
|
|
|
|
thermal-sensors = <&tsens0 5>;
|
|
|
|
trips {
|
|
cluster0_alert0: trip-point0 {
|
|
temperature = <90000>;
|
|
hysteresis = <2000>;
|
|
type = "hot";
|
|
};
|
|
cluster0_crit: cluster0_crit {
|
|
temperature = <110000>;
|
|
hysteresis = <2000>;
|
|
type = "critical";
|
|
};
|
|
};
|
|
};
|
|
|
|
/* ... */
|
|
|
|
gpu-top-thermal {
|
|
polling-delay-passive = <250>;
|
|
polling-delay = <1000>;
|
|
|
|
thermal-sensors = <&tsens0 11>;
|
|
|
|
trips {
|
|
gpu1_alert0: trip-point0 {
|
|
temperature = <90000>;
|
|
hysteresis = <2000>;
|
|
type = "hot";
|
|
};
|
|
};
|
|
};
|
|
};
|
|
...
|