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       thermal-sensors:
  79         $ref: /schemas/types.yaml#/definitions/phandle-array
  80         maxItems: 1
  81         description:
  82           The thermal sensor phandle and sensor specifier used to monitor this
  83           thermal zone.
  84
  85       coefficients:
  86         $ref: /schemas/types.yaml#/definitions/uint32-array
  87         description:
  88           An array of integers containing the coefficients of a linear equation
  89           that binds all the sensors listed in this thermal zone.
  90
  91           The linear equation used is as follows,
  92             z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn
  93           where c0, c1, .., cn are the coefficients.
  94
  95           Coefficients default to 1 in case this property is not specified. The
  96           coefficients are ordered and are matched with sensors by means of the
  97           sensor ID. Additional coefficients are interpreted as constant offset.
  98
  99       sustainable-power:
 100         $ref: /schemas/types.yaml#/definitions/uint32
 101         description:
 102           An estimate of the sustainable power (in mW) that this thermal zone
 103           can dissipate at the desired control temperature. For reference, the
 104           sustainable power of a 4-inch phone is typically 2000mW, while on a
 105           10-inch tablet is around 4500mW.
 106
 107       trips:
 108         type: object
 109         description:
 110           This node describes a set of points in the temperature domain at
 111           which the thermal framework needs to take action. The actions to
 112           be taken are defined in another node called cooling-maps.
 113
 114         patternProperties:
 115           "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
 116             type: object
 117
 118             properties:
 119               temperature:
 120                 $ref: /schemas/types.yaml#/definitions/int32
 121                 minimum: -273000
 122                 maximum: 200000
 123                 description:
 124                   An integer expressing the trip temperature in millicelsius.
 125
 126               hysteresis:
 127                 $ref: /schemas/types.yaml#/definitions/uint32
 128                 description:
 129                   An unsigned integer expressing the hysteresis delta with
 130                   respect to the trip temperature property above, also in
 131                   millicelsius. Any cooling action initiated by the framework is
 132                   maintained until the temperature falls below
 133                   (trip temperature - hysteresis). This potentially prevents a
 134                   situation where the trip gets constantly triggered soon after
 135                   cooling action is removed.
 136
 137               type:
 138                 $ref: /schemas/types.yaml#/definitions/string
 139                 enum:
 140                   - active   # enable active cooling e.g. fans
 141                   - passive  # enable passive cooling e.g. throttling cpu
 142                   - hot      # send notification to driver
 143                   - critical # send notification to driver, trigger shutdown
 144                 description: |
 145                   There are four valid trip types: active, passive, hot,
 146                   critical.
 147
 148                   The critical trip type is used to set the maximum
 149                   temperature threshold above which the HW becomes
 150                   unstable and underlying firmware might even trigger a
 151                   reboot. Hitting the critical threshold triggers a system
 152                   shutdown.
 153
 154                   The hot trip type can be used to send a notification to
 155                   the thermal driver (if a .notify callback is registered).
 156                   The action to be taken is left to the driver.
 157
 158                   The passive trip type can be used to slow down HW e.g. run
 159                   the CPU, GPU, bus at a lower frequency.
 160
 161                   The active trip type can be used to control other HW to
 162                   help in cooling e.g. fans can be sped up or slowed down
 163
 164             required:
 165               - temperature
 166               - hysteresis
 167               - type
 168             additionalProperties: false
 169
 170         additionalProperties: false
 171
 172       cooling-maps:
 173         type: object
 174         additionalProperties: false
 175         description:
 176           This node describes the action to be taken when a thermal zone
 177           crosses one of the temperature thresholds described in the trips
 178           node. The action takes the form of a mapping relation between a
 179           trip and the target cooling device state.
 180
 181         patternProperties:
 182           "^map[-a-zA-Z0-9]*$":
 183             type: object
 184
 185             properties:
 186               trip:
 187                 $ref: /schemas/types.yaml#/definitions/phandle
 188                 description:
 189                   A phandle of a trip point node within this thermal zone.
 190
 191               cooling-device:
 192                 $ref: /schemas/types.yaml#/definitions/phandle-array
 193                 description:
 194                   A list of cooling device phandles along with the minimum
 195                   and maximum cooling state specifiers for each cooling
 196                   device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
 197                   cooling-device phandle limit specifier lets the framework
 198                   use the minimum and maximum cooling state for that cooling
 199                   device automatically.
 200
 201               contribution:
 202                 $ref: /schemas/types.yaml#/definitions/uint32
 203                 description:
 204                   The cooling contribution to the thermal zone of the referred
 205                   cooling device at the referred trip point. The contribution is
 206                   a ratio of the sum of all cooling contributions within a
 207                   thermal zone.
 208
 209             required:
 210               - trip
 211               - cooling-device
 212             additionalProperties: false
 213
 214     required:
 215       - polling-delay
 216       - polling-delay-passive
 217       - thermal-sensors
 218       - trips
 219
 220     additionalProperties: false
 221
 222 additionalProperties: false
 223
 224 examples:
 225   - |
 226     #include <dt-bindings/interrupt-controller/arm-gic.h>
 227     #include <dt-bindings/thermal/thermal.h>
 228
 229     // Example 1: SDM845 TSENS
 230     soc {
 231             #address-cells = <2>;
 232             #size-cells = <2>;
 233
 234             /* ... */
 235
 236             tsens0: thermal-sensor@c263000 {
 237                     compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
 238                     reg = <0 0x0c263000 0 0x1ff>, /* TM */
 239                           <0 0x0c222000 0 0x1ff>; /* SROT */
 240                     #qcom,sensors = <13>;
 241                     interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
 242                                  <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
 243                     interrupt-names = "uplow", "critical";
 244                     #thermal-sensor-cells = <1>;
 245             };
 246
 247             tsens1: thermal-sensor@c265000 {
 248                     compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
 249                     reg = <0 0x0c265000 0 0x1ff>, /* TM */
 250                           <0 0x0c223000 0 0x1ff>; /* SROT */
 251                     #qcom,sensors = <8>;
 252                     interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
 253                                  <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
 254                     interrupt-names = "uplow", "critical";
 255                     #thermal-sensor-cells = <1>;
 256             };
 257     };
 258
 259     /* ... */
 260
 261     thermal-zones {
 262             cpu0-thermal {
 263                     polling-delay-passive = <250>;
 264                     polling-delay = <1000>;
 265
 266                     thermal-sensors = <&tsens0 1>;
 267
 268                     trips {
 269                             cpu0_alert0: trip-point0 {
 270                                     temperature = <90000>;
 271                                     hysteresis = <2000>;
 272                                     type = "passive";
 273                             };
 274
 275                             cpu0_alert1: trip-point1 {
 276                                     temperature = <95000>;
 277                                     hysteresis = <2000>;
 278                                     type = "passive";
 279                             };
 280
 281                             cpu0_crit: cpu_crit {
 282                                     temperature = <110000>;
 283                                     hysteresis = <1000>;
 284                                     type = "critical";
 285                             };
 286                     };
 287
 288                     cooling-maps {
 289                             map0 {
 290                                     trip = <&cpu0_alert0>;
 291                                     /* Corresponds to 1400MHz in OPP table */
 292                                     cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
 293                                                      <&CPU2 3 3>, <&CPU3 3 3>;
 294                             };
 295
 296                             map1 {
 297                                     trip = <&cpu0_alert1>;
 298                                     /* Corresponds to 1000MHz in OPP table */
 299                                     cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
 300                                                      <&CPU2 5 5>, <&CPU3 5 5>;
 301                             };
 302                     };
 303             };
 304
 305             /* ... */
 306
 307             cluster0-thermal {
 308                     polling-delay-passive = <250>;
 309                     polling-delay = <1000>;
 310
 311                     thermal-sensors = <&tsens0 5>;
 312
 313                     trips {
 314                             cluster0_alert0: trip-point0 {
 315                                     temperature = <90000>;
 316                                     hysteresis = <2000>;
 317                                     type = "hot";
 318                             };
 319                             cluster0_crit: cluster0_crit {
 320                                     temperature = <110000>;
 321                                     hysteresis = <2000>;
 322                                     type = "critical";
 323                             };
 324                     };
 325             };
 326
 327             /* ... */
 328
 329             gpu-top-thermal {
 330                     polling-delay-passive = <250>;
 331                     polling-delay = <1000>;
 332
 333                     thermal-sensors = <&tsens0 11>;
 334
 335                     trips {
 336                             gpu1_alert0: trip-point0 {
 337                                     temperature = <90000>;
 338                                     hysteresis = <2000>;
 339                                     type = "hot";
 340                             };
 341                     };
 342             };
 343     };
 344 ...