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   "^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$":
  53     type: object
  54     description:
  55       Each thermal zone node contains information about how frequently it
  56       must be checked, the sensor responsible for reporting temperature for
  57       this zone, one sub-node containing the various trip points for this
  58       zone and one sub-node containing all the zone cooling-maps.
  59
  60     properties:
  61       polling-delay:
  62         $ref: /schemas/types.yaml#/definitions/uint32
  63         description:
  64           The maximum number of milliseconds to wait between polls when
  65           checking this thermal zone. Setting this to 0 disables the polling
  66           timers setup by the thermal framework and assumes that the thermal
  67           sensors in this zone support interrupts.
  68
  69       polling-delay-passive:
  70         $ref: /schemas/types.yaml#/definitions/uint32
  71         description:
  72           The maximum number of milliseconds to wait between polls when
  73           checking this thermal zone while doing passive cooling. Setting
  74           this to 0 disables the polling timers setup by the thermal
  75           framework and assumes that the thermal sensors in this zone
  76           support interrupts.
  77
  78       critical-action:
  79         $ref: /schemas/types.yaml#/definitions/string
  80         description: |
  81           The action the OS should perform after the critical temperature is reached.
  82           By default the system will shutdown as a safe action to prevent damage
  83           to the hardware, if the property is not set.
  84           The shutdown action should be always the default and preferred one.
  85           Choose 'reboot' with care, as the hardware may be in thermal stress,
  86           thus leading to infinite reboots that may cause damage to the hardware.
  87           Make sure the firmware/bootloader will act as the last resort and take
  88           over the thermal control.
  89
  90         enum:
  91           - shutdown
  92           - reboot
  93
  94       thermal-sensors:
  95         $ref: /schemas/types.yaml#/definitions/phandle-array
  96         maxItems: 1
  97         description:
  98           The thermal sensor phandle and sensor specifier used to monitor this
  99           thermal zone.
 100
 101       coefficients:
 102         $ref: /schemas/types.yaml#/definitions/uint32-array
 103         description:
 104           An array of integers containing the coefficients of a linear equation
 105           that binds all the sensors listed in this thermal zone.
 106
 107           The linear equation used is as follows,
 108             z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn
 109           where c0, c1, .., cn are the coefficients.
 110
 111           Coefficients default to 1 in case this property is not specified. The
 112           coefficients are ordered and are matched with sensors by means of the
 113           sensor ID. Additional coefficients are interpreted as constant offset.
 114
 115       sustainable-power:
 116         $ref: /schemas/types.yaml#/definitions/uint32
 117         description:
 118           An estimate of the sustainable power (in mW) that this thermal zone
 119           can dissipate at the desired control temperature. For reference, the
 120           sustainable power of a 4-inch phone is typically 2000mW, while on a
 121           10-inch tablet is around 4500mW.
 122
 123       trips:
 124         type: object
 125         description:
 126           This node describes a set of points in the temperature domain at
 127           which the thermal framework needs to take action. The actions to
 128           be taken are defined in another node called cooling-maps.
 129
 130         patternProperties:
 131           "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
 132             type: object
 133
 134             properties:
 135               temperature:
 136                 $ref: /schemas/types.yaml#/definitions/int32
 137                 minimum: -273000
 138                 maximum: 200000
 139                 description:
 140                   An integer expressing the trip temperature in millicelsius.
 141
 142               hysteresis:
 143                 $ref: /schemas/types.yaml#/definitions/uint32
 144                 description:
 145                   An unsigned integer expressing the hysteresis delta with
 146                   respect to the trip temperature property above, also in
 147                   millicelsius. Any cooling action initiated by the framework is
 148                   maintained until the temperature falls below
 149                   (trip temperature - hysteresis). This potentially prevents a
 150                   situation where the trip gets constantly triggered soon after
 151                   cooling action is removed.
 152
 153               type:
 154                 $ref: /schemas/types.yaml#/definitions/string
 155                 enum:
 156                   - active   # enable active cooling e.g. fans
 157                   - passive  # enable passive cooling e.g. throttling cpu
 158                   - hot      # send notification to driver
 159                   - critical # send notification to driver, trigger shutdown
 160                 description: |
 161                   There are four valid trip types: active, passive, hot,
 162                   critical.
 163
 164                   The critical trip type is used to set the maximum
 165                   temperature threshold above which the HW becomes
 166                   unstable and underlying firmware might even trigger a
 167                   reboot. Hitting the critical threshold triggers a system
 168                   shutdown.
 169
 170                   The hot trip type can be used to send a notification to
 171                   the thermal driver (if a .notify callback is registered).
 172                   The action to be taken is left to the driver.
 173
 174                   The passive trip type can be used to slow down HW e.g. run
 175                   the CPU, GPU, bus at a lower frequency.
 176
 177                   The active trip type can be used to control other HW to
 178                   help in cooling e.g. fans can be sped up or slowed down
 179
 180             required:
 181               - temperature
 182               - hysteresis
 183               - type
 184             additionalProperties: false
 185
 186         additionalProperties: false
 187
 188       cooling-maps:
 189         type: object
 190         additionalProperties: false
 191         description:
 192           This node describes the action to be taken when a thermal zone
 193           crosses one of the temperature thresholds described in the trips
 194           node. The action takes the form of a mapping relation between a
 195           trip and the target cooling device state.
 196
 197         patternProperties:
 198           "^map[-a-zA-Z0-9]*$":
 199             type: object
 200
 201             properties:
 202               trip:
 203                 $ref: /schemas/types.yaml#/definitions/phandle
 204                 description:
 205                   A phandle of a trip point node within this thermal zone.
 206
 207               cooling-device:
 208                 $ref: /schemas/types.yaml#/definitions/phandle-array
 209                 description:
 210                   A list of cooling device phandles along with the minimum
 211                   and maximum cooling state specifiers for each cooling
 212                   device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
 213                   cooling-device phandle limit specifier lets the framework
 214                   use the minimum and maximum cooling state for that cooling
 215                   device automatically.
 216
 217               contribution:
 218                 $ref: /schemas/types.yaml#/definitions/uint32
 219                 description:
 220                   The cooling contribution to the thermal zone of the referred
 221                   cooling device at the referred trip point. The contribution is
 222                   a ratio of the sum of all cooling contributions within a
 223                   thermal zone.
 224
 225             required:
 226               - trip
 227               - cooling-device
 228             additionalProperties: false
 229
 230     required:
 231       - polling-delay
 232       - polling-delay-passive
 233       - thermal-sensors
 234       - trips
 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 ...