thermal.txt 18.3 KB
Newer Older
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
* Thermal Framework Device Tree descriptor

This file describes a generic binding to provide a way of
defining hardware thermal structure using device tree.
A thermal structure includes thermal zones and their components,
such as trip points, polling intervals, sensors and cooling devices
binding descriptors.

The target of device tree thermal descriptors is to describe only
the hardware thermal aspects. The thermal device tree bindings are
not about how the system must control or which algorithm or policy
must be taken in place.

There are five types of nodes involved to describe thermal bindings:
- thermal sensors: devices which may be used to take temperature
  measurements.
- cooling devices: devices which may be used to dissipate heat.
- trip points: describe key temperatures at which cooling is recommended. The
  set of points should be chosen based on hardware limits.
- cooling maps: used to describe links between trip points and cooling devices;
- thermal zones: used to describe thermal data within the hardware;

The following is a description of each of these node types.

* Thermal sensor devices

Thermal sensor devices are nodes providing temperature sensing capabilities on
thermal zones. Typical devices are I2C ADC converters and bandgaps. These are
nodes providing temperature data to thermal zones. Thermal sensor devices may
control one or more internal sensors.

Required property:
- #thermal-sensor-cells: Used to provide sensor device specific information
  Type: unsigned	 while referring to it. Typically 0 on thermal sensor
  Size: one cell	 nodes with only one sensor, and at least 1 on nodes
			 with several internal sensors, in order
			 to identify uniquely the sensor instances within
			 the IC. See thermal zone binding for more details
			 on how consumers refer to sensor devices.

* Cooling device nodes

Cooling devices are nodes providing control on power dissipation. There
are essentially two ways to provide control on power dissipation. First
is by means of regulating device performance, which is known as passive
cooling. A typical passive cooling is a CPU that has dynamic voltage and
frequency scaling (DVFS), and uses lower frequencies as cooling states.
Second is by means of activating devices in order to remove
the dissipated heat, which is known as active cooling, e.g. regulating
fan speeds. In both cases, cooling devices shall have a way to determine
the state of cooling in which the device is.

Any cooling device has a range of cooling states (i.e. different levels
of heat dissipation). For example a fan's cooling states correspond to
the different fan speeds possible. Cooling states are referred to by
single unsigned integers, where larger numbers mean greater heat
dissipation. The precise set of cooling states associated with a device
58
should be defined in a particular device's binding.
59 60 61 62 63
For more examples of cooling devices, refer to the example sections below.

Required properties:
- #cooling-cells:	Used to provide cooling device specific information
  Type: unsigned	while referring to it. Must be at least 2, in order
Caesar Wang's avatar
Caesar Wang committed
64
  Size: one cell	to specify minimum and maximum cooling state used
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
			in the reference. The first cell is the minimum
			cooling state requested and the second cell is
			the maximum cooling state requested in the reference.
			See Cooling device maps section below for more details
			on how consumers refer to cooling devices.

* Trip points

The trip node is a node to describe a point in the temperature domain
in which the system takes an action. This node describes just the point,
not the action.

Required properties:
- temperature:		An integer indicating the trip temperature level,
  Type: signed		in millicelsius.
  Size: one cell

- hysteresis:		A low hysteresis value on temperature property (above).
  Type: unsigned	This is a relative value, in millicelsius.
  Size: one cell

- type:			a string containing the trip type. Expected values are:
	"active":	A trip point to enable active cooling
	"passive":	A trip point to enable passive cooling
	"hot":		A trip point to notify emergency
	"critical":	Hardware not reliable.
  Type: string

* Cooling device maps

The cooling device maps node is a node to describe how cooling devices
get assigned to trip points of the zone. The cooling devices are expected
to be loaded in the target system.

Required properties:
- cooling-device:	A phandle of a cooling device with its specifier,
  Type: phandle +	referring to which cooling device is used in this
    cooling specifier	binding. In the cooling specifier, the first cell
			is the minimum cooling state and the second cell
			is the maximum cooling state used in this map.
- trip:			A phandle of a trip point node within the same thermal
  Type: phandle of	zone.
   trip point node

Optional property:
- contribution:		The cooling contribution to the thermal zone of the
  Type: unsigned	referred cooling device at the referred trip point.
Caesar Wang's avatar
Caesar Wang committed
112
  Size: one cell	The contribution is a ratio of the sum
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
			of all cooling contributions within a thermal zone.

Note: Using the THERMAL_NO_LIMIT (-1UL) constant in the cooling-device phandle
limit specifier means:
(i)   - minimum state allowed for minimum cooling state used in the reference.
(ii)  - maximum state allowed for maximum cooling state used in the reference.
Refer to include/dt-bindings/thermal/thermal.h for definition of this constant.

* Thermal zone nodes

