Thermal Zones

Thermal zone 공통 스키마

GPL-2.0 라이선스의 이 YAML 스키마는 devicetree의 thermal zone을 정의합니다. 저작권자는 Linaro Ltd.이고 maintainer는 Daniel Lezcano입니다.

Thermal 관리 시스템의 세 구성 요소

Devicetree의 thermal 관리는 sensor hardware와 cooling device 및 thermal zone의 software abstraction을 기술하여 thermal overload를 완화하는 적절한 동작을 수행합니다. 전체 시스템은 온도를 측정하고 SoC별 binding을 갖는 `thermal-sensor`, 수동 또는 능동 방식으로 열을 방출하는 `cooling-device`, 플랫폼의 모든 thermal data를 담는 `thermal-zones` 컨테이너로 구성됩니다. 이 binding은 그중 `thermal-zones`를 설명합니다.

최대 dT/dt에 따른 polling 간격

Thermal zone의 polling-delay 속성은 두 상황의 최대 dT/dt, 즉 시간에 따른 온도 변화율에 맞춰야 합니다. Passive cooling이 활성화된 동안에는 `polling-delay-passive`, 단순 감시 중이거나 active cooling이 활성화된 동안에는 `polling-delay`를 사용합니다. 최대 dT/dt는 hardware power consumption과 heat dissipation capability에 크게 좌우됩니다. Poll 사이에 여러 trip boundary를 예상치 못하게 넘어가지 않도록 지연을 정해야 하며, 올바른 간격은 silicon structure를 손상하거나 silicon lifetime을 줄일 수 있는 온도 범위에 장치가 머무는 일을 방지합니다.

컨테이너와 zone 이름 제약

Thermal framework가 여러 zone의 입력을 관리하고 과열을 완화하려면 `/thermal-zones` node가 필요하며 `$nodename`은 정확히 `thermal-zones`입니다. 이 node는 실제 장치를 나타내지 않고 thermal sensor, temperature threshold에 관한 platform data, threshold를 넘을 때의 mitigation action을 연결하는 컨테이너입니다. 각 zone 이름은 정규식 `^[a-zA-Z][a-zA-Z0-9\-]{1,10}-thermal$`을 따릅니다. Linux kernel의 `THERMAL_NAME_LENGTH` 제한 때문에 terminating NUL byte를 포함한 전체 길이는 19 characters입니다.

properties:
  $nodename:
    const: thermal-zones
    description:
      A /thermal-zones node is required in order to use the thermal framework to
      manage input from the various thermal zones in the system in order to
      mitigate thermal overload conditions. It does not represent a real device
      in the system, but acts as a container to link a thermal sensor device,
      platform-data regarding temperature thresholds and the mitigation actions
      to take when the temperature crosses those thresholds.

patternProperties:
  # Node name is limited in size due to Linux kernel requirements - 19
  # characters in total (see THERMAL_NAME_LENGTH, including terminating NUL
  # byte):
  "^[a-zA-Z][a-zA-Z0-9\\-]{1,10}-thermal$":
    type: object
    description:
      Each thermal zone node contains information about how frequently it
      must be checked, the sensor responsible for reporting temperature for
      this zone, one sub-node containing the various trip points for this
      zone and one sub-node containing all the zone cooling-maps.

Polling timer와 critical-action

각 zone은 검사 주기, 온도를 보고하는 sensor, trip point 하위 node, cooling-map 하위 node를 담습니다. `polling-delay`는 일반 감시 중 poll 사이의 최대 millisecond이고 `polling-delay-passive`는 passive cooling 중의 최대 millisecond입니다. 어느 값을 0으로 설정하면 thermal framework가 만드는 polling timer가 비활성화되므로 해당 zone sensor가 interrupt를 지원한다고 가정합니다.

`critical-action`은 critical temperature 도달 후 OS가 수행할 동작입니다. 속성이 없으면 system이 동작을 선택하며 권장 기본값은 `shutdown`입니다. `reboot`는 hardware가 thermal stress 상태일 때 infinite reboot와 추가 손상을 일으킬 수 있으므로 주의해서 선택해야 합니다. Firmware/bootloader는 최후 수단으로 thermal control을 인계할 수 있어야 합니다. 허용 값은 `shutdown`과 `reboot`입니다.

