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                minimum: 0
203                maximum: 100
204                description:
205                  The percentage contribution of the cooling devices at the
206                  specific trip temperature referenced in this map
207                  to this 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
219    additionalProperties: false
220
221additionalProperties: false
222
223examples:
224  - |
225    #include <dt-bindings/interrupt-controller/arm-gic.h>
226    #include <dt-bindings/thermal/thermal.h>
227
228    // Example 1: SDM845 TSENS
229    soc {
230            #address-cells = <2>;
231            #size-cells = <2>;
232
233            /* ... */
234
235            tsens0: thermal-sensor@c263000 {
236                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
237                    reg = <0 0x0c263000 0 0x1ff>, /* TM */
238                          <0 0x0c222000 0 0x1ff>; /* SROT */
239                    #qcom,sensors = <13>;
240                    interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
241                                 <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
242                    interrupt-names = "uplow", "critical";
243                    #thermal-sensor-cells = <1>;
244            };
245
246            tsens1: thermal-sensor@c265000 {
247                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
248                    reg = <0 0x0c265000 0 0x1ff>, /* TM */
249                          <0 0x0c223000 0 0x1ff>; /* SROT */
250                    #qcom,sensors = <8>;
251                    interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
252                                 <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
253                    interrupt-names = "uplow", "critical";
254                    #thermal-sensor-cells = <1>;
255            };
256    };
257
258    /* ... */
259
260    thermal-zones {
261            cpu0-thermal {
262                    polling-delay-passive = <250>;
263                    polling-delay = <1000>;
264
265                    thermal-sensors = <&tsens0 1>;
266
267                    trips {
268                            cpu0_alert0: trip-point0 {
269                                    temperature = <90000>;
270                                    hysteresis = <2000>;
271                                    type = "passive";
272                            };
273
274                            cpu0_alert1: trip-point1 {
275                                    temperature = <95000>;
276                                    hysteresis = <2000>;
277                                    type = "passive";
278                            };
279
280                            cpu0_crit: cpu_crit {
281                                    temperature = <110000>;
282                                    hysteresis = <1000>;
283                                    type = "critical";
284                            };
285                    };
286
287                    cooling-maps {
288                            map0 {
289                                    trip = <&cpu0_alert0>;
290                                    /* Corresponds to 1400MHz in OPP table */
291                                    cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
292                                                     <&CPU2 3 3>, <&CPU3 3 3>;
293                            };
294
295                            map1 {
296                                    trip = <&cpu0_alert1>;
297                                    /* Corresponds to 1000MHz in OPP table */
298                                    cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
299                                                     <&CPU2 5 5>, <&CPU3 5 5>;
300                            };
301                    };
302            };
303
304            /* ... */
305
306            cluster0-thermal {
307                    polling-delay-passive = <250>;
308                    polling-delay = <1000>;
309
310                    thermal-sensors = <&tsens0 5>;
311
312                    trips {
313                            cluster0_alert0: trip-point0 {
314                                    temperature = <90000>;
315                                    hysteresis = <2000>;
316                                    type = "hot";
317                            };
318                            cluster0_crit: cluster0_crit {
319                                    temperature = <110000>;
320                                    hysteresis = <2000>;
321                                    type = "critical";
322                            };
323                    };
324            };
325
326            /* ... */
327
328            gpu-top-thermal {
329                    polling-delay-passive = <250>;
330                    polling-delay = <1000>;
331
332                    thermal-sensors = <&tsens0 11>;
333
334                    trips {
335                            gpu1_alert0: trip-point0 {
336                                    temperature = <90000>;
337                                    hysteresis = <2000>;
338                                    type = "hot";
339                            };
340                    };
341            };
342    };
343...
344