The thermal zone node is the node containing all the required info
for describing a thermal zone, including its cooling device bindings. The
thermal zone node must contain, apart from its own properties, one sub-node
containing trip nodes and one sub-node containing all the zone cooling maps.

Required properties:
- polling-delay:	The maximum number of milliseconds to wait between polls
  Type: unsigned	when checking this thermal zone.
  Size: one cell

- polling-delay-passive: The maximum number of milliseconds to wait
  Type: unsigned	between polls when performing passive cooling.
  Size: one cell

- thermal-sensors:	A list of thermal sensor phandles and sensor specifier
Caesar Wang's avatar
Caesar Wang committed
138
  Type: list of		used while monitoring the thermal zone.
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160
  phandles + sensor
  specifier

- trips:		A sub-node which is a container of only trip point nodes
  Type: sub-node	required to describe the thermal zone.

- cooling-maps:		A sub-node which is a container of only cooling device
  Type: sub-node	map nodes, used to describe the relation between trips
			and cooling devices.

Optional property:
- coefficients:		An array of integers (one signed cell) containing
  Type: array		coefficients to compose a linear relation between
  Elem size: one cell	the sensors listed in the thermal-sensors property.
  Elem type: signed	Coefficients defaults to 1, in case this property
			is not specified. A simple linear polynomial is used:
			Z = c0 * x0 + c1 + x1 + ... + c(n-1) * x(n-1) + cn.

			The coefficients are ordered and they match with sensors
			by means of sensor ID. Additional coefficients are
			interpreted as constant offset.

161 162 163 164 165 166 167
- sustainable-power:	An estimate of the sustainable power (in mW) that the
  Type: unsigned	thermal zone can dissipate at the desired
  Size: one cell	control temperature.  For reference, the
			sustainable power of a 4'' phone is typically
			2000mW, while on a 10'' tablet is around
			4500mW.

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
Note: The delay properties are bound to the maximum dT/dt (temperature
derivative over time) in two situations for a thermal zone:
(i)  - when passive cooling is activated (polling-delay-passive); and
(ii) - 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.

* The thermal-zones node

The "thermal-zones" node is a container for all thermal zone nodes. It shall
contain only sub-nodes describing thermal zones as in the section
"Thermal zone nodes". The "thermal-zones" node appears under "/".

* Examples

Below are several examples on how to use thermal data descriptors
using device tree bindings:

(a) - CPU thermal zone

The CPU thermal zone example below describes how to setup one thermal zone
using one single sensor as temperature source and many cooling devices and
power dissipation control sources.

#include <dt-bindings/thermal/thermal.h>

cpus {
	/*
	 * Here is an example of describing a cooling device for a DVFS
	 * capable CPU. The CPU node describes its four OPPs.
	 * The cooling states possible are 0..3, and they are
	 * used as OPP indexes. The minimum cooling state is 0, which means
	 * all four OPPs can be available to the system. The maximum
	 * cooling state is 3, which means only the lowest OPPs (198MHz@0.85V)
	 * can be available in the system.
	 */
	cpu0: cpu@0 {
		...
		operating-points = <
			/* kHz    uV */
			970000  1200000
			792000  1100000
			396000  950000
			198000  850000
		>;
		#cooling-cells = <2>; /* min followed by max */
	};
	...
};

&i2c1 {
	...
	/*
	 * A simple fan controller which supports 10 speeds of operation
	 * (represented as 0-9).
	 */
230
	fan0: fan@48 {
231 232 233 234 235 236 237 238 239 240
		...
		#cooling-cells = <2>; /* min followed by max */
	};
};

ocp {
	...
	/*
	 * A simple IC with a single bandgap temperature sensor.
	 */
241
	bandgap0: bandgap@0000ed00 {
242 243 244 245 246 247
		...
		#thermal-sensor-cells = <0>;
	};
};

thermal-zones {
248
	cpu_thermal: cpu-thermal {
249 250 251 252 253 254
		polling-delay-passive = <250>; /* milliseconds */
		polling-delay = <1000>; /* milliseconds */

		thermal-sensors = <&bandgap0>;

		trips {
255
			cpu_alert0: cpu-alert0 {
256 257 258 259
				temperature = <90000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "active";
			};
260
			cpu_alert1: cpu-alert1 {
261 262 263 264
				temperature = <100000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "passive";
			};
265
			cpu_crit: cpu-crit {
266 267 268 269 270 271 272 273
				temperature = <125000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "critical";
			};
		};

		cooling-maps {
			map0 {
274 275
				trip = <&cpu_alert0>;
				cooling-device = <&fan0 THERMAL_NO_LIMIT 4>;
276 277
			};
			map1 {
278 279
				trip = <&cpu_alert1>;
				cooling-device = <&fan0 5 THERMAL_NO_LIMIT>;
280 281
			};
			map2 {
282
				trip = <&cpu_alert1>;
283
				cooling-device =
284
				    <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>;
285 286 287 288 289 290 291 292 293 294
			};
		};
	};
};

