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