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