thermal-zones.yaml

Version: - FREEBSD - FREEBSD-13-STABLE - FREEBSD-13-0 - FREEBSD-12-STABLE - FREEBSD-12-0 - FREEBSD-11-STABLE - FREEBSD-11-0 - FREEBSD-10-STABLE - FREEBSD-10-0 - FREEBSD-9-STABLE - FREEBSD-9-0 - FREEBSD-8-STABLE - FREEBSD-8-0 - FREEBSD-7-STABLE - FREEBSD-7-0 - FREEBSD-6-STABLE - FREEBSD-6-0 - FREEBSD-5-STABLE - FREEBSD-5-0 - FREEBSD-4-STABLE - FREEBSD-3-STABLE - FREEBSD22 - l41 - OPENBSD - linux-2.6 - MK84 - PLAN9 - xnu-8792
SearchContext: - none - 3 - 10
    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 binding
    9 
   10 maintainers:
   11   - Amit Kucheria <amitk@kernel.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         description:
  175           This node describes the action to be taken when a thermal zone
  176           crosses one of the temperature thresholds described in the trips
  177           node. The action takes the form of a mapping relation between a
  178           trip and the target cooling device state.
  179 
  180         patternProperties:
  181           "^map[-a-zA-Z0-9]*$":
  182             type: object
  183 
  184             properties:
  185               trip:
  186                 $ref: /schemas/types.yaml#/definitions/phandle
  187                 description:
  188                   A phandle of a trip point node within this thermal zone.
  189 
  190               cooling-device:
  191                 $ref: /schemas/types.yaml#/definitions/phandle-array
  192                 description:
  193                   A list of cooling device phandles along with the minimum
  194                   and maximum cooling state specifiers for each cooling
  195                   device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
  196                   cooling-device phandle limit specifier lets the framework
  197                   use the minimum and maximum cooling state for that cooling
  198                   device automatically.
  199 
  200               contribution:
  201                 $ref: /schemas/types.yaml#/definitions/uint32
  202                 description:
  203                   The cooling contribution to the thermal zone of the referred
  204                   cooling device at the referred trip point. The contribution is
  205                   a ratio of the sum of all cooling contributions within a
  206                   thermal zone.
  207 
  208             required:
  209               - trip
  210               - cooling-device
  211             additionalProperties: false
  212 
  213     required:
  214       - polling-delay
  215       - polling-delay-passive
  216       - thermal-sensors
  217       - trips
  218 
  219     additionalProperties: false
  220 
  221 additionalProperties: false
  222 
  223 examples:
  224   - |
  225     #include <dt-bindings/interrupt-controller/arm-gic.h>
  226     #include <dt-bindings/thermal/thermal.h>
  227 
  228     // Example 1: SDM845 TSENS
  229     soc {
  230             #address-cells = <2>;
  231             #size-cells = <2>;
  232 
  233             /* ... */
  234 
  235             tsens0: thermal-sensor@c263000 {
  236                     compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
  237                     reg = <0 0x0c263000 0 0x1ff>, /* TM */
  238                           <0 0x0c222000 0 0x1ff>; /* SROT */
  239                     #qcom,sensors = <13>;
  240                     interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
  241                                  <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
  242                     interrupt-names = "uplow", "critical";
  243                     #thermal-sensor-cells = <1>;
  244             };
  245 
  246             tsens1: thermal-sensor@c265000 {
  247                     compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
  248                     reg = <0 0x0c265000 0 0x1ff>, /* TM */
  249                           <0 0x0c223000 0 0x1ff>; /* SROT */
  250                     #qcom,sensors = <8>;
  251                     interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
  252                                  <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
  253                     interrupt-names = "uplow", "critical";
  254                     #thermal-sensor-cells = <1>;
  255             };
  256     };
  257 
  258     /* ... */
  259 
  260     thermal-zones {
  261             cpu0-thermal {
  262                     polling-delay-passive = <250>;
  263                     polling-delay = <1000>;
  264 
  265                     thermal-sensors = <&tsens0 1>;
  266 
  267                     trips {
  268                             cpu0_alert0: trip-point0 {
  269                                     temperature = <90000>;
  270                                     hysteresis = <2000>;
  271                                     type = "passive";
  272                             };
  273 
  274                             cpu0_alert1: trip-point1 {
  275                                     temperature = <95000>;
  276                                     hysteresis = <2000>;
  277                                     type = "passive";
  278                             };
  279 
  280                             cpu0_crit: cpu_crit {
  281                                     temperature = <110000>;
  282                                     hysteresis = <1000>;
  283                                     type = "critical";
  284                             };
  285                     };
  286 
  287                     cooling-maps {
  288                             map0 {
  289                                     trip = <&cpu0_alert0>;
  290                                     /* Corresponds to 1400MHz in OPP table */
  291                                     cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
  292                                                      <&CPU2 3 3>, <&CPU3 3 3>;
  293                             };
  294 
  295                             map1 {
  296                                     trip = <&cpu0_alert1>;
  297                                     /* Corresponds to 1000MHz in OPP table */
  298                                     cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
  299                                                      <&CPU2 5 5>, <&CPU3 5 5>;
  300                             };
  301                     };
  302             };
  303 
  304             /* ... */
  305 
  306             cluster0-thermal {
  307                     polling-delay-passive = <250>;
  308                     polling-delay = <1000>;
  309 
  310                     thermal-sensors = <&tsens0 5>;
  311 
  312                     trips {
  313                             cluster0_alert0: trip-point0 {
  314                                     temperature = <90000>;
  315                                     hysteresis = <2000>;
  316                                     type = "hot";
  317                             };
  318                             cluster0_crit: cluster0_crit {
  319                                     temperature = <110000>;
  320                                     hysteresis = <2000>;
  321                                     type = "critical";
  322                             };
  323                     };
  324             };
  325 
  326             /* ... */
  327 
  328             gpu-top-thermal {
  329                     polling-delay-passive = <250>;
  330                     polling-delay = <1000>;
  331 
  332                     thermal-sensors = <&tsens0 11>;
  333 
  334                     trips {
  335                             gpu1_alert0: trip-point0 {
  336                                     temperature = <90000>;
  337                                     hysteresis = <2000>;
  338                                     type = "hot";
  339                             };
  340                     };
  341             };
  342     };
  343 ...
Cache object: e81336b2ae93835e352301e4fe910875
[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]
This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.
FreeBSD/Linux Kernel Cross Reference sys/contrib/device-tree/Bindings/thermal/thermal-zones.yaml

FreeBSD/Linux Kernel Cross Reference
sys/contrib/device-tree/Bindings/thermal/thermal-zones.yaml
