summaryrefslogtreecommitdiffstats
path: root/Documentation/devicetree/bindings/thermal/thermal-zones.yaml
blob: 164f71598c5956fa16b21284ba1e2c3d3523dca8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
# SPDX-License-Identifier: (GPL-2.0)
# Copyright 2020 Linaro Ltd.
%YAML 1.2
---
$id: http://devicetree.org/schemas/thermal/thermal-zones.yaml#
$schema: http://devicetree.org/meta-schemas/base.yaml#

title: Thermal zone binding

maintainers:
  - Amit Kucheria <amitk@kernel.org>

description: |
  Thermal management is achieved in devicetree by describing the sensor hardware
  and the software abstraction of cooling devices and thermal zones required to
  take appropriate action to mitigate thermal overloads.

  The following node types are used to completely describe a thermal management
  system in devicetree:
   - thermal-sensor: device that measures temperature, has SoC-specific bindings
   - cooling-device: device used to dissipate heat either passively or actively
   - thermal-zones: a container of the following node types used to describe all
     thermal data for the platform

  This binding describes the thermal-zones.

  The polling-delay properties of a thermal-zone are bound to the maximum dT/dt
  (temperature derivative over time) in two situations for a thermal zone:
    1. when passive cooling is activated (polling-delay-passive)
    2. when the zone just needs to be monitored (polling-delay) or when
       active cooling is activated.

  The maximum dT/dt is highly bound to hardware power consumption and
  dissipation capability. The delays should be chosen to account for said
  max dT/dt, such that a device does not cross several trip boundaries
  unexpectedly between polls. Choosing the right polling delays shall avoid
  having the device in temperature ranges that may damage the silicon structures
  and reduce silicon lifetime.

properties:
  $nodename:
    const: thermal-zones
    description:
      A /thermal-zones node is required in order to use the thermal framework to
      manage input from the various thermal zones in the system in order to
      mitigate thermal overload conditions. It does not represent a real device
      in the system, but acts as a container to link a thermal sensor device,
      platform-data regarding temperature thresholds and the mitigation actions
      to take when the temperature crosses those thresholds.