properties:
  polling-delay:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      The maximum number of milliseconds to wait between polls when
      checking this thermal zone. Setting this to 0 disables the polling
      timers setup by the thermal framework and assumes that the thermal
      sensors in this zone support interrupts.

  polling-delay-passive:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      The maximum number of milliseconds to wait between polls when
      checking this thermal zone while doing passive cooling. Setting
      this to 0 disables the polling timers setup by the thermal
      framework and assumes that the thermal sensors in this zone
      support interrupts.

  critical-action:
    $ref: /schemas/types.yaml#/definitions/string
    description: |
      The action the OS should perform after the critical temperature is reached.
      If the property is not set, it is up to the system to select the correct
      action. The recommended and preferred default is shutdown.
      Choose 'reboot' with care, as the hardware may be in thermal stress,
      thus leading to infinite reboots that may cause damage to the hardware.
      Make sure the firmware/bootloader will act as the last resort and take
      over the thermal control.

    enum:
      - shutdown
      - reboot

Sensor, 선형 계수와 지속 가능 전력

`thermal-sensors`는 이 zone을 감시하는 thermal sensor phandle과 sensor specifier를 담으며 항목은 하나로 제한됩니다. `coefficients`는 zone에 나열된 sensor들을 결합하는 선형식의 정수 계수 배열입니다. 식은 `z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn`이고 c0부터 cn까지가 coefficients입니다. 속성이 없으면 계수의 default는 1입니다. 계수는 순서대로 배치되고 sensor ID로 sensor와 대응하며, sensor 수보다 더 있는 계수는 constant offset으로 해석됩니다.

`sustainable-power`는 원하는 control temperature에서 이 thermal zone이 지속적으로 방출할 수 있다고 추정한 전력을 mW 단위로 나타냅니다. 참고로 4-inch phone은 보통 2000mW, 10-inch tablet은 약 4500mW입니다.

thermal-sensors:
  $ref: /schemas/types.yaml#/definitions/phandle-array
  maxItems: 1
  description:
    The thermal sensor phandle and sensor specifier used to monitor this
    thermal zone.

coefficients:
  $ref: /schemas/types.yaml#/definitions/uint32-array
  description:
    An array of integers containing the coefficients of a linear equation
    that binds all the sensors listed in this thermal zone.

    The linear equation used is as follows,
      z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn
    where c0, c1, .., cn are the coefficients.

    Coefficients default to 1 in case this property is not specified. The
    coefficients are ordered and are matched with sensors by means of the
    sensor ID. Additional coefficients are interpreted as constant offset.

sustainable-power:
  $ref: /schemas/types.yaml#/definitions/uint32
  description:
    An estimate of the sustainable power (in mW) that this thermal zone
    can dissipate at the desired control temperature. For reference, the
    sustainable power of a 4-inch phone is typically 2000mW, while on a
    10-inch tablet is around 4500mW.

Trip point와 네 가지 동작 유형

`trips` node는 thermal framework가 동작해야 하는 temperature domain의 지점들을 정의하며 실제 동작은 `cooling-maps`에서 연결합니다. 각 trip 이름은 `^[a-zA-Z][a-zA-Z0-9\-_]{0,63}$`을 따릅니다. `temperature`는 millicelsius 단위 int32로 minimum -273000, maximum 200000입니다. `hysteresis`도 millicelsius 단위의 unsigned delta이며, 시작된 cooling action은 온도가 `(trip temperature - hysteresis)` 아래로 내려갈 때까지 유지됩니다. 이는 cooling action 제거 직후 trip이 계속 다시 발생하는 상황을 줄입니다.

유효한 trip type은 `active`, `passive`, `hot`, `critical` 네 가지입니다. `critical`은 HW가 불안정해지고 firmware가 reboot를 일으킬 수도 있는 최대 threshold이며 도달하면 system shutdown을 유발합니다. `hot`은 `.notify` callback이 등록된 thermal driver에 notification을 보내고 후속 동작은 driver에 맡깁니다. `passive`는 CPU, GPU, bus 등을 더 낮은 frequency로 실행해 HW를 늦춥니다. `active`는 fan 속도처럼 냉각을 돕는 다른 HW를 제어합니다. 모든 trip에는 `temperature`, `hysteresis`, `type`이 필요합니다.

