xref: /linux/Documentation/devicetree/bindings/thermal/thermal-zones.yaml (revision ef9226cd56b718c79184a3466d32984a51cb449c)
1# SPDX-License-Identifier: (GPL-2.0)
2# Copyright 2020 Linaro Ltd.
3%YAML 1.2
4---
5$id: http://devicetree.org/schemas/thermal/thermal-zones.yaml#
6$schema: http://devicetree.org/meta-schemas/base.yaml#
7
8title: Thermal zone
9
10maintainers:
11  - Daniel Lezcano <daniel.lezcano@linaro.org>
12
13description: |
14  Thermal management is achieved in devicetree by describing the sensor hardware
15  and the software abstraction of cooling devices and thermal zones required to
16  take appropriate action to mitigate thermal overloads.
17
18  The following node types are used to completely describe a thermal management
19  system in devicetree:
20   - thermal-sensor: device that measures temperature, has SoC-specific bindings
21   - cooling-device: device used to dissipate heat either passively or actively
22   - thermal-zones: a container of the following node types used to describe all
23     thermal data for the platform
24
25  This binding describes the thermal-zones.
26
27  The polling-delay properties of a thermal-zone are bound to the maximum dT/dt
28  (temperature derivative over time) in two situations for a thermal zone:
29    1. when passive cooling is activated (polling-delay-passive)
30    2. when the zone just needs to be monitored (polling-delay) or when
31       active cooling is activated.
32
33  The maximum dT/dt is highly bound to hardware power consumption and
34  dissipation capability. The delays should be chosen to account for said
35  max dT/dt, such that a device does not cross several trip boundaries
36  unexpectedly between polls. Choosing the right polling delays shall avoid
37  having the device in temperature ranges that may damage the silicon structures
38  and reduce silicon lifetime.
39
40properties:
41  $nodename:
42    const: thermal-zones
43    description:
44      A /thermal-zones node is required in order to use the thermal framework to
45      manage input from the various thermal zones in the system in order to
46      mitigate thermal overload conditions. It does not represent a real device
47      in the system, but acts as a container to link a thermal sensor device,
48      platform-data regarding temperature thresholds and the mitigation actions
49      to take when the temperature crosses those thresholds.
50
51patternProperties:
52  "^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$":
53    type: object
54    description:
55      Each thermal zone node contains information about how frequently it
56      must be checked, the sensor responsible for reporting temperature for
57      this zone, one sub-node containing the various trip points for this
58      zone and one sub-node containing all the zone cooling-maps.
59
60    properties:
61      polling-delay:
62        $ref: /schemas/types.yaml#/definitions/uint32
63        description:
64          The maximum number of milliseconds to wait between polls when
65          checking this thermal zone. Setting this to 0 disables the polling
66          timers setup by the thermal framework and assumes that the thermal
67          sensors in this zone support interrupts.
68
69      polling-delay-passive:
70        $ref: /schemas/types.yaml#/definitions/uint32
71        description:
72          The maximum number of milliseconds to wait between polls when
73          checking this thermal zone while doing passive cooling. Setting
74          this to 0 disables the polling timers setup by the thermal
75          framework and assumes that the thermal sensors in this zone
76          support interrupts.
77
78      critical-action:
79        $ref: /schemas/types.yaml#/definitions/string
80        description: |
81          The action the OS should perform after the critical temperature is reached.
82          By default the system will shutdown as a safe action to prevent damage
83          to the hardware, if the property is not set.
84          The shutdown action should be always the default and preferred one.
85          Choose 'reboot' with care, as the hardware may be in thermal stress,
86          thus leading to infinite reboots that may cause damage to the hardware.
87          Make sure the firmware/bootloader will act as the last resort and take
88          over the thermal control.
89
90        enum:
91          - shutdown
92          - reboot
93
94      thermal-sensors:
95        $ref: /schemas/types.yaml#/definitions/phandle-array
96        maxItems: 1
97        description:
98          The thermal sensor phandle and sensor specifier used to monitor this
99          thermal zone.
100
101      coefficients:
102        $ref: /schemas/types.yaml#/definitions/uint32-array
103        description:
104          An array of integers containing the coefficients of a linear equation
105          that binds all the sensors listed in this thermal zone.
106
107          The linear equation used is as follows,
108            z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn
109          where c0, c1, .., cn are the coefficients.
110
111          Coefficients default to 1 in case this property is not specified. The
112          coefficients are ordered and are matched with sensors by means of the
113          sensor ID. Additional coefficients are interpreted as constant offset.
114
115      sustainable-power:
116        $ref: /schemas/types.yaml#/definitions/uint32
117        description:
118          An estimate of the sustainable power (in mW) that this thermal zone
119          can dissipate at the desired control temperature. For reference, the
120          sustainable power of a 4-inch phone is typically 2000mW, while on a
121          10-inch tablet is around 4500mW.
122
123      trips:
124        type: object
125        description:
126          This node describes a set of points in the temperature domain at
127          which the thermal framework needs to take action. The actions to
128          be taken are defined in another node called cooling-maps.
129
130        patternProperties:
131          "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
132            type: object
133
134            properties:
135              temperature:
136                $ref: /schemas/types.yaml#/definitions/int32
137                minimum: -273000
138                maximum: 200000
139                description:
140                  An integer expressing the trip temperature in millicelsius.
141
142              hysteresis:
143                $ref: /schemas/types.yaml#/definitions/uint32
144                description:
145                  An unsigned integer expressing the hysteresis delta with
146                  respect to the trip temperature property above, also in
147                  millicelsius. Any cooling action initiated by the framework is
148                  maintained until the temperature falls below
149                  (trip temperature - hysteresis). This potentially prevents a
150                  situation where the trip gets constantly triggered soon after
151                  cooling action is removed.
152
153              type:
154                $ref: /schemas/types.yaml#/definitions/string
155                enum:
156                  - active   # enable active cooling e.g. fans
157                  - passive  # enable passive cooling e.g. throttling cpu
158                  - hot      # send notification to driver
159                  - critical # send notification to driver, trigger shutdown
160                description: |
161                  There are four valid trip types: active, passive, hot,
162                  critical.
163
164                  The critical trip type is used to set the maximum
165                  temperature threshold above which the HW becomes
166                  unstable and underlying firmware might even trigger a
167                  reboot. Hitting the critical threshold triggers a system
168                  shutdown.
169
170                  The hot trip type can be used to send a notification to
171                  the thermal driver (if a .notify callback is registered).
172                  The action to be taken is left to the driver.
173
174                  The passive trip type can be used to slow down HW e.g. run
175                  the CPU, GPU, bus at a lower frequency.
176
177                  The active trip type can be used to control other HW to
178                  help in cooling e.g. fans can be sped up or slowed down
179
180            required:
181              - temperature
182              - hysteresis
183              - type
184            additionalProperties: false
185
186        additionalProperties: false
187
188      cooling-maps:
189        type: object
190        additionalProperties: false
191        description:
192          This node describes the action to be taken when a thermal zone
193          crosses one of the temperature thresholds described in the trips
194          node. The action takes the form of a mapping relation between a
195          trip and the target cooling device state.
196
197        patternProperties:
198          "^map[-a-zA-Z0-9]*$":
199            type: object
200
201            properties:
202              trip:
203                $ref: /schemas/types.yaml#/definitions/phandle
204                description:
205                  A phandle of a trip point node within this thermal zone.
206
207              cooling-device:
208                $ref: /schemas/types.yaml#/definitions/phandle-array
209                description:
210                  A list of cooling device phandles along with the minimum
211                  and maximum cooling state specifiers for each cooling
212                  device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
213                  cooling-device phandle limit specifier lets the framework
214                  use the minimum and maximum cooling state for that cooling
215                  device automatically.
216
217              contribution:
218                $ref: /schemas/types.yaml#/definitions/uint32
219                description:
220                  The cooling contribution to the thermal zone of the referred
221                  cooling device at the referred trip point. The contribution is
222                  a ratio of the sum of all cooling contributions within a
223                  thermal zone.
224
225            required:
226              - trip
227              - cooling-device
228            additionalProperties: false
229
230    required:
231      - thermal-sensors
232      - trips
233
234    additionalProperties: false
235
236additionalProperties: false
237
238examples:
239  - |
240    #include <dt-bindings/interrupt-controller/arm-gic.h>
241    #include <dt-bindings/thermal/thermal.h>
242
243    // Example 1: SDM845 TSENS
244    soc {
245            #address-cells = <2>;
246            #size-cells = <2>;
247
248            /* ... */
249
250            tsens0: thermal-sensor@c263000 {
251                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
252                    reg = <0 0x0c263000 0 0x1ff>, /* TM */
253                          <0 0x0c222000 0 0x1ff>; /* SROT */
254                    #qcom,sensors = <13>;
255                    interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
256                                 <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
257                    interrupt-names = "uplow", "critical";
258                    #thermal-sensor-cells = <1>;
259            };
260
261            tsens1: thermal-sensor@c265000 {
262                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
263                    reg = <0 0x0c265000 0 0x1ff>, /* TM */
264                          <0 0x0c223000 0 0x1ff>; /* SROT */
265                    #qcom,sensors = <8>;
266                    interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
267                                 <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
268                    interrupt-names = "uplow", "critical";
269                    #thermal-sensor-cells = <1>;
270            };
271    };
272
273    /* ... */
274
275    thermal-zones {
276            cpu0-thermal {
277                    polling-delay-passive = <250>;
278                    polling-delay = <1000>;
279
280                    thermal-sensors = <&tsens0 1>;
281
282                    trips {
283                            cpu0_alert0: trip-point0 {
284                                    temperature = <90000>;
285                                    hysteresis = <2000>;
286                                    type = "passive";
287                            };
288
289                            cpu0_alert1: trip-point1 {
290                                    temperature = <95000>;
291                                    hysteresis = <2000>;
292                                    type = "passive";
293                            };
294
295                            cpu0_crit: cpu_crit {
296                                    temperature = <110000>;
297                                    hysteresis = <1000>;
298                                    type = "critical";
299                            };
300                    };
301
302                    cooling-maps {
303                            map0 {
304                                    trip = <&cpu0_alert0>;
305                                    /* Corresponds to 1400MHz in OPP table */
306                                    cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
307                                                     <&CPU2 3 3>, <&CPU3 3 3>;
308                            };
309
310                            map1 {
311                                    trip = <&cpu0_alert1>;
312                                    /* Corresponds to 1000MHz in OPP table */
313                                    cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
314                                                     <&CPU2 5 5>, <&CPU3 5 5>;
315                            };
316                    };
317            };
318
319            /* ... */
320
321            cluster0-thermal {
322                    polling-delay-passive = <250>;
323                    polling-delay = <1000>;
324
325                    thermal-sensors = <&tsens0 5>;
326
327                    trips {
328                            cluster0_alert0: trip-point0 {
329                                    temperature = <90000>;
330                                    hysteresis = <2000>;
331                                    type = "hot";
332                            };
333                            cluster0_crit: cluster0_crit {
334                                    temperature = <110000>;
335                                    hysteresis = <2000>;
336                                    type = "critical";
337                            };
338                    };
339            };
340
341            /* ... */
342
343            gpu-top-thermal {
344                    polling-delay-passive = <250>;
345                    polling-delay = <1000>;
346
347                    thermal-sensors = <&tsens0 11>;
348
349                    trips {
350                            gpu1_alert0: trip-point0 {
351                                    temperature = <90000>;
352                                    hysteresis = <2000>;
353                                    type = "hot";
354                            };
355                    };
356            };
357    };
358...
359