In the example above, the ADC sensor (bandgap0) at address 0x0000ED00 is
used to monitor the zone 'cpu-thermal' using its sole sensor. A fan
device (fan0) is controlled via I2C bus 1, at address 0x48, and has ten
different cooling states 0-9. It is used to remove the heat out of
the thermal zone 'cpu-thermal' using its cooling states
295
from its minimum to 4, when it reaches trip point 'cpu_alert0'
296
at 90C, as an example of active cooling. The same cooling device is used at
297
'cpu_alert1', but from 5 to its maximum state. The cpu@0 device is also
298
linked to the same thermal zone, 'cpu-thermal', as a passive cooling device,
299
using all its cooling states at trip point 'cpu_alert1',
300
which is a trip point at 100C. On the thermal zone 'cpu-thermal', at the
301
temperature of 125C, represented by the trip point 'cpu_crit', the silicon
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318
is not reliable anymore.

(b) - IC with several internal sensors

The example below describes how to deploy several thermal zones based off a
single sensor IC, assuming it has several internal sensors. This is a common
case on SoC designs with several internal IPs that may need different thermal
requirements, and thus may have their own sensor to monitor or detect internal
hotspots in their silicon.

#include <dt-bindings/thermal/thermal.h>

ocp {
	...
	/*
	 * A simple IC with several bandgap temperature sensors.
	 */
319
	bandgap0: bandgap@0000ed00 {
320 321 322 323 324 325
		...
		#thermal-sensor-cells = <1>;
	};
};

thermal-zones {
326
	cpu_thermal: cpu-thermal {
327 328 329 330 331 332 333 334
		polling-delay-passive = <250>; /* milliseconds */
		polling-delay = <1000>; /* milliseconds */

				/* sensor       ID */
		thermal-sensors = <&bandgap0     0>;

		trips {
			/* each zone within the SoC may have its own trips */
335
			cpu_alert: cpu-alert {
336 337 338 339
				temperature = <100000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "passive";
			};
340
			cpu_crit: cpu-crit {
341 342 343 344 345 346 347 348 349 350 351 352
				temperature = <125000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "critical";
			};
		};

		cooling-maps {
			/* each zone within the SoC may have its own cooling */
			...
		};
	};

353
	gpu_thermal: gpu-thermal {
354 355 356 357 358 359 360 361
		polling-delay-passive = <120>; /* milliseconds */
		polling-delay = <1000>; /* milliseconds */

				/* sensor       ID */
		thermal-sensors = <&bandgap0     1>;

		trips {
			/* each zone within the SoC may have its own trips */
362
			gpu_alert: gpu-alert {
363 364 365 366
				temperature = <90000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "passive";
			};
367
			gpu_crit: gpu-crit {
368 369 370 371 372 373 374 375 376 377 378 379
				temperature = <105000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "critical";
			};
		};

		cooling-maps {
			/* each zone within the SoC may have its own cooling */
			...
		};
	};

380
	dsp_thermal: dsp-thermal {
381 382 383 384 385 386 387 388
		polling-delay-passive = <50>; /* milliseconds */
		polling-delay = <1000>; /* milliseconds */

				/* sensor       ID */
		thermal-sensors = <&bandgap0     2>;

		trips {
			/* each zone within the SoC may have its own trips */
389
			dsp_alert: dsp-alert {
390 391 392 393
				temperature = <90000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "passive";
			};
394
			dsp_crit: gpu-crit {
395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435
				temperature = <135000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "critical";
			};
		};

		cooling-maps {
			/* each zone within the SoC may have its own cooling */
			...
		};
	};
};

In the example above, there is one bandgap IC which has the capability to
monitor three sensors. The hardware has been designed so that sensors are
placed on different places in the DIE to monitor different temperature
hotspots: one for CPU thermal zone, one for GPU thermal zone and the
other to monitor a DSP thermal zone.

Thus, there is a need to assign each sensor provided by the bandgap IC
to different thermal zones. This is achieved by means of using the
#thermal-sensor-cells property and using the first cell of the sensor
specifier as sensor ID. In the example, then, <bandgap 0> is used to
monitor CPU thermal zone, <bandgap 1> is used to monitor GPU thermal
zone and <bandgap 2> is used to monitor DSP thermal zone. Each zone
may be uncorrelated, having its own dT/dt requirements, trips
and cooling maps.


(c) - Several sensors within one single thermal zone

The example below illustrates how to use more than one sensor within
one thermal zone.

#include <dt-bindings/thermal/thermal.h>

