Documentation/devicetree/bindings/thermal/thermal-zones.yaml

   1 # SPDX-License-Identifier: (GPL-2.0)
   2 # Copyright 2020 Linaro Ltd.
   3 %YAML 1.2
   4 ---
   5 $id: http://devicetree.org/schemas/thermal/thermal-zones.yaml#
   6 $schema: http://devicetree.org/meta-schemas/base.yaml#
   7
   8 title: Thermal zone
   9
  10 maintainers:
  11   - Daniel Lezcano <daniel.lezcano@linaro.org>
  12
  13 description: |
  14   Thermal management is achieved in devicetree by describing the sensor hardware
  15   and the software abstraction of cooling devices and thermal zones required to
  16   take appropriate action to mitigate thermal overloads.
  17
  18   The following node types are used to completely describe a thermal management
  19   system in devicetree:
  20    - thermal-sensor: device that measures temperature, has SoC-specific bindings
  21    - cooling-device: device used to dissipate heat either passively or actively
  22    - thermal-zones: a container of the following node types used to describe all
  23      thermal data for the platform
  24
  25   This binding describes the thermal-zones.
  26
  27   The polling-delay properties of a thermal-zone are bound to the maximum dT/dt
  28   (temperature derivative over time) in two situations for a thermal zone:
  29     1. when passive cooling is activated (polling-delay-passive)
  30     2. when the zone just needs to be monitored (polling-delay) or when
  31        active cooling is activated.
  32
  33   The maximum dT/dt is highly bound to hardware power consumption and
  34   dissipation capability. The delays should be chosen to account for said
  35   max dT/dt, such that a device does not cross several trip boundaries
  36   unexpectedly between polls. Choosing the right polling delays shall avoid
  37   having the device in temperature ranges that may damage the silicon structures
  38   and reduce silicon lifetime.
  39
  40 properties:
  41   $nodename:
  42     const: thermal-zones
  43     description:
  44       A /thermal-zones node is required in order to use the thermal framework to
  45       manage input from the various thermal zones in the system in order to
  46       mitigate thermal overload conditions. It does not represent a real device
  47       in the system, but acts as a container to link a thermal sensor device,
  48       platform-data regarding temperature thresholds and the mitigation actions
  49       to take when the temperature crosses those thresholds.
  50
  51 patternProperties:
  52   # Node name is limited in size due to Linux kernel requirements - 19
  53   # characters in total (see THERMAL_NAME_LENGTH, including terminating NUL
  54   # byte):
  55   "^[a-zA-Z][a-zA-Z0-9\\-]{1,10}-thermal$":
  56     type: object
  57     description:
  58       Each thermal zone node contains information about how frequently it
  59       must be checked, the sensor responsible for reporting temperature for
  60       this zone, one sub-node containing the various trip points for this
  61       zone and one sub-node containing all the zone cooling-maps.
  62
  63     properties:
  64       polling-delay:
  65         $ref: /schemas/types.yaml#/definitions/uint32
  66         description:
  67           The maximum number of milliseconds to wait between polls when
  68           checking this thermal zone. Setting this to 0 disables the polling
  69           timers setup by the thermal framework and assumes that the thermal
  70           sensors in this zone support interrupts.
  71
  72       polling-delay-passive:
  73         $ref: /schemas/types.yaml#/definitions/uint32
  74         description:
  75           The maximum number of milliseconds to wait between polls when
  76           checking this thermal zone while doing passive cooling. Setting
  77           this to 0 disables the polling timers setup by the thermal
  78           framework and assumes that the thermal sensors in this zone
  79           support interrupts.
  80
  81       critical-action:
  82         $ref: /schemas/types.yaml#/definitions/string
  83         description: |
  84           The action the OS should perform after the critical temperature is reached.
  85           By default the system will shutdown as a safe action to prevent damage
  86           to the hardware, if the property is not set.
  87           The shutdown action should be always the default and preferred one.
  88           Choose 'reboot' with care, as the hardware may be in thermal stress,
  89           thus leading to infinite reboots that may cause damage to the hardware.
  90           Make sure the firmware/bootloader will act as the last resort and take
  91           over the thermal control.
  92
  93         enum:
  94           - shutdown
  95           - reboot
  96
  97       thermal-sensors:
  98         $ref: /schemas/types.yaml#/definitions/phandle-array
  99         maxItems: 1
 100         description:
 101           The thermal sensor phandle and sensor specifier used to monitor this
 102           thermal zone.
 103
 104       coefficients:
 105         $ref: /schemas/types.yaml#/definitions/uint32-array
 106         description:
 107           An array of integers containing the coefficients of a linear equation
 108           that binds all the sensors listed in this thermal zone.
 109
 110           The linear equation used is as follows,
 111             z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn
 112           where c0, c1, .., cn are the coefficients.
 113
 114           Coefficients default to 1 in case this property is not specified. The
 115           coefficients are ordered and are matched with sensors by means of the
 116           sensor ID. Additional coefficients are interpreted as constant offset.
 117
 118       sustainable-power:
 119         $ref: /schemas/types.yaml#/definitions/uint32
 120         description:
 121           An estimate of the sustainable power (in mW) that this thermal zone
 122           can dissipate at the desired control temperature. For reference, the
 123           sustainable power of a 4-inch phone is typically 2000mW, while on a
 124           10-inch tablet is around 4500mW.
 125
 126       trips:
 127         type: object
 128         description:
 129           This node describes a set of points in the temperature domain at
 130           which the thermal framework needs to take action. The actions to
 131           be taken are defined in another node called cooling-maps.
 132
 133         patternProperties:
 134           "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
 135             type: object
 136
 137             properties:
 138               temperature:
 139                 $ref: /schemas/types.yaml#/definitions/int32
 140                 minimum: -273000
 141                 maximum: 200000
 142                 description:
 143                   An integer expressing the trip temperature in millicelsius.
 144
 145               hysteresis:
 146                 $ref: /schemas/types.yaml#/definitions/uint32
 147                 description:
 148                   An unsigned integer expressing the hysteresis delta with
 149                   respect to the trip temperature property above, also in
 150                   millicelsius. Any cooling action initiated by the framework is
 151                   maintained until the temperature falls below
 152                   (trip temperature - hysteresis). This potentially prevents a
 153                   situation where the trip gets constantly triggered soon after
 154                   cooling action is removed.
 155
 156               type:
 157                 $ref: /schemas/types.yaml#/definitions/string
 158                 enum:
 159                   - active   # enable active cooling e.g. fans
 160                   - passive  # enable passive cooling e.g. throttling cpu
 161                   - hot      # send notification to driver
 162                   - critical # send notification to driver, trigger shutdown
 163                 description: |
 164                   There are four valid trip types: active, passive, hot,
 165                   critical.
 166
 167                   The critical trip type is used to set the maximum
 168                   temperature threshold above which the HW becomes
 169                   unstable and underlying firmware might even trigger a
 170                   reboot. Hitting the critical threshold triggers a system
 171                   shutdown.
 172
 173                   The hot trip type can be used to send a notification to
 174                   the thermal driver (if a .notify callback is registered).
 175                   The action to be taken is left to the driver.
 176
 177                   The passive trip type can be used to slow down HW e.g. run
 178                   the CPU, GPU, bus at a lower frequency.
 179
 180                   The active trip type can be used to control other HW to
 181                   help in cooling e.g. fans can be sped up or slowed down
 182
 183             required:
 184               - temperature
 185               - hysteresis
 186               - type
 187             additionalProperties: false
 188
 189         additionalProperties: false
 190
 191       cooling-maps:
 192         type: object
 193         additionalProperties: false
 194         description:
 195           This node describes the action to be taken when a thermal zone
 196           crosses one of the temperature thresholds described in the trips
 197           node. The action takes the form of a mapping relation between a
 198           trip and the target cooling device state.
 199
 200         patternProperties:
 201           "^map[-a-zA-Z0-9]*$":
 202             type: object
 203
 204             properties:
 205               trip:
 206                 $ref: /schemas/types.yaml#/definitions/phandle
 207                 description:
 208                   A phandle of a trip point node within this thermal zone.
 209
 210               cooling-device:
 211                 $ref: /schemas/types.yaml#/definitions/phandle-array
 212                 description:
 213                   A list of cooling device phandles along with the minimum
 214                   and maximum cooling state specifiers for each cooling
 215                   device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
 216                   cooling-device phandle limit specifier lets the framework
 217                   use the minimum and maximum cooling state for that cooling
 218                   device automatically.
 219
 220               contribution:
 221                 $ref: /schemas/types.yaml#/definitions/uint32
 222                 description:
 223                   The cooling contribution to the thermal zone of the referred
 224                   cooling device at the referred trip point. The contribution is
 225                   a ratio of the sum of all cooling contributions within a
 226                   thermal zone.
 227
 228             required:
 229               - trip
 230               - cooling-device
 231             additionalProperties: false
 232
 233     required:
 234       - thermal-sensors
 235
 236     additionalProperties: false
 237
 238 additionalProperties: false
 239
 240 examples:
 241   - |
 242     #include <dt-bindings/interrupt-controller/arm-gic.h>
 243     #include <dt-bindings/thermal/thermal.h>
 244
 245     // Example 1: SDM845 TSENS
 246     soc {
 247             #address-cells = <2>;
 248             #size-cells = <2>;
 249
 250             /* ... */
 251
 252             tsens0: thermal-sensor@c263000 {
 253                     compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
 254                     reg = <0 0x0c263000 0 0x1ff>, /* TM */
 255                           <0 0x0c222000 0 0x1ff>; /* SROT */
 256                     #qcom,sensors = <13>;
 257                     interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
 258                                  <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
 259                     interrupt-names = "uplow", "critical";
 260                     #thermal-sensor-cells = <1>;
 261             };
 262
 263             tsens1: thermal-sensor@c265000 {
 264                     compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
 265                     reg = <0 0x0c265000 0 0x1ff>, /* TM */
 266                           <0 0x0c223000 0 0x1ff>; /* SROT */
 267                     #qcom,sensors = <8>;
 268                     interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
 269                                  <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
 270                     interrupt-names = "uplow", "critical";
 271                     #thermal-sensor-cells = <1>;
 272             };
 273     };
 274
 275     /* ... */
 276
 277     thermal-zones {
 278             cpu0-thermal {
 279                     polling-delay-passive = <250>;
 280                     polling-delay = <1000>;
 281
 282                     thermal-sensors = <&tsens0 1>;
 283
 284                     trips {
 285                             cpu0_alert0: trip-point0 {
 286                                     temperature = <90000>;
 287                                     hysteresis = <2000>;
 288                                     type = "passive";
 289                             };
 290
 291                             cpu0_alert1: trip-point1 {
 292                                     temperature = <95000>;
 293                                     hysteresis = <2000>;
 294                                     type = "passive";
 295                             };
 296
 297                             cpu0_crit: cpu_crit {
 298                                     temperature = <110000>;
 299                                     hysteresis = <1000>;
 300                                     type = "critical";
 301                             };
 302                     };
 303
 304                     cooling-maps {
 305                             map0 {
 306                                     trip = <&cpu0_alert0>;
 307                                     /* Corresponds to 1400MHz in OPP table */
 308                                     cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
 309                                                      <&CPU2 3 3>, <&CPU3 3 3>;
 310                             };
 311
 312                             map1 {
 313                                     trip = <&cpu0_alert1>;
 314                                     /* Corresponds to 1000MHz in OPP table */
 315                                     cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
 316                                                      <&CPU2 5 5>, <&CPU3 5 5>;
 317                             };
 318                     };
 319             };
 320
 321             /* ... */
 322
 323             cluster0-thermal {
 324                     polling-delay-passive = <250>;
 325                     polling-delay = <1000>;
 326
 327                     thermal-sensors = <&tsens0 5>;
 328
 329                     trips {
 330                             cluster0_alert0: trip-point0 {
 331                                     temperature = <90000>;
 332                                     hysteresis = <2000>;
 333                                     type = "hot";
 334                             };
 335                             cluster0_crit: cluster0_crit {
 336                                     temperature = <110000>;
 337                                     hysteresis = <2000>;
 338                                     type = "critical";
 339                             };
 340                     };
 341             };
 342
 343             /* ... */
 344
 345             gpu-top-thermal {
 346                     polling-delay-passive = <250>;
 347                     polling-delay = <1000>;
 348
 349                     thermal-sensors = <&tsens0 11>;
 350
 351                     trips {
 352                             gpu1_alert0: trip-point0 {
 353                                     temperature = <90000>;
 354                                     hysteresis = <2000>;
 355                                     type = "hot";
 356                             };
 357                     };
 358             };
 359     };
 360 ...