patternProperties:
  "^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$":
    type: object
    description:
      Each thermal zone node contains information about how frequently it
      must be checked, the sensor responsible for reporting temperature for
      this zone, one sub-node containing the various trip points for this
      zone and one sub-node containing all the zone cooling-maps.

    properties:
      polling-delay:
        $ref: /schemas/types.yaml#/definitions/uint32
        description:
          The maximum number of milliseconds to wait between polls when
          checking this thermal zone. Setting this to 0 disables the polling
          timers setup by the thermal framework and assumes that the thermal
          sensors in this zone support interrupts.

      polling-delay-passive:
        $ref: /schemas/types.yaml#/definitions/uint32
        description:
          The maximum number of milliseconds to wait between polls when
          checking this thermal zone while doing passive cooling. Setting
          this to 0 disables the polling timers setup by the thermal
          framework and assumes that the thermal sensors in this zone
          support interrupts.

      thermal-sensors:
        $ref: /schemas/types.yaml#/definitions/phandle-array
        maxItems: 1
        description:
          The thermal sensor phandle and sensor specifier used to monitor this
          thermal zone.

      coefficients:
        $ref: /schemas/types.yaml#/definitions/uint32-array
        description:
          An array of integers containing the coefficients of a linear equation
          that binds all the sensors listed in this thermal zone.

          The linear equation used is as follows,
            z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn
          where c0, c1, .., cn are the coefficients.

          Coefficients default to 1 in case this property is not specified. The
          coefficients are ordered and are matched with sensors by means of the
          sensor ID. Additional coefficients are interpreted as constant offset.

      sustainable-power:
        $ref: /schemas/types.yaml#/definitions/uint32
        description:
          An estimate of the sustainable power (in mW) that this thermal zone
          can dissipate at the desired control temperature. For reference, the
          sustainable power of a 4-inch phone is typically 2000mW, while on a
          10-inch tablet is around 4500mW.

      trips:
        type: object
        description:
          This node describes a set of points in the temperature domain at
          which the thermal framework needs to take action. The actions to
          be taken are defined in another node called cooling-maps.

        patternProperties:
          "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
            type: object

            properties:
              temperature:
                $ref: /schemas/types.yaml#/definitions/int32
                minimum: -273000
                maximum: 200000
                description:
                  An integer expressing the trip temperature in millicelsius.

              hysteresis:
                $ref: /schemas/types.yaml#/definitions/uint32
                description:
                  An unsigned integer expressing the hysteresis delta with
                  respect to the trip temperature property above, also in
                  millicelsius. Any cooling action initiated by the framework is
                  maintained until the temperature falls below
                  (trip temperature - hysteresis). This potentially prevents a
                  situation where the trip gets constantly triggered soon after
                  cooling action is removed.

              type:
                $ref: /schemas/types.yaml#/definitions/string
                enum:
                  - active   # enable active cooling e.g. fans
                  - passive  # enable passive cooling e.g. throttling cpu
                  - hot      # send notification to driver
                  - critical # send notification to driver, trigger shutdown
                description: |
                  There are four valid trip types: active, passive, hot,
                  critical.

                  The critical trip type is used to set the maximum
                  temperature threshold above which the HW becomes
                  unstable and underlying firmware might even trigger a
                  reboot. Hitting the critical threshold triggers a system
                  shutdown.

                  The hot trip type can be used to send a notification to
                  the thermal driver (if a .notify callback is registered).
                  The action to be taken is left to the driver.

                  The passive trip type can be used to slow down HW e.g. run
                  the CPU, GPU, bus at a lower frequency.

                  The active trip type can be used to control other HW to
                  help in cooling e.g. fans can be sped up or slowed down

            required:
              - temperature
              - hysteresis
              - type
            additionalProperties: false

        additionalProperties: false

      cooling-maps:
        type: object
        description:
          This node describes the action to be taken when a thermal zone
          crosses one of the temperature thresholds described in the trips
          node. The action takes the form of a mapping relation between a
          trip and the target cooling device state.

        patternProperties:
          "^map[-a-zA-Z0-9]*$":
            type: object

            properties:
              trip:
                $ref: /schemas/types.yaml#/definitions/phandle
                description:
                  A phandle of a trip point node within this thermal zone.

              cooling-device:
                $ref: /schemas/types.yaml#/definitions/phandle-array
                description:
                  A list of cooling device phandles along with the minimum
                  and maximum cooling state specifiers for each cooling
                  device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
                  cooling-device phandle limit specifier lets the framework
                  use the minimum and maximum cooling state for that cooling
                  device automatically.

              contribution:
                $ref: /schemas/types.yaml#/definitions/uint32
                minimum: 0
                maximum: 100
                description:
                  The percentage contribution of the cooling devices at the
                  specific trip temperature referenced in this map
                  to this thermal zone

            required:
              - trip
              - cooling-device
            additionalProperties: false

    required:
      - polling-delay
      - polling-delay-passive
      - thermal-sensors
      - trips
    additionalProperties: false

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/thermal/thermal.h>

    // Example 1: SDM845 TSENS
    soc {
            #address-cells = <2>;
            #size-cells = <2>;

            /* ... */

            tsens0: thermal-sensor@c263000 {
                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
                    reg = <0 0x0c263000 0 0x1ff>, /* TM */
                          <0 0x0c222000 0 0x1ff>; /* SROT */
                    #qcom,sensors = <13>;
                    interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
                                 <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
                    interrupt-names = "uplow", "critical";
                    #thermal-sensor-cells = <1>;
            };

            tsens1: thermal-sensor@c265000 {
                    compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
                    reg = <0 0x0c265000 0 0x1ff>, /* TM */
                          <0 0x0c223000 0 0x1ff>; /* SROT */
                    #qcom,sensors = <8>;
                    interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
                                 <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
                    interrupt-names = "uplow", "critical";
                    #thermal-sensor-cells = <1>;
            };
    };

    /* ... */

    thermal-zones {
            cpu0-thermal {
                    polling-delay-passive = <250>;
                    polling-delay = <1000>;

                    thermal-sensors = <&tsens0 1>;

                    trips {
                            cpu0_alert0: trip-point0 {
                                    temperature = <90000>;
                                    hysteresis = <2000>;
                                    type = "passive";
                            };

                            cpu0_alert1: trip-point1 {
                                    temperature = <95000>;
                                    hysteresis = <2000>;
                                    type = "passive";
                            };

                            cpu0_crit: cpu_crit {
                                    temperature = <110000>;
                                    hysteresis = <1000>;
                                    type = "critical";
                            };
                    };

                    cooling-maps {
                            map0 {
                                    trip = <&cpu0_alert0>;
                                    /* Corresponds to 1400MHz in OPP table */
                                    cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
                                                     <&CPU2 3 3>, <&CPU3 3 3>;
                            };

                            map1 {
                                    trip = <&cpu0_alert1>;
                                    /* Corresponds to 1000MHz in OPP table */
                                    cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
                                                     <&CPU2 5 5>, <&CPU3 5 5>;
                            };
                    };
            };

            /* ... */

            cluster0-thermal {
                    polling-delay-passive = <250>;
                    polling-delay = <1000>;

                    thermal-sensors = <&tsens0 5>;

                    trips {
                            cluster0_alert0: trip-point0 {
                                    temperature = <90000>;
                                    hysteresis = <2000>;
                                    type = "hot";
                            };
                            cluster0_crit: cluster0_crit {
                                    temperature = <110000>;
                                    hysteresis = <2000>;
                                    type = "critical";
                            };
                    };
            };

            /* ... */

            gpu-top-thermal {
                    polling-delay-passive = <250>;
                    polling-delay = <1000>;

                    thermal-sensors = <&tsens0 11>;

                    trips {
                            gpu1_alert0: trip-point0 {
                                    temperature = <90000>;
                                    hysteresis = <2000>;
                                    type = "hot";
                            };
                    };
            };
    };
...