&i2c1 {
	...
	/*
	 * A simple IC with a single temperature sensor.
	 */
436
	adc: sensor@49 {
437 438 439 440 441 442 443 444 445 446
		...
		#thermal-sensor-cells = <0>;
	};
};

ocp {
	...
	/*
	 * A simple IC with a single bandgap temperature sensor.
	 */
447
	bandgap0: bandgap@0000ed00 {
448 449 450 451 452 453
		...
		#thermal-sensor-cells = <0>;
	};
};

thermal-zones {
454
	cpu_thermal: cpu-thermal {
455 456 457 458 459 460 461
		polling-delay-passive = <250>; /* milliseconds */
		polling-delay = <1000>; /* milliseconds */

		thermal-sensors = <&bandgap0>,	/* cpu */
				  <&adc>;	/* pcb north */

		/* hotspot = 100 * bandgap - 120 * adc + 484 */
Caesar Wang's avatar
Caesar Wang committed
462
		coefficients =		<100	-120	484>;
463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490

		trips {
			...
		};

		cooling-maps {
			...
		};
	};
};

In some cases, there is a need to use more than one sensor to extrapolate
a thermal hotspot in the silicon. The above example illustrates this situation.
For instance, it may be the case that a sensor external to CPU IP may be placed
close to CPU hotspot and together with internal CPU sensor, it is used
to determine the hotspot. Assuming this is the case for the above example,
the hypothetical extrapolation rule would be:
		hotspot = 100 * bandgap - 120 * adc + 484

In other context, the same idea can be used to add fixed offset. For instance,
consider the hotspot extrapolation rule below:
		hotspot = 1 * adc + 6000

In the above equation, the hotspot is always 6C higher than what is read
from the ADC sensor. The binding would be then:
        thermal-sensors =  <&adc>;

		/* hotspot = 1 * adc + 6000 */
Caesar Wang's avatar
Caesar Wang committed
491
	coefficients =		<1	6000>;
492 493 494 495 496 497 498 499 500 501 502 503 504

(d) - Board thermal

The board thermal example below illustrates how to setup one thermal zone
with many sensors and many cooling devices.

#include <dt-bindings/thermal/thermal.h>

&i2c1 {
	...
	/*
	 * An IC with several temperature sensor.
	 */
505
	adc_dummy: sensor@50 {
506 507 508 509 510 511 512 513 514 515 516
		...
		#thermal-sensor-cells = <1>; /* sensor internal ID */
	};
};

thermal-zones {
	batt-thermal {
		polling-delay-passive = <500>; /* milliseconds */
		polling-delay = <2500>; /* milliseconds */

				/* sensor       ID */
517
		thermal-sensors = <&adc_dummy     4>;
518 519 520 521 522 523 524 525 526 527

		trips {
			...
		};

		cooling-maps {
			...
		};
	};

528
	board_thermal: board-thermal {
529 530 531 532
		polling-delay-passive = <1000>; /* milliseconds */
		polling-delay = <2500>; /* milliseconds */

				/* sensor       ID */
533 534 535
		thermal-sensors = <&adc_dummy     0>, /* pcb top edge */
				  <&adc_dummy     1>, /* lcd */
				  <&adc_dummy     2>; /* back cover */
536 537 538 539 540 541 542
		/*
		 * An array of coefficients describing the sensor
		 * linear relation. E.g.:
		 * z = c1*x1 + c2*x2 + c3*x3
		 */
		coefficients =		<1200	-345	890>;

543 544
		sustainable-power = <2500>;

545 546
		trips {
			/* Trips are based on resulting linear equation */
547
			cpu_trip: cpu-trip {
548 549 550 551
				temperature = <60000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "passive";
			};
552
			gpu_trip: gpu-trip {
553 554 555 556
				temperature = <55000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "passive";
			}
557
			lcd_trip: lcp-trip {
558 559 560 561
				temperature = <53000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "passive";
			};
562
			crit_trip: crit-trip {
563 564 565 566 567 568 569 570
				temperature = <68000>; /* millicelsius */
				hysteresis = <2000>; /* millicelsius */
				type = "critical";
			};
		};

		cooling-maps {
			map0 {
571
				trip = <&cpu_trip>;
572 573 574 575
				cooling-device = <&cpu0 0 2>;
				contribution = <55>;
			};
			map1 {
576
				trip = <&gpu_trip>;
577 578 579 580
				cooling-device = <&gpu0 0 2>;
				contribution = <20>;
			};
			map2 {
581
				trip = <&lcd_trip>;
582 583 584 585 586 587 588 589 590 591
				cooling-device = <&lcd0 5 10>;
				contribution = <15>;
			};
		};
	};
};

The above example is a mix of previous examples, a sensor IP with several internal
sensors used to monitor different zones, one of them is composed by several sensors and
with different cooling devices.