trips:
  type: object
  description:
    This node describes a set of points in the temperature domain at
    which the thermal framework needs to take action. The actions to
    be taken are defined in another node called cooling-maps.

  patternProperties:
    "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
      type: object

      properties:
        temperature:
          $ref: /schemas/types.yaml#/definitions/int32
          minimum: -273000
          maximum: 200000
          description:
            An integer expressing the trip temperature in millicelsius.

        hysteresis:
          $ref: /schemas/types.yaml#/definitions/uint32
          description:
            An unsigned integer expressing the hysteresis delta with
            respect to the trip temperature property above, also in
            millicelsius. Any cooling action initiated by the framework is
            maintained until the temperature falls below
            (trip temperature - hysteresis). This potentially prevents a
            situation where the trip gets constantly triggered soon after
            cooling action is removed.

        type:
          $ref: /schemas/types.yaml#/definitions/string
          enum:
            - active   # enable active cooling e.g. fans
            - passive  # enable passive cooling e.g. throttling cpu
            - hot      # send notification to driver
            - critical # send notification to driver, trigger shutdown
          description: |
            There are four valid trip types: active, passive, hot,
            critical.

            The critical trip type is used to set the maximum
            temperature threshold above which the HW becomes
            unstable and underlying firmware might even trigger a
            reboot. Hitting the critical threshold triggers a system
            shutdown.

            The hot trip type can be used to send a notification to
            the thermal driver (if a .notify callback is registered).
            The action to be taken is left to the driver.

            The passive trip type can be used to slow down HW e.g. run
            the CPU, GPU, bus at a lower frequency.

            The active trip type can be used to control other HW to
            help in cooling e.g. fans can be sped up or slowed down

      required:
        - temperature
        - hysteresis
        - type
      additionalProperties: false

  additionalProperties: false

Trip과 cooling device state의 연결

`cooling-maps`는 zone이 `trips`의 temperature threshold를 넘을 때 취할 동작을 정의하고, trip과 target cooling device state 사이의 mapping relation으로 표현합니다. Map 이름은 `^map[-a-zA-Z0-9]*$`을 따릅니다. `trip`은 같은 thermal zone 안의 trip point node phandle입니다. `cooling-device`는 각 cooling device phandle과 minimum 및 maximum cooling state specifier의 목록입니다. Limit specifier에 `THERMAL_NO_LIMIT (-1UL)`을 쓰면 framework가 해당 장치의 최소·최대 cooling state를 자동 사용합니다.

선택적인 `contribution`은 해당 trip에서 참조한 cooling device가 zone 냉각에 기여하는 비율이며, 한 thermal zone 안의 모든 cooling contribution 합에 대한 ratio입니다. 각 map에는 `trip`과 `cooling-device`가 반드시 있어야 하고, 각 zone에는 `thermal-sensors`가 필수입니다. 정의되지 않은 추가 속성은 허용되지 않습니다.

      cooling-maps:
        type: object
        additionalProperties: false
        description:
          This node describes the action to be taken when a thermal zone
          crosses one of the temperature thresholds described in the trips
          node. The action takes the form of a mapping relation between a
          trip and the target cooling device state.

        patternProperties:
          "^map[-a-zA-Z0-9]*$":
            type: object

            properties:
              trip:
                $ref: /schemas/types.yaml#/definitions/phandle
                description:
                  A phandle of a trip point node within this thermal zone.

              cooling-device:
                $ref: /schemas/types.yaml#/definitions/phandle-array
                description:
                  A list of cooling device phandles along with the minimum
                  and maximum cooling state specifiers for each cooling
                  device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
                  cooling-device phandle limit specifier lets the framework
                  use the minimum and maximum cooling state for that cooling
                  device automatically.

              contribution:
                $ref: /schemas/types.yaml#/definitions/uint32
                description:
                  The cooling contribution to the thermal zone of the referred
                  cooling device at the referred trip point. The contribution is
                  a ratio of the sum of all cooling contributions within a
                  thermal zone.

            required:
              - trip
              - cooling-device
            additionalProperties: false

    required:
      - thermal-sensors

    additionalProperties: false

additionalProperties: false

SDM845 TSENS provider 예제

예제는 SDM845의 TSENS provider 두 개를 구성합니다. `tsens0`은 TM과 SROT register 영역, sensors 13개, `uplow` 및 `critical` interrupt를 갖고, `tsens1`은 별도 register 영역, sensors 8개와 같은 두 interrupt 종류를 갖습니다. 둘 다 `#thermal-sensor-cells = <1>`로 sensor index를 받습니다.

