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 be the cooling-min-state and cooling-max-state
  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-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
  82 The trip node is a node to describe a point in the temperature domain
  83 in which the system takes an action. This node describes just the point,
  84 not the action.
  85
  86 Required 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
 104 The cooling device maps node is a node to describe how cooling devices
 105 get assigned to trip points of the zone. The cooling devices are expected
 106 to be loaded in the target system.
 107
 108 Required 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
 118 Optional 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
 124 Note: Using the THERMAL_NO_LIMIT (-1UL) constant in the cooling-device phandle
 125 limit 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.
 128 Refer to include/dt-bindings/thermal/thermal.h for definition of this constant.
 129
 130 * Thermal zone nodes
 131
 132 The thermal zone node is the node containing all the required info
 133 for describing a thermal zone, including its cooling device bindings. The
 134 thermal zone node must contain, apart from its own properties, one sub-node
 135 containing trip nodes and one sub-node containing all the zone cooling maps.
 136
 137 Required 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
 158 Optional 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
 170 - sustainable-power:    An estimate of the sustainable power (in mW) that the
 171   Type: unsigned        thermal zone can dissipate at the desired
 172   Size: one cell        control temperature.  For reference, the
 173                         sustainable power of a 4'' phone is typically
 174                         2000mW, while on a 10'' tablet is around
 175                         4500mW.
 176
 177 Note: The delay properties are bound to the maximum dT/dt (temperature
 178 derivative over time) in two situations for a thermal zone:
 179 (i)  - when passive cooling is activated (polling-delay-passive); and
 180 (ii) - when the zone just needs to be monitored (polling-delay) or
 181 when active cooling is activated.
 182
 183 The maximum dT/dt is highly bound to hardware power consumption and dissipation
 184 capability. The delays should be chosen to account for said max dT/dt,
 185 such that a device does not cross several trip boundaries unexpectedly
 186 between polls. Choosing the right polling delays shall avoid having the
 187 device in temperature ranges that may damage the silicon structures and
 188 reduce silicon lifetime.
 189
 190 * The thermal-zones node
 191
 192 The "thermal-zones" node is a container for all thermal zone nodes. It shall
 193 contain only sub-nodes describing thermal zones as in the section
 194 "Thermal zone nodes". The "thermal-zones" node appears under "/".
 195
 196 * Examples
 197
 198 Below are several examples on how to use thermal data descriptors
 199 using device tree bindings:
 200
 201 (a) - CPU thermal zone
 202
 203 The CPU thermal zone example below describes how to setup one thermal zone
 204 using one single sensor as temperature source and many cooling devices and
 205 power dissipation control sources.
 206
 207 #include <dt-bindings/thermal/thermal.h>
 208
 209 cpus {
 210         /*
 211          * Here is an example of describing a cooling device for a DVFS
 212          * capable CPU. The CPU node describes its four OPPs.
 213          * The cooling states possible are 0..3, and they are
 214          * used as OPP indexes. The minimum cooling state is 0, which means
 215          * all four OPPs can be available to the system. The maximum
 216          * cooling state is 3, which means only the lowest OPPs (198MHz@0.85V)
 217          * can be available in the system.
 218          */
 219         cpu0: cpu@0 {
 220                 ...
 221                 operating-points = <
 222                         /* kHz    uV */
 223                         970000  1200000
 224                         792000  1100000
 225                         396000  950000
 226                         198000  850000
 227                 >;
 228                 cooling-min-state = <0>;
 229                 cooling-max-state = <3>;
 230                 #cooling-cells = <2>; /* min followed by max */
 231         };
 232         ...
 233 };
 234
 235 &i2c1 {
 236         ...
 237         /*
 238          * A simple fan controller which supports 10 speeds of operation
 239          * (represented as 0-9).
 240          */
 241         fan0: fan@0x48 {
 242                 ...
 243                 cooling-min-state = <0>;
 244                 cooling-max-state = <9>;
 245                 #cooling-cells = <2>; /* min followed by max */
 246         };
 247 };
 248
 249 ocp {
 250         ...
 251         /*
 252          * A simple IC with a single bandgap temperature sensor.
 253          */
 254         bandgap0: bandgap@0x0000ED00 {
 255                 ...
 256                 #thermal-sensor-cells = <0>;
 257         };
 258 };
 259
 260 thermal-zones {
 261         cpu_thermal: cpu-thermal {
 262                 polling-delay-passive = <250>; /* milliseconds */
 263                 polling-delay = <1000>; /* milliseconds */
 264
 265                 thermal-sensors = <&bandgap0>;
 266
 267                 trips {
 268                         cpu_alert0: cpu-alert0 {
 269                                 temperature = <90000>; /* millicelsius */
 270                                 hysteresis = <2000>; /* millicelsius */
 271                                 type = "active";
 272                         };
 273                         cpu_alert1: cpu-alert1 {
 274                                 temperature = <100000>; /* millicelsius */
 275                                 hysteresis = <2000>; /* millicelsius */
 276                                 type = "passive";
 277                         };
 278                         cpu_crit: cpu-crit {
 279                                 temperature = <125000>; /* millicelsius */
 280                                 hysteresis = <2000>; /* millicelsius */
 281                                 type = "critical";
 282                         };
 283                 };
 284
 285                 cooling-maps {
 286                         map0 {
 287                                 trip = <&cpu_alert0>;
 288                                 cooling-device = <&fan0 THERMAL_NO_LIMIT 4>;
 289                         };
 290                         map1 {
 291                                 trip = <&cpu_alert1>;
 292                                 cooling-device = <&fan0 5 THERMAL_NO_LIMIT>;
 293                         };
 294                         map2 {
 295                                 trip = <&cpu_alert1>;
 296                                 cooling-device =
 297                                     <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>;
 298                         };
 299                 };
 300         };
 301 };
 302
 303 In the example above, the ADC sensor (bandgap0) at address 0x0000ED00 is
 304 used to monitor the zone 'cpu-thermal' using its sole sensor. A fan
 305 device (fan0) is controlled via I2C bus 1, at address 0x48, and has ten
 306 different cooling states 0-9. It is used to remove the heat out of
 307 the thermal zone 'cpu-thermal' using its cooling states
 308 from its minimum to 4, when it reaches trip point 'cpu_alert0'
 309 at 90C, as an example of active cooling. The same cooling device is used at
 310 'cpu_alert1', but from 5 to its maximum state. The cpu@0 device is also
 311 linked to the same thermal zone, 'cpu-thermal', as a passive cooling device,
 312 using all its cooling states at trip point 'cpu_alert1',
 313 which is a trip point at 100C. On the thermal zone 'cpu-thermal', at the
 314 temperature of 125C, represented by the trip point 'cpu_crit', the silicon
 315 is not reliable anymore.
 316
 317 (b) - IC with several internal sensors
 318
 319 The example below describes how to deploy several thermal zones based off a
 320 single sensor IC, assuming it has several internal sensors. This is a common
 321 case on SoC designs with several internal IPs that may need different thermal
 322 requirements, and thus may have their own sensor to monitor or detect internal
 323 hotspots in their silicon.
 324
 325 #include <dt-bindings/thermal/thermal.h>
 326
 327 ocp {
 328         ...
 329         /*
 330          * A simple IC with several bandgap temperature sensors.
 331          */
 332         bandgap0: bandgap@0x0000ED00 {
 333                 ...
 334                 #thermal-sensor-cells = <1>;
 335         };
 336 };
 337
 338 thermal-zones {
 339         cpu_thermal: cpu-thermal {
 340                 polling-delay-passive = <250>; /* milliseconds */
 341                 polling-delay = <1000>; /* milliseconds */
 342
 343                                 /* sensor       ID */
 344                 thermal-sensors = <&bandgap0     0>;
 345
 346                 trips {
 347                         /* each zone within the SoC may have its own trips */
 348                         cpu_alert: cpu-alert {
 349                                 temperature = <100000>; /* millicelsius */
 350                                 hysteresis = <2000>; /* millicelsius */
 351                                 type = "passive";
 352                         };
 353                         cpu_crit: cpu-crit {
 354                                 temperature = <125000>; /* millicelsius */
 355                                 hysteresis = <2000>; /* millicelsius */
 356                                 type = "critical";
 357                         };
 358                 };
 359
 360                 cooling-maps {
 361                         /* each zone within the SoC may have its own cooling */
 362                         ...
 363                 };
 364         };
 365
 366         gpu_thermal: gpu-thermal {
 367                 polling-delay-passive = <120>; /* milliseconds */
 368                 polling-delay = <1000>; /* milliseconds */
 369
 370                                 /* sensor       ID */
 371                 thermal-sensors = <&bandgap0     1>;
 372
 373                 trips {
 374                         /* each zone within the SoC may have its own trips */
 375                         gpu_alert: gpu-alert {
 376                                 temperature = <90000>; /* millicelsius */
 377                                 hysteresis = <2000>; /* millicelsius */
 378                                 type = "passive";
 379                         };
 380                         gpu_crit: gpu-crit {
 381                                 temperature = <105000>; /* millicelsius */
 382                                 hysteresis = <2000>; /* millicelsius */
 383                                 type = "critical";
 384                         };
 385                 };
 386
 387                 cooling-maps {
 388                         /* each zone within the SoC may have its own cooling */
 389                         ...
 390                 };
 391         };
 392
 393         dsp_thermal: dsp-thermal {
 394                 polling-delay-passive = <50>; /* milliseconds */
 395                 polling-delay = <1000>; /* milliseconds */
 396
 397                                 /* sensor       ID */
 398                 thermal-sensors = <&bandgap0     2>;
 399
 400                 trips {
 401                         /* each zone within the SoC may have its own trips */
 402                         dsp_alert: dsp-alert {
 403                                 temperature = <90000>; /* millicelsius */
 404                                 hysteresis = <2000>; /* millicelsius */
 405                                 type = "passive";
 406                         };
 407                         dsp_crit: gpu-crit {
 408                                 temperature = <135000>; /* millicelsius */
 409                                 hysteresis = <2000>; /* millicelsius */
 410                                 type = "critical";
 411                         };
 412                 };
 413
 414                 cooling-maps {
 415                         /* each zone within the SoC may have its own cooling */
 416                         ...
 417                 };
 418         };
 419 };
 420
 421 In the example above, there is one bandgap IC which has the capability to
 422 monitor three sensors. The hardware has been designed so that sensors are
 423 placed on different places in the DIE to monitor different temperature
 424 hotspots: one for CPU thermal zone, one for GPU thermal zone and the
 425 other to monitor a DSP thermal zone.
 426
 427 Thus, there is a need to assign each sensor provided by the bandgap IC
 428 to different thermal zones. This is achieved by means of using the
 429 #thermal-sensor-cells property and using the first cell of the sensor
 430 specifier as sensor ID. In the example, then, <bandgap 0> is used to
 431 monitor CPU thermal zone, <bandgap 1> is used to monitor GPU thermal
 432 zone and <bandgap 2> is used to monitor DSP thermal zone. Each zone
 433 may be uncorrelated, having its own dT/dt requirements, trips
 434 and cooling maps.
 435
 436
 437 (c) - Several sensors within one single thermal zone
 438
 439 The example below illustrates how to use more than one sensor within
 440 one thermal zone.
 441
 442 #include <dt-bindings/thermal/thermal.h>
 443
 444 &i2c1 {
 445         ...
 446         /*
 447          * A simple IC with a single temperature sensor.
 448          */
 449         adc: sensor@0x49 {
 450                 ...
 451                 #thermal-sensor-cells = <0>;
 452         };
 453 };
 454
 455 ocp {
 456         ...
 457         /*
 458          * A simple IC with a single bandgap temperature sensor.
 459          */
 460         bandgap0: bandgap@0x0000ED00 {
 461                 ...
 462                 #thermal-sensor-cells = <0>;
 463         };
 464 };
 465
 466 thermal-zones {
 467         cpu_thermal: cpu-thermal {
 468                 polling-delay-passive = <250>; /* milliseconds */
 469                 polling-delay = <1000>; /* milliseconds */
 470
 471                 thermal-sensors = <&bandgap0>,  /* cpu */
 472                                   <&adc>;       /* pcb north */
 473
 474                 /* hotspot = 100 * bandgap - 120 * adc + 484 */
 475                 coefficients =          <100    -120    484>;
 476
 477                 trips {
 478                         ...
 479                 };
 480
 481                 cooling-maps {
 482                         ...
 483                 };
 484         };
 485 };
 486
 487 In some cases, there is a need to use more than one sensor to extrapolate
 488 a thermal hotspot in the silicon. The above example illustrates this situation.
 489 For instance, it may be the case that a sensor external to CPU IP may be placed
 490 close to CPU hotspot and together with internal CPU sensor, it is used
 491 to determine the hotspot. Assuming this is the case for the above example,
 492 the hypothetical extrapolation rule would be:
 493                 hotspot = 100 * bandgap - 120 * adc + 484
 494
 495 In other context, the same idea can be used to add fixed offset. For instance,
 496 consider the hotspot extrapolation rule below:
 497                 hotspot = 1 * adc + 6000
 498
 499 In the above equation, the hotspot is always 6C higher than what is read
 500 from the ADC sensor. The binding would be then:
 501         thermal-sensors =  <&adc>;
 502
 503                 /* hotspot = 1 * adc + 6000 */
 504         coefficients =          <1      6000>;
 505
 506 (d) - Board thermal
 507
 508 The board thermal example below illustrates how to setup one thermal zone
 509 with many sensors and many cooling devices.
 510
 511 #include <dt-bindings/thermal/thermal.h>
 512
 513 &i2c1 {
 514         ...
 515         /*
 516          * An IC with several temperature sensor.
 517          */
 518         adc_dummy: sensor@0x50 {
 519                 ...
 520                 #thermal-sensor-cells = <1>; /* sensor internal ID */
 521         };
 522 };
 523
 524 thermal-zones {
 525         batt-thermal {
 526                 polling-delay-passive = <500>; /* milliseconds */
 527                 polling-delay = <2500>; /* milliseconds */
 528
 529                                 /* sensor       ID */
 530                 thermal-sensors = <&adc_dummy     4>;
 531
 532                 trips {
 533                         ...
 534                 };
 535
 536                 cooling-maps {
 537                         ...
 538                 };
 539         };
 540
 541         board_thermal: board-thermal {
 542                 polling-delay-passive = <1000>; /* milliseconds */
 543                 polling-delay = <2500>; /* milliseconds */
 544
 545                                 /* sensor       ID */
 546                 thermal-sensors = <&adc_dummy     0>, /* pcb top edge */
 547                                   <&adc_dummy     1>, /* lcd */
 548                                   <&adc_dummy     2>; /* back cover */
 549                 /*
 550                  * An array of coefficients describing the sensor
 551                  * linear relation. E.g.:
 552                  * z = c1*x1 + c2*x2 + c3*x3
 553                  */
 554                 coefficients =          <1200   -345    890>;
 555
 556                 sustainable-power = <2500>;
 557
 558                 trips {
 559                         /* Trips are based on resulting linear equation */
 560                         cpu_trip: cpu-trip {
 561                                 temperature = <60000>; /* millicelsius */
 562                                 hysteresis = <2000>; /* millicelsius */
 563                                 type = "passive";
 564                         };
 565                         gpu_trip: gpu-trip {
 566                                 temperature = <55000>; /* millicelsius */
 567                                 hysteresis = <2000>; /* millicelsius */
 568                                 type = "passive";
 569                         }
 570                         lcd_trip: lcp-trip {
 571                                 temperature = <53000>; /* millicelsius */
 572                                 hysteresis = <2000>; /* millicelsius */
 573                                 type = "passive";
 574                         };
 575                         crit_trip: crit-trip {
 576                                 temperature = <68000>; /* millicelsius */
 577                                 hysteresis = <2000>; /* millicelsius */
 578                                 type = "critical";
 579                         };
 580                 };
 581
 582                 cooling-maps {
 583                         map0 {
 584                                 trip = <&cpu_trip>;
 585                                 cooling-device = <&cpu0 0 2>;
 586                                 contribution = <55>;
 587                         };
 588                         map1 {
 589                                 trip = <&gpu_trip>;
 590                                 cooling-device = <&gpu0 0 2>;
 591                                 contribution = <20>;
 592                         };
 593                         map2 {
 594                                 trip = <&lcd_trip>;
 595                                 cooling-device = <&lcd0 5 10>;
 596                                 contribution = <15>;
 597                         };
 598                 };
 599         };
 600 };
 601
 602 The above example is a mix of previous examples, a sensor IP with several internal
 603 sensors used to monitor different zones, one of them is composed by several sensors and
 604 with different cooling devices.