]> git.kernelconcepts.de Git - karo-tx-linux.git/blob - Documentation/devicetree/bindings/thermal/thermal.txt
Merge remote-tracking branch 'regulator/topic/list' into regulator-next
[karo-tx-linux.git] / Documentation / devicetree / bindings / thermal / thermal.txt
1 * Thermal Framework Device Tree descriptor
2
3 This file describes a generic binding to provide a way of
4 defining hardware thermal structure using device tree.
5 A thermal structure includes thermal zones and their components,
6 such as trip points, polling intervals, sensors and cooling devices
7 binding descriptors.
8
9 The target of device tree thermal descriptors is to describe only
10 the hardware thermal aspects. The thermal device tree bindings are
11 not about how the system must control or which algorithm or policy
12 must be taken in place.
13
14 There are five types of nodes involved to describe thermal bindings:
15 - thermal sensors: devices which may be used to take temperature
16   measurements.
17 - cooling devices: devices which may be used to dissipate heat.
18 - trip points: describe key temperatures at which cooling is recommended. The
19   set of points should be chosen based on hardware limits.
20 - cooling maps: used to describe links between trip points and cooling devices;
21 - thermal zones: used to describe thermal data within the hardware;
22
23 The following is a description of each of these node types.
24
25 * Thermal sensor devices
26
27 Thermal sensor devices are nodes providing temperature sensing capabilities on
28 thermal zones. Typical devices are I2C ADC converters and bandgaps. These are
29 nodes providing temperature data to thermal zones. Thermal sensor devices may
30 control one or more internal sensors.
31
32 Required property:
33 - #thermal-sensor-cells: Used to provide sensor device specific information
34   Type: unsigned         while referring to it. Typically 0 on thermal sensor
35   Size: one cell         nodes with only one sensor, and at least 1 on nodes
36                          with several internal sensors, in order
37                          to identify uniquely the sensor instances within
38                          the IC. See thermal zone binding for more details
39                          on how consumers refer to sensor devices.
40
41 * Cooling device nodes
42
43 Cooling devices are nodes providing control on power dissipation. There
44 are essentially two ways to provide control on power dissipation. First
45 is by means of regulating device performance, which is known as passive
46 cooling. A typical passive cooling is a CPU that has dynamic voltage and
47 frequency scaling (DVFS), and uses lower frequencies as cooling states.
48 Second is by means of activating devices in order to remove
49 the dissipated heat, which is known as active cooling, e.g. regulating
50 fan speeds. In both cases, cooling devices shall have a way to determine
51 the state of cooling in which the device is.
52
53 Any cooling device has a range of cooling states (i.e. different levels
54 of heat dissipation). For example a fan's cooling states correspond to
55 the different fan speeds possible. Cooling states are referred to by
56 single unsigned integers, where larger numbers mean greater heat
57 dissipation. The precise set of cooling states associated with a device
58 (as referred to by the cooling-min-level and cooling-max-level
59 properties) should be defined in a particular device's binding.
60 For more examples of cooling devices, refer to the example sections below.
61
62 Required properties:
63 - #cooling-cells:       Used to provide cooling device specific information
64   Type: unsigned        while referring to it. Must be at least 2, in order
65   Size: one cell        to specify minimum and maximum cooling state used
66                         in the reference. The first cell is the minimum
67                         cooling state requested and the second cell is
68                         the maximum cooling state requested in the reference.
69                         See Cooling device maps section below for more details
70                         on how consumers refer to cooling devices.
71
72 Optional properties:
73 - cooling-min-level:    An integer indicating the smallest
74   Type: unsigned        cooling state accepted. Typically 0.
75   Size: one cell
76
77 - cooling-max-level:    An integer indicating the largest
78   Type: unsigned        cooling state accepted.
79   Size: one cell
80
81 * Trip points
82
83 The trip node is a node to describe a point in the temperature domain
84 in which the system takes an action. This node describes just the point,
85 not the action.
86
87 Required properties:
88 - temperature:          An integer indicating the trip temperature level,
89   Type: signed          in millicelsius.
90   Size: one cell
91
92 - hysteresis:           A low hysteresis value on temperature property (above).
93   Type: unsigned        This is a relative value, in millicelsius.
94   Size: one cell
95
96 - type:                 a string containing the trip type. Expected values are:
97         "active":       A trip point to enable active cooling
98         "passive":      A trip point to enable passive cooling
99         "hot":          A trip point to notify emergency
100         "critical":     Hardware not reliable.
101   Type: string
102
103 * Cooling device maps
104
105 The cooling device maps node is a node to describe how cooling devices
106 get assigned to trip points of the zone. The cooling devices are expected
107 to be loaded in the target system.
108
109 Required properties:
110 - cooling-device:       A phandle of a cooling device with its specifier,
111   Type: phandle +       referring to which cooling device is used in this
112     cooling specifier   binding. In the cooling specifier, the first cell
113                         is the minimum cooling state and the second cell
114                         is the maximum cooling state used in this map.
115 - trip:                 A phandle of a trip point node within the same thermal
116   Type: phandle of      zone.
117    trip point node
118
119 Optional property:
120 - contribution:         The cooling contribution to the thermal zone of the
121   Type: unsigned        referred cooling device at the referred trip point.
122   Size: one cell        The contribution is a ratio of the sum
123                         of all cooling contributions within a thermal zone.
124
125 Note: Using the THERMAL_NO_LIMIT (-1UL) constant in the cooling-device phandle
126 limit specifier means:
127 (i)   - minimum state allowed for minimum cooling state used in the reference.
128 (ii)  - maximum state allowed for maximum cooling state used in the reference.
129 Refer to include/dt-bindings/thermal/thermal.h for definition of this constant.
130
131 * Thermal zone nodes
132
133 The thermal zone node is the node containing all the required info
134 for describing a thermal zone, including its cooling device bindings. The
135 thermal zone node must contain, apart from its own properties, one sub-node
136 containing trip nodes and one sub-node containing all the zone cooling maps.
137
138 Required properties:
139 - polling-delay:        The maximum number of milliseconds to wait between polls
140   Type: unsigned        when checking this thermal zone.
141   Size: one cell
142
143 - polling-delay-passive: The maximum number of milliseconds to wait
144   Type: unsigned        between polls when performing passive cooling.
145   Size: one cell
146
147 - thermal-sensors:      A list of thermal sensor phandles and sensor specifier
148   Type: list of         used while monitoring the thermal zone.
149   phandles + sensor
150   specifier
151
152 - trips:                A sub-node which is a container of only trip point nodes
153   Type: sub-node        required to describe the thermal zone.
154
155 - cooling-maps:         A sub-node which is a container of only cooling device
156   Type: sub-node        map nodes, used to describe the relation between trips
157                         and cooling devices.
158
159 Optional property:
160 - coefficients:         An array of integers (one signed cell) containing
161   Type: array           coefficients to compose a linear relation between
162   Elem size: one cell   the sensors listed in the thermal-sensors property.
163   Elem type: signed     Coefficients defaults to 1, in case this property
164                         is not specified. A simple linear polynomial is used:
165                         Z = c0 * x0 + c1 + x1 + ... + c(n-1) * x(n-1) + cn.
166
167                         The coefficients are ordered and they match with sensors
168                         by means of sensor ID. Additional coefficients are
169                         interpreted as constant offset.
170
171 - sustainable-power:    An estimate of the sustainable power (in mW) that the
172   Type: unsigned        thermal zone can dissipate at the desired
173   Size: one cell        control temperature.  For reference, the
174                         sustainable power of a 4'' phone is typically
175                         2000mW, while on a 10'' tablet is around
176                         4500mW.
177
178 Note: The delay properties are bound to the maximum dT/dt (temperature
179 derivative over time) in two situations for a thermal zone:
180 (i)  - when passive cooling is activated (polling-delay-passive); and
181 (ii) - when the zone just needs to be monitored (polling-delay) or
182 when active cooling is activated.
183
184 The maximum dT/dt is highly bound to hardware power consumption and dissipation
185 capability. The delays should be chosen to account for said max dT/dt,
186 such that a device does not cross several trip boundaries unexpectedly
187 between polls. Choosing the right polling delays shall avoid having the
188 device in temperature ranges that may damage the silicon structures and
189 reduce silicon lifetime.
190
191 * The thermal-zones node
192
193 The "thermal-zones" node is a container for all thermal zone nodes. It shall
194 contain only sub-nodes describing thermal zones as in the section
195 "Thermal zone nodes". The "thermal-zones" node appears under "/".
196
197 * Examples
198
199 Below are several examples on how to use thermal data descriptors
200 using device tree bindings:
201
202 (a) - CPU thermal zone
203
204 The CPU thermal zone example below describes how to setup one thermal zone
205 using one single sensor as temperature source and many cooling devices and
206 power dissipation control sources.
207
208 #include <dt-bindings/thermal/thermal.h>
209
210 cpus {
211         /*
212          * Here is an example of describing a cooling device for a DVFS
213          * capable CPU. The CPU node describes its four OPPs.
214          * The cooling states possible are 0..3, and they are
215          * used as OPP indexes. The minimum cooling state is 0, which means
216          * all four OPPs can be available to the system. The maximum
217          * cooling state is 3, which means only the lowest OPPs (198MHz@0.85V)
218          * can be available in the system.
219          */
220         cpu0: cpu@0 {
221                 ...
222                 operating-points = <
223                         /* kHz    uV */
224                         970000  1200000
225                         792000  1100000
226                         396000  950000
227                         198000  850000
228                 >;
229                 cooling-min-level = <0>;
230                 cooling-max-level = <3>;
231                 #cooling-cells = <2>; /* min followed by max */
232         };
233         ...
234 };
235
236 &i2c1 {
237         ...
238         /*
239          * A simple fan controller which supports 10 speeds of operation
240          * (represented as 0-9).
241          */
242         fan0: fan@0x48 {
243                 ...
244                 cooling-min-level = <0>;
245                 cooling-max-level = <9>;
246                 #cooling-cells = <2>; /* min followed by max */
247         };
248 };
249
250 ocp {
251         ...
252         /*
253          * A simple IC with a single bandgap temperature sensor.
254          */
255         bandgap0: bandgap@0x0000ED00 {
256                 ...
257                 #thermal-sensor-cells = <0>;
258         };
259 };
260
261 thermal-zones {
262         cpu_thermal: cpu-thermal {
263                 polling-delay-passive = <250>; /* milliseconds */
264                 polling-delay = <1000>; /* milliseconds */
265
266                 thermal-sensors = <&bandgap0>;
267
268                 trips {
269                         cpu_alert0: cpu-alert0 {
270                                 temperature = <90000>; /* millicelsius */
271                                 hysteresis = <2000>; /* millicelsius */
272                                 type = "active";
273                         };
274                         cpu_alert1: cpu-alert1 {
275                                 temperature = <100000>; /* millicelsius */
276                                 hysteresis = <2000>; /* millicelsius */
277                                 type = "passive";
278                         };
279                         cpu_crit: cpu-crit {
280                                 temperature = <125000>; /* millicelsius */
281                                 hysteresis = <2000>; /* millicelsius */
282                                 type = "critical";
283                         };
284                 };
285
286                 cooling-maps {
287                         map0 {
288                                 trip = <&cpu_alert0>;
289                                 cooling-device = <&fan0 THERMAL_NO_LIMIT 4>;
290                         };
291                         map1 {
292                                 trip = <&cpu_alert1>;
293                                 cooling-device = <&fan0 5 THERMAL_NO_LIMIT>;
294                         };
295                         map2 {
296                                 trip = <&cpu_alert1>;
297                                 cooling-device =
298                                     <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>;
299                         };
300                 };
301         };
302 };
303
304 In the example above, the ADC sensor (bandgap0) at address 0x0000ED00 is
305 used to monitor the zone 'cpu-thermal' using its sole sensor. A fan
306 device (fan0) is controlled via I2C bus 1, at address 0x48, and has ten
307 different cooling states 0-9. It is used to remove the heat out of
308 the thermal zone 'cpu-thermal' using its cooling states
309 from its minimum to 4, when it reaches trip point 'cpu_alert0'
310 at 90C, as an example of active cooling. The same cooling device is used at
311 'cpu_alert1', but from 5 to its maximum state. The cpu@0 device is also
312 linked to the same thermal zone, 'cpu-thermal', as a passive cooling device,
313 using all its cooling states at trip point 'cpu_alert1',
314 which is a trip point at 100C. On the thermal zone 'cpu-thermal', at the
315 temperature of 125C, represented by the trip point 'cpu_crit', the silicon
316 is not reliable anymore.
317
318 (b) - IC with several internal sensors
319
320 The example below describes how to deploy several thermal zones based off a
321 single sensor IC, assuming it has several internal sensors. This is a common
322 case on SoC designs with several internal IPs that may need different thermal
323 requirements, and thus may have their own sensor to monitor or detect internal
324 hotspots in their silicon.
325
326 #include <dt-bindings/thermal/thermal.h>
327
328 ocp {
329         ...
330         /*
331          * A simple IC with several bandgap temperature sensors.
332          */
333         bandgap0: bandgap@0x0000ED00 {
334                 ...
335                 #thermal-sensor-cells = <1>;
336         };
337 };
338
339 thermal-zones {
340         cpu_thermal: cpu-thermal {
341                 polling-delay-passive = <250>; /* milliseconds */
342                 polling-delay = <1000>; /* milliseconds */
343
344                                 /* sensor       ID */
345                 thermal-sensors = <&bandgap0     0>;
346
347                 trips {
348                         /* each zone within the SoC may have its own trips */
349                         cpu_alert: cpu-alert {
350                                 temperature = <100000>; /* millicelsius */
351                                 hysteresis = <2000>; /* millicelsius */
352                                 type = "passive";
353                         };
354                         cpu_crit: cpu-crit {
355                                 temperature = <125000>; /* millicelsius */
356                                 hysteresis = <2000>; /* millicelsius */
357                                 type = "critical";
358                         };
359                 };
360
361                 cooling-maps {
362                         /* each zone within the SoC may have its own cooling */
363                         ...
364                 };
365         };
366
367         gpu_thermal: gpu-thermal {
368                 polling-delay-passive = <120>; /* milliseconds */
369                 polling-delay = <1000>; /* milliseconds */
370
371                                 /* sensor       ID */
372                 thermal-sensors = <&bandgap0     1>;
373
374                 trips {
375                         /* each zone within the SoC may have its own trips */
376                         gpu_alert: gpu-alert {
377                                 temperature = <90000>; /* millicelsius */
378                                 hysteresis = <2000>; /* millicelsius */
379                                 type = "passive";
380                         };
381                         gpu_crit: gpu-crit {
382                                 temperature = <105000>; /* millicelsius */
383                                 hysteresis = <2000>; /* millicelsius */
384                                 type = "critical";
385                         };
386                 };
387
388                 cooling-maps {
389                         /* each zone within the SoC may have its own cooling */
390                         ...
391                 };
392         };
393
394         dsp_thermal: dsp-thermal {
395                 polling-delay-passive = <50>; /* milliseconds */
396                 polling-delay = <1000>; /* milliseconds */
397
398                                 /* sensor       ID */
399                 thermal-sensors = <&bandgap0     2>;
400
401                 trips {
402                         /* each zone within the SoC may have its own trips */
403                         dsp_alert: dsp-alert {
404                                 temperature = <90000>; /* millicelsius */
405                                 hysteresis = <2000>; /* millicelsius */
406                                 type = "passive";
407                         };
408                         dsp_crit: gpu-crit {
409                                 temperature = <135000>; /* millicelsius */
410                                 hysteresis = <2000>; /* millicelsius */
411                                 type = "critical";
412                         };
413                 };
414
415                 cooling-maps {
416                         /* each zone within the SoC may have its own cooling */
417                         ...
418                 };
419         };
420 };
421
422 In the example above, there is one bandgap IC which has the capability to
423 monitor three sensors. The hardware has been designed so that sensors are
424 placed on different places in the DIE to monitor different temperature
425 hotspots: one for CPU thermal zone, one for GPU thermal zone and the
426 other to monitor a DSP thermal zone.
427
428 Thus, there is a need to assign each sensor provided by the bandgap IC
429 to different thermal zones. This is achieved by means of using the
430 #thermal-sensor-cells property and using the first cell of the sensor
431 specifier as sensor ID. In the example, then, <bandgap 0> is used to
432 monitor CPU thermal zone, <bandgap 1> is used to monitor GPU thermal
433 zone and <bandgap 2> is used to monitor DSP thermal zone. Each zone
434 may be uncorrelated, having its own dT/dt requirements, trips
435 and cooling maps.
436
437
438 (c) - Several sensors within one single thermal zone
439
440 The example below illustrates how to use more than one sensor within
441 one thermal zone.
442
443 #include <dt-bindings/thermal/thermal.h>
444
445 &i2c1 {
446         ...
447         /*
448          * A simple IC with a single temperature sensor.
449          */
450         adc: sensor@0x49 {
451                 ...
452                 #thermal-sensor-cells = <0>;
453         };
454 };
455
456 ocp {
457         ...
458         /*
459          * A simple IC with a single bandgap temperature sensor.
460          */
461         bandgap0: bandgap@0x0000ED00 {
462                 ...
463                 #thermal-sensor-cells = <0>;
464         };
465 };
466
467 thermal-zones {
468         cpu_thermal: cpu-thermal {
469                 polling-delay-passive = <250>; /* milliseconds */
470                 polling-delay = <1000>; /* milliseconds */
471
472                 thermal-sensors = <&bandgap0>,  /* cpu */
473                                   <&adc>;       /* pcb north */
474
475                 /* hotspot = 100 * bandgap - 120 * adc + 484 */
476                 coefficients =          <100    -120    484>;
477
478                 trips {
479                         ...
480                 };
481
482                 cooling-maps {
483                         ...
484                 };
485         };
486 };
487
488 In some cases, there is a need to use more than one sensor to extrapolate
489 a thermal hotspot in the silicon. The above example illustrates this situation.
490 For instance, it may be the case that a sensor external to CPU IP may be placed
491 close to CPU hotspot and together with internal CPU sensor, it is used
492 to determine the hotspot. Assuming this is the case for the above example,
493 the hypothetical extrapolation rule would be:
494                 hotspot = 100 * bandgap - 120 * adc + 484
495
496 In other context, the same idea can be used to add fixed offset. For instance,
497 consider the hotspot extrapolation rule below:
498                 hotspot = 1 * adc + 6000
499
500 In the above equation, the hotspot is always 6C higher than what is read
501 from the ADC sensor. The binding would be then:
502         thermal-sensors =  <&adc>;
503
504                 /* hotspot = 1 * adc + 6000 */
505         coefficients =          <1      6000>;
506
507 (d) - Board thermal
508
509 The board thermal example below illustrates how to setup one thermal zone
510 with many sensors and many cooling devices.
511
512 #include <dt-bindings/thermal/thermal.h>
513
514 &i2c1 {
515         ...
516         /*
517          * An IC with several temperature sensor.
518          */
519         adc_dummy: sensor@0x50 {
520                 ...
521                 #thermal-sensor-cells = <1>; /* sensor internal ID */
522         };
523 };
524
525 thermal-zones {
526         batt-thermal {
527                 polling-delay-passive = <500>; /* milliseconds */
528                 polling-delay = <2500>; /* milliseconds */
529
530                                 /* sensor       ID */
531                 thermal-sensors = <&adc_dummy     4>;
532
533                 trips {
534                         ...
535                 };
536
537                 cooling-maps {
538                         ...
539                 };
540         };
541
542         board_thermal: board-thermal {
543                 polling-delay-passive = <1000>; /* milliseconds */
544                 polling-delay = <2500>; /* milliseconds */
545
546                                 /* sensor       ID */
547                 thermal-sensors = <&adc_dummy     0>, /* pcb top edge */
548                                   <&adc_dummy     1>, /* lcd */
549                                   <&adc_dummy     2>; /* back cover */
550                 /*
551                  * An array of coefficients describing the sensor
552                  * linear relation. E.g.:
553                  * z = c1*x1 + c2*x2 + c3*x3
554                  */
555                 coefficients =          <1200   -345    890>;
556
557                 sustainable-power = <2500>;
558
559                 trips {
560                         /* Trips are based on resulting linear equation */
561                         cpu_trip: cpu-trip {
562                                 temperature = <60000>; /* millicelsius */
563                                 hysteresis = <2000>; /* millicelsius */
564                                 type = "passive";
565                         };
566                         gpu_trip: gpu-trip {
567                                 temperature = <55000>; /* millicelsius */
568                                 hysteresis = <2000>; /* millicelsius */
569                                 type = "passive";
570                         }
571                         lcd_trip: lcp-trip {
572                                 temperature = <53000>; /* millicelsius */
573                                 hysteresis = <2000>; /* millicelsius */
574                                 type = "passive";
575                         };
576                         crit_trip: crit-trip {
577                                 temperature = <68000>; /* millicelsius */
578                                 hysteresis = <2000>; /* millicelsius */
579                                 type = "critical";
580                         };
581                 };
582
583                 cooling-maps {
584                         map0 {
585                                 trip = <&cpu_trip>;
586                                 cooling-device = <&cpu0 0 2>;
587                                 contribution = <55>;
588                         };
589                         map1 {
590                                 trip = <&gpu_trip>;
591                                 cooling-device = <&gpu0 0 2>;
592                                 contribution = <20>;
593                         };
594                         map2 {
595                                 trip = <&lcd_trip>;
596                                 cooling-device = <&lcd0 5 10>;
597                                 contribution = <15>;
598                         };
599                 };
600         };
601 };
602
603 The above example is a mix of previous examples, a sensor IP with several internal
604 sensors used to monitor different zones, one of them is composed by several sensors and
605 with different cooling devices.