- |
  #include <dt-bindings/interrupt-controller/arm-gic.h>
  #include <dt-bindings/thermal/thermal.h>

  // Example 1: SDM845 TSENS
  soc {
          #address-cells = <2>;
          #size-cells = <2>;

          /* ... */

          tsens0: thermal-sensor@c263000 {
                  compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
                  reg = <0 0x0c263000 0 0x1ff>, /* TM */
                        <0 0x0c222000 0 0x1ff>; /* SROT */
                  #qcom,sensors = <13>;
                  interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
                               <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
                  interrupt-names = "uplow", "critical";
                  #thermal-sensor-cells = <1>;
          };

          tsens1: thermal-sensor@c265000 {
                  compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
                  reg = <0 0x0c265000 0 0x1ff>, /* TM */
                        <0 0x0c223000 0 0x1ff>; /* SROT */
                  #qcom,sensors = <8>;
                  interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
                               <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
                  interrupt-names = "uplow", "critical";
                  #thermal-sensor-cells = <1>;
          };
  };

  /* ... */

CPU0 trip과 주파수 cooling map

`cpu0-thermal` zone은 passive polling 250ms, 일반 polling 1000ms로 `tsens0`의 sensor index 1을 감시합니다. Passive trip은 90000 및 95000 millicelsius이고 각 hysteresis는 2000입니다. Critical trip은 110000, hysteresis 1000입니다. 첫 map은 90000 trip에서 CPU0부터 CPU3까지 `<3 3>` state를 선택하며 OPP table의 1400MHz에 해당합니다. 둘째 map은 95000 trip에서 네 CPU 모두 `<5 5>` state를 선택하며 1000MHz에 해당합니다.

thermal-zones {
        cpu0-thermal {
                polling-delay-passive = <250>;
                polling-delay = <1000>;

                thermal-sensors = <&tsens0 1>;

                trips {
                        cpu0_alert0: trip-point0 {
                                temperature = <90000>;
                                hysteresis = <2000>;
                                type = "passive";
                        };

                        cpu0_alert1: trip-point1 {
                                temperature = <95000>;
                                hysteresis = <2000>;
                                type = "passive";
                        };

                        cpu0_crit: cpu_crit {
                                temperature = <110000>;
                                hysteresis = <1000>;
                                type = "critical";
                        };
                };

                cooling-maps {
                        map0 {
                                trip = <&cpu0_alert0>;
                                /* Corresponds to 1400MHz in OPP table */
                                cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
                                                 <&CPU2 3 3>, <&CPU3 3 3>;
                        };

                        map1 {
                                trip = <&cpu0_alert1>;
                                /* Corresponds to 1000MHz in OPP table */
                                cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
                                                 <&CPU2 5 5>, <&CPU3 5 5>;
                        };
                };
        };

        /* ... */

Cluster0 hot·critical trip

`cluster0-thermal` zone은 passive polling 250ms, 일반 polling 1000ms로 `tsens0` sensor index 5를 사용합니다. 90000 millicelsius의 `hot` trip과 110000 millicelsius의 `critical` trip을 두며 둘의 hysteresis는 2000입니다.

cluster0-thermal {
        polling-delay-passive = <250>;
        polling-delay = <1000>;

        thermal-sensors = <&tsens0 5>;

        trips {
                cluster0_alert0: trip-point0 {
                        temperature = <90000>;
                        hysteresis = <2000>;
                        type = "hot";
                };
                cluster0_crit: cluster0_crit {
                        temperature = <110000>;
                        hysteresis = <2000>;
                        type = "critical";
                };
        };
};

/* ... */

GPU top hot trip

`gpu-top-thermal` zone은 passive polling 250ms, 일반 polling 1000ms로 `tsens0` sensor index 11을 감시합니다. 90000 millicelsius, hysteresis 2000의 `hot` trip 하나를 정의합니다.

            gpu-top-thermal {
                    polling-delay-passive = <250>;
                    polling-delay = <1000>;

                    thermal-sensors = <&tsens0 11>;

                    trips {
                            gpu1_alert0: trip-point0 {
                                    temperature = <90000>;
                                    hysteresis = <2000>;
                                    type = "hot";
                            };
                    };
            };
    };
...