1 * Thermal Framework Device Tree descriptor
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
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.
14 There are five types of nodes involved to describe thermal bindings:
15 - thermal sensors: devices which may be used to take temperature
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;
23 The following is a description of each of these node types.
25 * Thermal sensor devices
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.
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.
41 * Cooling device nodes
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.
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.
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.
73 - cooling-min-level: An integer indicating the smallest
74 Type: unsigned cooling state accepted. Typically 0.
77 - cooling-max-level: An integer indicating the largest
78 Type: unsigned cooling state accepted.
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,
88 - temperature: An integer indicating the trip temperature level,
89 Type: signed in millicelsius.
92 - hysteresis: A low hysteresis value on temperature property (above).
93 Type: unsigned This is a relative value, in millicelsius.
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.
103 * Cooling device maps
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.
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.
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.
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.
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.
139 - polling-delay: The maximum number of milliseconds to wait between polls
140 Type: unsigned when checking this thermal zone.
143 - polling-delay-passive: The maximum number of milliseconds to wait
144 Type: unsigned between polls when performing passive cooling.
147 - thermal-sensors: A list of thermal sensor phandles and sensor specifier
148 Type: list of used while monitoring the thermal zone.
152 - trips: A sub-node which is a container of only trip point nodes
153 Type: sub-node required to describe the thermal zone.
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
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.
167 The coefficients are ordered and they match with sensors
168 by means of sensor ID. Additional coefficients are
169 interpreted as constant offset.
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
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.
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.
191 * The thermal-zones node
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 "/".
199 Below are several examples on how to use thermal data descriptors
200 using device tree bindings:
202 (a) - CPU thermal zone
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.
208 #include <dt-bindings/thermal/thermal.h>
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.
229 cooling-min-level = <0>;
230 cooling-max-level = <3>;
231 #cooling-cells = <2>; /* min followed by max */
239 * A simple fan controller which supports 10 speeds of operation
240 * (represented as 0-9).
244 cooling-min-level = <0>;
245 cooling-max-level = <9>;
246 #cooling-cells = <2>; /* min followed by max */
253 * A simple IC with a single bandgap temperature sensor.
255 bandgap0: bandgap@0x0000ED00 {
257 #thermal-sensor-cells = <0>;
262 cpu_thermal: cpu-thermal {
263 polling-delay-passive = <250>; /* milliseconds */
264 polling-delay = <1000>; /* milliseconds */
266 thermal-sensors = <&bandgap0>;
269 cpu_alert0: cpu-alert0 {
270 temperature = <90000>; /* millicelsius */
271 hysteresis = <2000>; /* millicelsius */
274 cpu_alert1: cpu-alert1 {
275 temperature = <100000>; /* millicelsius */
276 hysteresis = <2000>; /* millicelsius */
280 temperature = <125000>; /* millicelsius */
281 hysteresis = <2000>; /* millicelsius */
288 trip = <&cpu_alert0>;
289 cooling-device = <&fan0 THERMAL_NO_LIMIT 4>;
292 trip = <&cpu_alert1>;
293 cooling-device = <&fan0 5 THERMAL_NO_LIMIT>;
296 trip = <&cpu_alert1>;
298 <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>;
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.
318 (b) - IC with several internal sensors
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.
326 #include <dt-bindings/thermal/thermal.h>
331 * A simple IC with several bandgap temperature sensors.
333 bandgap0: bandgap@0x0000ED00 {
335 #thermal-sensor-cells = <1>;
340 cpu_thermal: cpu-thermal {
341 polling-delay-passive = <250>; /* milliseconds */
342 polling-delay = <1000>; /* milliseconds */
345 thermal-sensors = <&bandgap0 0>;
348 /* each zone within the SoC may have its own trips */
349 cpu_alert: cpu-alert {
350 temperature = <100000>; /* millicelsius */
351 hysteresis = <2000>; /* millicelsius */
355 temperature = <125000>; /* millicelsius */
356 hysteresis = <2000>; /* millicelsius */
362 /* each zone within the SoC may have its own cooling */
367 gpu_thermal: gpu-thermal {
368 polling-delay-passive = <120>; /* milliseconds */
369 polling-delay = <1000>; /* milliseconds */
372 thermal-sensors = <&bandgap0 1>;
375 /* each zone within the SoC may have its own trips */
376 gpu_alert: gpu-alert {
377 temperature = <90000>; /* millicelsius */
378 hysteresis = <2000>; /* millicelsius */
382 temperature = <105000>; /* millicelsius */
383 hysteresis = <2000>; /* millicelsius */
389 /* each zone within the SoC may have its own cooling */
394 dsp_thermal: dsp-thermal {
395 polling-delay-passive = <50>; /* milliseconds */
396 polling-delay = <1000>; /* milliseconds */
399 thermal-sensors = <&bandgap0 2>;
402 /* each zone within the SoC may have its own trips */
403 dsp_alert: dsp-alert {
404 temperature = <90000>; /* millicelsius */
405 hysteresis = <2000>; /* millicelsius */
409 temperature = <135000>; /* millicelsius */
410 hysteresis = <2000>; /* millicelsius */
416 /* each zone within the SoC may have its own cooling */
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.
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
438 (c) - Several sensors within one single thermal zone
440 The example below illustrates how to use more than one sensor within
443 #include <dt-bindings/thermal/thermal.h>
448 * A simple IC with a single temperature sensor.
452 #thermal-sensor-cells = <0>;
459 * A simple IC with a single bandgap temperature sensor.
461 bandgap0: bandgap@0x0000ED00 {
463 #thermal-sensor-cells = <0>;
468 cpu_thermal: cpu-thermal {
469 polling-delay-passive = <250>; /* milliseconds */
470 polling-delay = <1000>; /* milliseconds */
472 thermal-sensors = <&bandgap0>, /* cpu */
473 <&adc>; /* pcb north */
475 /* hotspot = 100 * bandgap - 120 * adc + 484 */
476 coefficients = <100 -120 484>;
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
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
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>;
504 /* hotspot = 1 * adc + 6000 */
505 coefficients = <1 6000>;
509 The board thermal example below illustrates how to setup one thermal zone
510 with many sensors and many cooling devices.
512 #include <dt-bindings/thermal/thermal.h>
517 * An IC with several temperature sensor.
519 adc_dummy: sensor@0x50 {
521 #thermal-sensor-cells = <1>; /* sensor internal ID */
527 polling-delay-passive = <500>; /* milliseconds */
528 polling-delay = <2500>; /* milliseconds */
531 thermal-sensors = <&adc_dummy 4>;
542 board_thermal: board-thermal {
543 polling-delay-passive = <1000>; /* milliseconds */
544 polling-delay = <2500>; /* milliseconds */
547 thermal-sensors = <&adc_dummy 0>, /* pcb top edge */
548 <&adc_dummy 1>, /* lcd */
549 <&adc_dummy 2>; /* back cover */
551 * An array of coefficients describing the sensor
552 * linear relation. E.g.:
553 * z = c1*x1 + c2*x2 + c3*x3
555 coefficients = <1200 -345 890>;
557 sustainable-power = <2500>;
560 /* Trips are based on resulting linear equation */
562 temperature = <60000>; /* millicelsius */
563 hysteresis = <2000>; /* millicelsius */
567 temperature = <55000>; /* millicelsius */
568 hysteresis = <2000>; /* millicelsius */
572 temperature = <53000>; /* millicelsius */
573 hysteresis = <2000>; /* millicelsius */
576 crit_trip: crit-trip {
577 temperature = <68000>; /* millicelsius */
578 hysteresis = <2000>; /* millicelsius */
586 cooling-device = <&cpu0 0 2>;
591 cooling-device = <&gpu0 0 2>;
596 cooling-device = <&lcd0 5 10>;
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.