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