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