xref: /linux/Documentation/devicetree/bindings/thermal/thermal-zones.yaml (revision 59fff63cc2b75dcfe08f9eeb4b2187d73e53843d)
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      thermal-sensors:
79        $ref: /schemas/types.yaml#/definitions/phandle-array
80        maxItems: 1
81        description:
82          The thermal sensor phandle and sensor specifier used to monitor this
83          thermal zone.
84
85      coefficients:
86        $ref: /schemas/types.yaml#/definitions/uint32-array
87        description:
88          An array of integers containing the coefficients of a linear equation
89          that binds all the sensors listed in this thermal zone.
90
91          The linear equation used is as follows,
92            z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn
93          where c0, c1, .., cn are the coefficients.
94
95          Coefficients default to 1 in case this property is not specified. The
96          coefficients are ordered and are matched with sensors by means of the
97          sensor ID. Additional coefficients are interpreted as constant offset.
98
99      sustainable-power:
100        $ref: /schemas/types.yaml#/definitions/uint32
101        description:
102          An estimate of the sustainable power (in mW) that this thermal zone
103          can dissipate at the desired control temperature. For reference, the
104          sustainable power of a 4-inch phone is typically 2000mW, while on a
105          10-inch tablet is around 4500mW.
106
107      trips:
108        type: object
109        description:
110          This node describes a set of points in the temperature domain at
111          which the thermal framework needs to take action. The actions to
112          be taken are defined in another node called cooling-maps.
113
114        patternProperties:
115          "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
116            type: object
117
118            properties:
119              temperature:
120                $ref: /schemas/types.yaml#/definitions/int32
121                minimum: -273000
122                maximum: 200000
123                description:
124                  An integer expressing the trip temperature in millicelsius.
125
126              hysteresis:
127                $ref: /schemas/types.yaml#/definitions/uint32
128                description:
129                  An unsigned integer expressing the hysteresis delta with
130                  respect to the trip temperature property above, also in
131                  millicelsius. Any cooling action initiated by the framework is
132                  maintained until the temperature falls below
133                  (trip temperature - hysteresis). This potentially prevents a
134                  situation where the trip gets constantly triggered soon after
135                  cooling action is removed.
136
137              type:
138                $ref: /schemas/types.yaml#/definitions/string
139                enum:
140                  - active   # enable active cooling e.g. fans
141                  - passive  # enable passive cooling e.g. throttling cpu
142                  - hot      # send notification to driver
143                  - critical # send notification to driver, trigger shutdown
144                description: |
145                  There are four valid trip types: active, passive, hot,
146                  critical.
147
148                  The critical trip type is used to set the maximum
149                  temperature threshold above which the HW becomes
150                  unstable and underlying firmware might even trigger a
151                  reboot. Hitting the critical threshold triggers a system
152                  shutdown.
153
154                  The hot trip type can be used to send a notification to
155                  the thermal driver (if a .notify callback is registered).
156                  The action to be taken is left to the driver.
157
158                  The passive trip type can be used to slow down HW e.g. run
159                  the CPU, GPU, bus at a lower frequency.
160
161                  The active trip type can be used to control other HW to
162                  help in cooling e.g. fans can be sped up or slowed down
163
164            required:
165              - temperature
166              - hysteresis
167              - type
168            additionalProperties: false
169
170        additionalProperties: false
171
172      cooling-maps:
173        type: object
174        additionalProperties: false
175        description:
176          This node describes the action to be taken when a thermal zone
177          crosses one of the temperature thresholds described in the trips
178          node. The action takes the form of a mapping relation between a
179          trip and the target cooling device state.
180
181        patternProperties:
182          "^map[-a-zA-Z0-9]*$":
183            type: object
184
185            properties:
186              trip:
187                $ref: /schemas/types.yaml#/definitions/phandle
188                description:
189                  A phandle of a trip point node within this thermal zone.
190
191              cooling-device:
192                $ref: /schemas/types.yaml#/definitions/phandle-array
193                description:
194                  A list of cooling device phandles along with the minimum
195                  and maximum cooling state specifiers for each cooling
196                  device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
197                  cooling-device phandle limit specifier lets the framework
198                  use the minimum and maximum cooling state for that cooling
199                  device automatically.
200
201              contribution:
202                $ref: /schemas/types.yaml#/definitions/uint32
203                description:
204                  The cooling contribution to the thermal zone of the referred
205                  cooling device at the referred trip point. The contribution is
206                  a ratio of the sum of all cooling contributions within a
207                  thermal zone.
208
209            required:
210              - trip
211              - cooling-device
212            additionalProperties: false
213
214    required:
215      - polling-delay
216      - polling-delay-passive
217      - thermal-sensors
218      - trips
219
220    additionalProperties: false
221
222additionalProperties: false
223
224examples:
225  - |
226    #include <dt-bindings/interrupt-controller/arm-gic.h>
227    #include <dt-bindings/thermal/thermal.h>
228
229    // Example 1: SDM845 TSENS
230    soc {
231            #address-cells = <2>;
232            #size-cells = <2>;
233
234            /* ... */
235
236            tsens0: thermal-sensor@c263000 {
237                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
238                    reg = <0 0x0c263000 0 0x1ff>, /* TM */
239                          <0 0x0c222000 0 0x1ff>; /* SROT */
240                    #qcom,sensors = <13>;
241                    interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
242                                 <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
243                    interrupt-names = "uplow", "critical";
244                    #thermal-sensor-cells = <1>;
245            };
246
247            tsens1: thermal-sensor@c265000 {
248                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
249                    reg = <0 0x0c265000 0 0x1ff>, /* TM */
250                          <0 0x0c223000 0 0x1ff>; /* SROT */
251                    #qcom,sensors = <8>;
252                    interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
253                                 <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
254                    interrupt-names = "uplow", "critical";
255                    #thermal-sensor-cells = <1>;
256            };
257    };
258
259    /* ... */
260
261    thermal-zones {
262            cpu0-thermal {
263                    polling-delay-passive = <250>;
264                    polling-delay = <1000>;
265
266                    thermal-sensors = <&tsens0 1>;
267
268                    trips {
269                            cpu0_alert0: trip-point0 {
270                                    temperature = <90000>;
271                                    hysteresis = <2000>;
272                                    type = "passive";
273                            };
274
275                            cpu0_alert1: trip-point1 {
276                                    temperature = <95000>;
277                                    hysteresis = <2000>;
278                                    type = "passive";
279                            };
280
281                            cpu0_crit: cpu_crit {
282                                    temperature = <110000>;
283                                    hysteresis = <1000>;
284                                    type = "critical";
285                            };
286                    };
287
288                    cooling-maps {
289                            map0 {
290                                    trip = <&cpu0_alert0>;
291                                    /* Corresponds to 1400MHz in OPP table */
292                                    cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
293                                                     <&CPU2 3 3>, <&CPU3 3 3>;
294                            };
295
296                            map1 {
297                                    trip = <&cpu0_alert1>;
298                                    /* Corresponds to 1000MHz in OPP table */
299                                    cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
300                                                     <&CPU2 5 5>, <&CPU3 5 5>;
301                            };
302                    };
303            };
304
305            /* ... */
306
307            cluster0-thermal {
308                    polling-delay-passive = <250>;
309                    polling-delay = <1000>;
310
311                    thermal-sensors = <&tsens0 5>;
312
313                    trips {
314                            cluster0_alert0: trip-point0 {
315                                    temperature = <90000>;
316                                    hysteresis = <2000>;
317                                    type = "hot";
318                            };
319                            cluster0_crit: cluster0_crit {
320                                    temperature = <110000>;
321                                    hysteresis = <2000>;
322                                    type = "critical";
323                            };
324                    };
325            };
326
327            /* ... */
328
329            gpu-top-thermal {
330                    polling-delay-passive = <250>;
331                    polling-delay = <1000>;
332
333                    thermal-sensors = <&tsens0 11>;
334
335                    trips {
336                            gpu1_alert0: trip-point0 {
337                                    temperature = <90000>;
338                                    hysteresis = <2000>;
339                                    type = "hot";
340                            };
341                    };
342            };
343    };
344...
345