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 binding
9
10maintainers:
11  - Amit Kucheria <amitk@kernel.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        description:
175          This node describes the action to be taken when a thermal zone
176          crosses one of the temperature thresholds described in the trips
177          node. The action takes the form of a mapping relation between a
178          trip and the target cooling device state.
179
180        patternProperties:
181          "^map[-a-zA-Z0-9]*$":
182            type: object
183
184            properties:
185              trip:
186                $ref: /schemas/types.yaml#/definitions/phandle
187                description:
188                  A phandle of a trip point node within this thermal zone.
189
190              cooling-device:
191                $ref: /schemas/types.yaml#/definitions/phandle-array
192                description:
193                  A list of cooling device phandles along with the minimum
194                  and maximum cooling state specifiers for each cooling
195                  device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
196                  cooling-device phandle limit specifier lets the framework
197                  use the minimum and maximum cooling state for that cooling
198                  device automatically.
199
200              contribution:
201                $ref: /schemas/types.yaml#/definitions/uint32
202                description:
203                  The cooling contribution to the thermal zone of the referred
204                  cooling device at the referred trip point. The contribution is
205                  a ratio of the sum of all cooling contributions within a
206                  thermal zone.
207
208            required:
209              - trip
210              - cooling-device
211            additionalProperties: false
212
213    required:
214      - polling-delay
215      - polling-delay-passive
216      - thermal-sensors
217
218    additionalProperties: false
219
220additionalProperties: false
221
222examples:
223  - |
224    #include <dt-bindings/interrupt-controller/arm-gic.h>
225    #include <dt-bindings/thermal/thermal.h>
226
227    // Example 1: SDM845 TSENS
228    soc {
229            #address-cells = <2>;
230            #size-cells = <2>;
231
232            /* ... */
233
234            tsens0: thermal-sensor@c263000 {
235                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
236                    reg = <0 0x0c263000 0 0x1ff>, /* TM */
237                          <0 0x0c222000 0 0x1ff>; /* SROT */
238                    #qcom,sensors = <13>;
239                    interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
240                                 <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
241                    interrupt-names = "uplow", "critical";
242                    #thermal-sensor-cells = <1>;
243            };
244
245            tsens1: thermal-sensor@c265000 {
246                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
247                    reg = <0 0x0c265000 0 0x1ff>, /* TM */
248                          <0 0x0c223000 0 0x1ff>; /* SROT */
249                    #qcom,sensors = <8>;
250                    interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
251                                 <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
252                    interrupt-names = "uplow", "critical";
253                    #thermal-sensor-cells = <1>;
254            };
255    };
256
257    /* ... */
258
259    thermal-zones {
260            cpu0-thermal {
261                    polling-delay-passive = <250>;
262                    polling-delay = <1000>;
263
264                    thermal-sensors = <&tsens0 1>;
265
266                    trips {
267                            cpu0_alert0: trip-point0 {
268                                    temperature = <90000>;
269                                    hysteresis = <2000>;
270                                    type = "passive";
271                            };
272
273                            cpu0_alert1: trip-point1 {
274                                    temperature = <95000>;
275                                    hysteresis = <2000>;
276                                    type = "passive";
277                            };
278
279                            cpu0_crit: cpu_crit {
280                                    temperature = <110000>;
281                                    hysteresis = <1000>;
282                                    type = "critical";
283                            };
284                    };
285
286                    cooling-maps {
287                            map0 {
288                                    trip = <&cpu0_alert0>;
289                                    /* Corresponds to 1400MHz in OPP table */
290                                    cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
291                                                     <&CPU2 3 3>, <&CPU3 3 3>;
292                            };
293
294                            map1 {
295                                    trip = <&cpu0_alert1>;
296                                    /* Corresponds to 1000MHz in OPP table */
297                                    cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
298                                                     <&CPU2 5 5>, <&CPU3 5 5>;
299                            };
300                    };
301            };
302
303            /* ... */
304
305            cluster0-thermal {
306                    polling-delay-passive = <250>;
307                    polling-delay = <1000>;
308
309                    thermal-sensors = <&tsens0 5>;
310
311                    trips {
312                            cluster0_alert0: trip-point0 {
313                                    temperature = <90000>;
314                                    hysteresis = <2000>;
315                                    type = "hot";
316                            };
317                            cluster0_crit: cluster0_crit {
318                                    temperature = <110000>;
319                                    hysteresis = <2000>;
320                                    type = "critical";
321                            };
322                    };
323            };
324
325            /* ... */
326
327            gpu-top-thermal {
328                    polling-delay-passive = <250>;
329                    polling-delay = <1000>;
330
331                    thermal-sensors = <&tsens0 11>;
332
333                    trips {
334                            gpu1_alert0: trip-point0 {
335                                    temperature = <90000>;
336                                    hysteresis = <2000>;
337                                    type = "hot";
338                            };
339                    };
340            };
341    };
342...
343