1 # SPDX-License-Identifier: (GPL-2.0) 1 # SPDX-License-Identifier: (GPL-2.0)
2 # Copyright 2020 Linaro Ltd. 2 # Copyright 2020 Linaro Ltd.
3 %YAML 1.2 3 %YAML 1.2
4 --- 4 ---
5 $id: http://devicetree.org/schemas/thermal/the 5 $id: http://devicetree.org/schemas/thermal/thermal-zones.yaml#
6 $schema: http://devicetree.org/meta-schemas/ba 6 $schema: http://devicetree.org/meta-schemas/base.yaml#
7 7
8 title: Thermal zone 8 title: Thermal zone
9 9
10 maintainers: 10 maintainers:
11 - Daniel Lezcano <daniel.lezcano@linaro.org> 11 - Daniel Lezcano <daniel.lezcano@linaro.org>
12 12
13 description: | 13 description: |
14 Thermal management is achieved in devicetree 14 Thermal management is achieved in devicetree by describing the sensor hardware
15 and the software abstraction of cooling devi 15 and the software abstraction of cooling devices and thermal zones required to
16 take appropriate action to mitigate thermal 16 take appropriate action to mitigate thermal overloads.
17 17
18 The following node types are used to complet 18 The following node types are used to completely describe a thermal management
19 system in devicetree: 19 system in devicetree:
20 - thermal-sensor: device that measures temp 20 - thermal-sensor: device that measures temperature, has SoC-specific bindings
21 - cooling-device: device used to dissipate 21 - cooling-device: device used to dissipate heat either passively or actively
22 - thermal-zones: a container of the followi 22 - thermal-zones: a container of the following node types used to describe all
23 thermal data for the platform 23 thermal data for the platform
24 24
25 This binding describes the thermal-zones. 25 This binding describes the thermal-zones.
26 26
27 The polling-delay properties of a thermal-zo 27 The polling-delay properties of a thermal-zone are bound to the maximum dT/dt
28 (temperature derivative over time) in two si 28 (temperature derivative over time) in two situations for a thermal zone:
29 1. when passive cooling is activated (poll 29 1. when passive cooling is activated (polling-delay-passive)
30 2. when the zone just needs to be monitore 30 2. when the zone just needs to be monitored (polling-delay) or when
31 active cooling is activated. 31 active cooling is activated.
32 32
33 The maximum dT/dt is highly bound to hardwar 33 The maximum dT/dt is highly bound to hardware power consumption and
34 dissipation capability. The delays should be 34 dissipation capability. The delays should be chosen to account for said
35 max dT/dt, such that a device does not cross 35 max dT/dt, such that a device does not cross several trip boundaries
36 unexpectedly between polls. Choosing the rig 36 unexpectedly between polls. Choosing the right polling delays shall avoid
37 having the device in temperature ranges that 37 having the device in temperature ranges that may damage the silicon structures
38 and reduce silicon lifetime. 38 and reduce silicon lifetime.
39 39
40 properties: 40 properties:
41 $nodename: 41 $nodename:
42 const: thermal-zones 42 const: thermal-zones
43 description: 43 description:
44 A /thermal-zones node is required in ord 44 A /thermal-zones node is required in order to use the thermal framework to
45 manage input from the various thermal zo 45 manage input from the various thermal zones in the system in order to
46 mitigate thermal overload conditions. It 46 mitigate thermal overload conditions. It does not represent a real device
47 in the system, but acts as a container t 47 in the system, but acts as a container to link a thermal sensor device,
48 platform-data regarding temperature thre 48 platform-data regarding temperature thresholds and the mitigation actions
49 to take when the temperature crosses tho 49 to take when the temperature crosses those thresholds.
50 50
51 patternProperties: 51 patternProperties:
52 # Node name is limited in size due to Linux 52 # Node name is limited in size due to Linux kernel requirements - 19
53 # characters in total (see THERMAL_NAME_LENG 53 # characters in total (see THERMAL_NAME_LENGTH, including terminating NUL
54 # byte): 54 # byte):
55 "^[a-zA-Z][a-zA-Z0-9\\-]{1,10}-thermal$": 55 "^[a-zA-Z][a-zA-Z0-9\\-]{1,10}-thermal$":
56 type: object 56 type: object
57 description: 57 description:
58 Each thermal zone node contains informat 58 Each thermal zone node contains information about how frequently it
59 must be checked, the sensor responsible 59 must be checked, the sensor responsible for reporting temperature for
60 this zone, one sub-node containing the v 60 this zone, one sub-node containing the various trip points for this
61 zone and one sub-node containing all the 61 zone and one sub-node containing all the zone cooling-maps.
62 62
63 properties: 63 properties:
64 polling-delay: 64 polling-delay:
65 $ref: /schemas/types.yaml#/definitions 65 $ref: /schemas/types.yaml#/definitions/uint32
66 description: 66 description:
67 The maximum number of milliseconds t 67 The maximum number of milliseconds to wait between polls when
68 checking this thermal zone. Setting 68 checking this thermal zone. Setting this to 0 disables the polling
69 timers setup by the thermal framewor 69 timers setup by the thermal framework and assumes that the thermal
70 sensors in this zone support interru 70 sensors in this zone support interrupts.
71 71
72 polling-delay-passive: 72 polling-delay-passive:
73 $ref: /schemas/types.yaml#/definitions 73 $ref: /schemas/types.yaml#/definitions/uint32
74 description: 74 description:
75 The maximum number of milliseconds t 75 The maximum number of milliseconds to wait between polls when
76 checking this thermal zone while doi 76 checking this thermal zone while doing passive cooling. Setting
77 this to 0 disables the polling timer 77 this to 0 disables the polling timers setup by the thermal
78 framework and assumes that the therm 78 framework and assumes that the thermal sensors in this zone
79 support interrupts. 79 support interrupts.
80 80
81 critical-action: 81 critical-action:
82 $ref: /schemas/types.yaml#/definitions 82 $ref: /schemas/types.yaml#/definitions/string
83 description: | 83 description: |
84 The action the OS should perform aft 84 The action the OS should perform after the critical temperature is reached.
85 By default the system will shutdown 85 By default the system will shutdown as a safe action to prevent damage
86 to the hardware, if the property is 86 to the hardware, if the property is not set.
87 The shutdown action should be always 87 The shutdown action should be always the default and preferred one.
88 Choose 'reboot' with care, as the ha 88 Choose 'reboot' with care, as the hardware may be in thermal stress,
89 thus leading to infinite reboots tha 89 thus leading to infinite reboots that may cause damage to the hardware.
90 Make sure the firmware/bootloader wi 90 Make sure the firmware/bootloader will act as the last resort and take
91 over the thermal control. 91 over the thermal control.
92 92
93 enum: 93 enum:
94 - shutdown 94 - shutdown
95 - reboot 95 - reboot
96 96
97 thermal-sensors: 97 thermal-sensors:
98 $ref: /schemas/types.yaml#/definitions 98 $ref: /schemas/types.yaml#/definitions/phandle-array
99 maxItems: 1 99 maxItems: 1
100 description: 100 description:
101 The thermal sensor phandle and senso 101 The thermal sensor phandle and sensor specifier used to monitor this
102 thermal zone. 102 thermal zone.
103 103
104 coefficients: 104 coefficients:
105 $ref: /schemas/types.yaml#/definitions 105 $ref: /schemas/types.yaml#/definitions/uint32-array
106 description: 106 description:
107 An array of integers containing the 107 An array of integers containing the coefficients of a linear equation
108 that binds all the sensors listed in 108 that binds all the sensors listed in this thermal zone.
109 109
110 The linear equation used is as follo 110 The linear equation used is as follows,
111 z = c0 * x0 + c1 * x1 + ... + c(n- 111 z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn
112 where c0, c1, .., cn are the coeffic 112 where c0, c1, .., cn are the coefficients.
113 113
114 Coefficients default to 1 in case th 114 Coefficients default to 1 in case this property is not specified. The
115 coefficients are ordered and are mat 115 coefficients are ordered and are matched with sensors by means of the
116 sensor ID. Additional coefficients a 116 sensor ID. Additional coefficients are interpreted as constant offset.
117 117
118 sustainable-power: 118 sustainable-power:
119 $ref: /schemas/types.yaml#/definitions 119 $ref: /schemas/types.yaml#/definitions/uint32
120 description: 120 description:
121 An estimate of the sustainable power 121 An estimate of the sustainable power (in mW) that this thermal zone
122 can dissipate at the desired control 122 can dissipate at the desired control temperature. For reference, the
123 sustainable power of a 4-inch phone 123 sustainable power of a 4-inch phone is typically 2000mW, while on a
124 10-inch tablet is around 4500mW. 124 10-inch tablet is around 4500mW.
125 125
126 trips: 126 trips:
127 type: object 127 type: object
128 description: 128 description:
129 This node describes a set of points 129 This node describes a set of points in the temperature domain at
130 which the thermal framework needs to 130 which the thermal framework needs to take action. The actions to
131 be taken are defined in another node 131 be taken are defined in another node called cooling-maps.
132 132
133 patternProperties: 133 patternProperties:
134 "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$": 134 "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
135 type: object 135 type: object
136 136
137 properties: 137 properties:
138 temperature: 138 temperature:
139 $ref: /schemas/types.yaml#/def 139 $ref: /schemas/types.yaml#/definitions/int32
140 minimum: -273000 140 minimum: -273000
141 maximum: 200000 141 maximum: 200000
142 description: 142 description:
143 An integer expressing the tr 143 An integer expressing the trip temperature in millicelsius.
144 144
145 hysteresis: 145 hysteresis:
146 $ref: /schemas/types.yaml#/def 146 $ref: /schemas/types.yaml#/definitions/uint32
147 description: 147 description:
148 An unsigned integer expressi 148 An unsigned integer expressing the hysteresis delta with
149 respect to the trip temperat 149 respect to the trip temperature property above, also in
150 millicelsius. Any cooling ac 150 millicelsius. Any cooling action initiated by the framework is
151 maintained until the tempera 151 maintained until the temperature falls below
152 (trip temperature - hysteres 152 (trip temperature - hysteresis). This potentially prevents a
153 situation where the trip get 153 situation where the trip gets constantly triggered soon after
154 cooling action is removed. 154 cooling action is removed.
155 155
156 type: 156 type:
157 $ref: /schemas/types.yaml#/def 157 $ref: /schemas/types.yaml#/definitions/string
158 enum: 158 enum:
159 - active # enable active c 159 - active # enable active cooling e.g. fans
160 - passive # enable passive 160 - passive # enable passive cooling e.g. throttling cpu
161 - hot # send notificati 161 - hot # send notification to driver
162 - critical # send notificati 162 - critical # send notification to driver, trigger shutdown
163 description: | 163 description: |
164 There are four valid trip ty 164 There are four valid trip types: active, passive, hot,
165 critical. 165 critical.
166 166
167 The critical trip type is us 167 The critical trip type is used to set the maximum
168 temperature threshold above 168 temperature threshold above which the HW becomes
169 unstable and underlying firm 169 unstable and underlying firmware might even trigger a
170 reboot. Hitting the critical 170 reboot. Hitting the critical threshold triggers a system
171 shutdown. 171 shutdown.
172 172
173 The hot trip type can be use 173 The hot trip type can be used to send a notification to
174 the thermal driver (if a .no 174 the thermal driver (if a .notify callback is registered).
175 The action to be taken is le 175 The action to be taken is left to the driver.
176 176
177 The passive trip type can be 177 The passive trip type can be used to slow down HW e.g. run
178 the CPU, GPU, bus at a lower 178 the CPU, GPU, bus at a lower frequency.
179 179
180 The active trip type can be 180 The active trip type can be used to control other HW to
181 help in cooling e.g. fans ca 181 help in cooling e.g. fans can be sped up or slowed down
182 182
183 required: 183 required:
184 - temperature 184 - temperature
185 - hysteresis 185 - hysteresis
186 - type 186 - type
187 additionalProperties: false 187 additionalProperties: false
188 188
189 additionalProperties: false 189 additionalProperties: false
190 190
191 cooling-maps: 191 cooling-maps:
192 type: object 192 type: object
193 additionalProperties: false 193 additionalProperties: false
194 description: 194 description:
195 This node describes the action to be 195 This node describes the action to be taken when a thermal zone
196 crosses one of the temperature thres 196 crosses one of the temperature thresholds described in the trips
197 node. The action takes the form of a 197 node. The action takes the form of a mapping relation between a
198 trip and the target cooling device s 198 trip and the target cooling device state.
199 199
200 patternProperties: 200 patternProperties:
201 "^map[-a-zA-Z0-9]*$": 201 "^map[-a-zA-Z0-9]*$":
202 type: object 202 type: object
203 203
204 properties: 204 properties:
205 trip: 205 trip:
206 $ref: /schemas/types.yaml#/def 206 $ref: /schemas/types.yaml#/definitions/phandle
207 description: 207 description:
208 A phandle of a trip point no 208 A phandle of a trip point node within this thermal zone.
209 209
210 cooling-device: 210 cooling-device:
211 $ref: /schemas/types.yaml#/def 211 $ref: /schemas/types.yaml#/definitions/phandle-array
212 description: 212 description:
213 A list of cooling device pha 213 A list of cooling device phandles along with the minimum
214 and maximum cooling state sp 214 and maximum cooling state specifiers for each cooling
215 device. Using the THERMAL_NO 215 device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
216 cooling-device phandle limit 216 cooling-device phandle limit specifier lets the framework
217 use the minimum and maximum 217 use the minimum and maximum cooling state for that cooling
218 device automatically. 218 device automatically.
219 219
220 contribution: 220 contribution:
221 $ref: /schemas/types.yaml#/def 221 $ref: /schemas/types.yaml#/definitions/uint32
222 description: 222 description:
223 The cooling contribution to 223 The cooling contribution to the thermal zone of the referred
224 cooling device at the referr 224 cooling device at the referred trip point. The contribution is
225 a ratio of the sum of all co 225 a ratio of the sum of all cooling contributions within a
226 thermal zone. 226 thermal zone.
227 227
228 required: 228 required:
229 - trip 229 - trip
230 - cooling-device 230 - cooling-device
231 additionalProperties: false 231 additionalProperties: false
232 232
233 required: 233 required:
234 - thermal-sensors 234 - thermal-sensors
235 235
236 additionalProperties: false 236 additionalProperties: false
237 237
238 additionalProperties: false 238 additionalProperties: false
239 239
240 examples: 240 examples:
241 - | 241 - |
242 #include <dt-bindings/interrupt-controller 242 #include <dt-bindings/interrupt-controller/arm-gic.h>
243 #include <dt-bindings/thermal/thermal.h> 243 #include <dt-bindings/thermal/thermal.h>
244 244
245 // Example 1: SDM845 TSENS 245 // Example 1: SDM845 TSENS
246 soc { 246 soc {
247 #address-cells = <2>; 247 #address-cells = <2>;
248 #size-cells = <2>; 248 #size-cells = <2>;
249 249
250 /* ... */ 250 /* ... */
251 251
252 tsens0: thermal-sensor@c263000 { 252 tsens0: thermal-sensor@c263000 {
253 compatible = "qcom,sdm845- 253 compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
254 reg = <0 0x0c263000 0 0x1f 254 reg = <0 0x0c263000 0 0x1ff>, /* TM */
255 <0 0x0c222000 0 0x1f 255 <0 0x0c222000 0 0x1ff>; /* SROT */
256 #qcom,sensors = <13>; 256 #qcom,sensors = <13>;
257 interrupts = <GIC_SPI 506 257 interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
258 <GIC_SPI 508 258 <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
259 interrupt-names = "uplow", 259 interrupt-names = "uplow", "critical";
260 #thermal-sensor-cells = <1 260 #thermal-sensor-cells = <1>;
261 }; 261 };
262 262
263 tsens1: thermal-sensor@c265000 { 263 tsens1: thermal-sensor@c265000 {
264 compatible = "qcom,sdm845- 264 compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
265 reg = <0 0x0c265000 0 0x1f 265 reg = <0 0x0c265000 0 0x1ff>, /* TM */
266 <0 0x0c223000 0 0x1f 266 <0 0x0c223000 0 0x1ff>; /* SROT */
267 #qcom,sensors = <8>; 267 #qcom,sensors = <8>;
268 interrupts = <GIC_SPI 507 268 interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
269 <GIC_SPI 509 269 <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
270 interrupt-names = "uplow", 270 interrupt-names = "uplow", "critical";
271 #thermal-sensor-cells = <1 271 #thermal-sensor-cells = <1>;
272 }; 272 };
273 }; 273 };
274 274
275 /* ... */ 275 /* ... */
276 276
277 thermal-zones { 277 thermal-zones {
278 cpu0-thermal { 278 cpu0-thermal {
279 polling-delay-passive = <2 279 polling-delay-passive = <250>;
280 polling-delay = <1000>; 280 polling-delay = <1000>;
281 281
282 thermal-sensors = <&tsens0 282 thermal-sensors = <&tsens0 1>;
283 283
284 trips { 284 trips {
285 cpu0_alert0: trip- 285 cpu0_alert0: trip-point0 {
286 temperatur 286 temperature = <90000>;
287 hysteresis 287 hysteresis = <2000>;
288 type = "pa 288 type = "passive";
289 }; 289 };
290 290
291 cpu0_alert1: trip- 291 cpu0_alert1: trip-point1 {
292 temperatur 292 temperature = <95000>;
293 hysteresis 293 hysteresis = <2000>;
294 type = "pa 294 type = "passive";
295 }; 295 };
296 296
297 cpu0_crit: cpu_cri 297 cpu0_crit: cpu_crit {
298 temperatur 298 temperature = <110000>;
299 hysteresis 299 hysteresis = <1000>;
300 type = "cr 300 type = "critical";
301 }; 301 };
302 }; 302 };
303 303
304 cooling-maps { 304 cooling-maps {
305 map0 { 305 map0 {
306 trip = <&c 306 trip = <&cpu0_alert0>;
307 /* Corresp 307 /* Corresponds to 1400MHz in OPP table */
308 cooling-de 308 cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
309 309 <&CPU2 3 3>, <&CPU3 3 3>;
310 }; 310 };
311 311
312 map1 { 312 map1 {
313 trip = <&c 313 trip = <&cpu0_alert1>;
314 /* Corresp 314 /* Corresponds to 1000MHz in OPP table */
315 cooling-de 315 cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
316 316 <&CPU2 5 5>, <&CPU3 5 5>;
317 }; 317 };
318 }; 318 };
319 }; 319 };
320 320
321 /* ... */ 321 /* ... */
322 322
323 cluster0-thermal { 323 cluster0-thermal {
324 polling-delay-passive = <2 324 polling-delay-passive = <250>;
325 polling-delay = <1000>; 325 polling-delay = <1000>;
326 326
327 thermal-sensors = <&tsens0 327 thermal-sensors = <&tsens0 5>;
328 328
329 trips { 329 trips {
330 cluster0_alert0: t 330 cluster0_alert0: trip-point0 {
331 temperatur 331 temperature = <90000>;
332 hysteresis 332 hysteresis = <2000>;
333 type = "ho 333 type = "hot";
334 }; 334 };
335 cluster0_crit: clu 335 cluster0_crit: cluster0_crit {
336 temperatur 336 temperature = <110000>;
337 hysteresis 337 hysteresis = <2000>;
338 type = "cr 338 type = "critical";
339 }; 339 };
340 }; 340 };
341 }; 341 };
342 342
343 /* ... */ 343 /* ... */
344 344
345 gpu-top-thermal { 345 gpu-top-thermal {
346 polling-delay-passive = <2 346 polling-delay-passive = <250>;
347 polling-delay = <1000>; 347 polling-delay = <1000>;
348 348
349 thermal-sensors = <&tsens0 349 thermal-sensors = <&tsens0 11>;
350 350
351 trips { 351 trips {
352 gpu1_alert0: trip- 352 gpu1_alert0: trip-point0 {
353 temperatur 353 temperature = <90000>;
354 hysteresis 354 hysteresis = <2000>;
355 type = "ho 355 type = "hot";
356 }; 356 };
357 }; 357 };
358 }; 358 };
359 }; 359 };
360 ... 360 ...
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.