0001 # SPDX-License-Identifier: (GPL-2.0)
0002 # Copyright 2020 Linaro Ltd.
0003 %YAML 1.2
0004 ---
0005 $id: http://devicetree.org/schemas/thermal/thermal-zones.yaml#
0006 $schema: http://devicetree.org/meta-schemas/base.yaml#
0007
0008 title: Thermal zone binding
0009
0010 maintainers:
0011 - Amit Kucheria <amitk@kernel.org>
0012
0013 description: |
0014 Thermal management is achieved in devicetree by describing the sensor hardware
0015 and the software abstraction of cooling devices and thermal zones required to
0016 take appropriate action to mitigate thermal overloads.
0017
0018 The following node types are used to completely describe a thermal management
0019 system in devicetree:
0020 - thermal-sensor: device that measures temperature, has SoC-specific bindings
0021 - cooling-device: device used to dissipate heat either passively or actively
0022 - thermal-zones: a container of the following node types used to describe all
0023 thermal data for the platform
0024
0025 This binding describes the thermal-zones.
0026
0027 The polling-delay properties of a thermal-zone are bound to the maximum dT/dt
0028 (temperature derivative over time) in two situations for a thermal zone:
0029 1. when passive cooling is activated (polling-delay-passive)
0030 2. when the zone just needs to be monitored (polling-delay) or when
0031 active cooling is activated.
0032
0033 The maximum dT/dt is highly bound to hardware power consumption and
0034 dissipation capability. The delays should be chosen to account for said
0035 max dT/dt, such that a device does not cross several trip boundaries
0036 unexpectedly between polls. Choosing the right polling delays shall avoid
0037 having the device in temperature ranges that may damage the silicon structures
0038 and reduce silicon lifetime.
0039
0040 properties:
0041 $nodename:
0042 const: thermal-zones
0043 description:
0044 A /thermal-zones node is required in order to use the thermal framework to
0045 manage input from the various thermal zones in the system in order to
0046 mitigate thermal overload conditions. It does not represent a real device
0047 in the system, but acts as a container to link a thermal sensor device,
0048 platform-data regarding temperature thresholds and the mitigation actions
0049 to take when the temperature crosses those thresholds.
0050
0051 patternProperties:
0052 "^[a-zA-Z][a-zA-Z0-9\\-]{1,12}-thermal$":
0053 type: object
0054 description:
0055 Each thermal zone node contains information about how frequently it
0056 must be checked, the sensor responsible for reporting temperature for
0057 this zone, one sub-node containing the various trip points for this
0058 zone and one sub-node containing all the zone cooling-maps.
0059
0060 properties:
0061 polling-delay:
0062 $ref: /schemas/types.yaml#/definitions/uint32
0063 description:
0064 The maximum number of milliseconds to wait between polls when
0065 checking this thermal zone. Setting this to 0 disables the polling
0066 timers setup by the thermal framework and assumes that the thermal
0067 sensors in this zone support interrupts.
0068
0069 polling-delay-passive:
0070 $ref: /schemas/types.yaml#/definitions/uint32
0071 description:
0072 The maximum number of milliseconds to wait between polls when
0073 checking this thermal zone while doing passive cooling. Setting
0074 this to 0 disables the polling timers setup by the thermal
0075 framework and assumes that the thermal sensors in this zone
0076 support interrupts.
0077
0078 thermal-sensors:
0079 $ref: /schemas/types.yaml#/definitions/phandle-array
0080 maxItems: 1
0081 description:
0082 The thermal sensor phandle and sensor specifier used to monitor this
0083 thermal zone.
0084
0085 coefficients:
0086 $ref: /schemas/types.yaml#/definitions/uint32-array
0087 description:
0088 An array of integers containing the coefficients of a linear equation
0089 that binds all the sensors listed in this thermal zone.
0090
0091 The linear equation used is as follows,
0092 z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn
0093 where c0, c1, .., cn are the coefficients.
0094
0095 Coefficients default to 1 in case this property is not specified. The
0096 coefficients are ordered and are matched with sensors by means of the
0097 sensor ID. Additional coefficients are interpreted as constant offset.
0098
0099 sustainable-power:
0100 $ref: /schemas/types.yaml#/definitions/uint32
0101 description:
0102 An estimate of the sustainable power (in mW) that this thermal zone
0103 can dissipate at the desired control temperature. For reference, the
0104 sustainable power of a 4-inch phone is typically 2000mW, while on a
0105 10-inch tablet is around 4500mW.
0106
0107 trips:
0108 type: object
0109 description:
0110 This node describes a set of points in the temperature domain at
0111 which the thermal framework needs to take action. The actions to
0112 be taken are defined in another node called cooling-maps.
0113
0114 patternProperties:
0115 "^[a-zA-Z][a-zA-Z0-9\\-_]{0,63}$":
0116 type: object
0117
0118 properties:
0119 temperature:
0120 $ref: /schemas/types.yaml#/definitions/int32
0121 minimum: -273000
0122 maximum: 200000
0123 description:
0124 An integer expressing the trip temperature in millicelsius.
0125
0126 hysteresis:
0127 $ref: /schemas/types.yaml#/definitions/uint32
0128 description:
0129 An unsigned integer expressing the hysteresis delta with
0130 respect to the trip temperature property above, also in
0131 millicelsius. Any cooling action initiated by the framework is
0132 maintained until the temperature falls below
0133 (trip temperature - hysteresis). This potentially prevents a
0134 situation where the trip gets constantly triggered soon after
0135 cooling action is removed.
0136
0137 type:
0138 $ref: /schemas/types.yaml#/definitions/string
0139 enum:
0140 - active # enable active cooling e.g. fans
0141 - passive # enable passive cooling e.g. throttling cpu
0142 - hot # send notification to driver
0143 - critical # send notification to driver, trigger shutdown
0144 description: |
0145 There are four valid trip types: active, passive, hot,
0146 critical.
0147
0148 The critical trip type is used to set the maximum
0149 temperature threshold above which the HW becomes
0150 unstable and underlying firmware might even trigger a
0151 reboot. Hitting the critical threshold triggers a system
0152 shutdown.
0153
0154 The hot trip type can be used to send a notification to
0155 the thermal driver (if a .notify callback is registered).
0156 The action to be taken is left to the driver.
0157
0158 The passive trip type can be used to slow down HW e.g. run
0159 the CPU, GPU, bus at a lower frequency.
0160
0161 The active trip type can be used to control other HW to
0162 help in cooling e.g. fans can be sped up or slowed down
0163
0164 required:
0165 - temperature
0166 - hysteresis
0167 - type
0168 additionalProperties: false
0169
0170 additionalProperties: false
0171
0172 cooling-maps:
0173 type: object
0174 description:
0175 This node describes the action to be taken when a thermal zone
0176 crosses one of the temperature thresholds described in the trips
0177 node. The action takes the form of a mapping relation between a
0178 trip and the target cooling device state.
0179
0180 patternProperties:
0181 "^map[-a-zA-Z0-9]*$":
0182 type: object
0183
0184 properties:
0185 trip:
0186 $ref: /schemas/types.yaml#/definitions/phandle
0187 description:
0188 A phandle of a trip point node within this thermal zone.
0189
0190 cooling-device:
0191 $ref: /schemas/types.yaml#/definitions/phandle-array
0192 description:
0193 A list of cooling device phandles along with the minimum
0194 and maximum cooling state specifiers for each cooling
0195 device. Using the THERMAL_NO_LIMIT (-1UL) constant in the
0196 cooling-device phandle limit specifier lets the framework
0197 use the minimum and maximum cooling state for that cooling
0198 device automatically.
0199
0200 contribution:
0201 $ref: /schemas/types.yaml#/definitions/uint32
0202 description:
0203 The cooling contribution to the thermal zone of the referred
0204 cooling device at the referred trip point. The contribution is
0205 a ratio of the sum of all cooling contributions within a
0206 thermal zone.
0207
0208 required:
0209 - trip
0210 - cooling-device
0211 additionalProperties: false
0212
0213 required:
0214 - polling-delay
0215 - polling-delay-passive
0216 - thermal-sensors
0217 - trips
0218
0219 additionalProperties: false
0220
0221 additionalProperties: false
0222
0223 examples:
0224 - |
0225 #include <dt-bindings/interrupt-controller/arm-gic.h>
0226 #include <dt-bindings/thermal/thermal.h>
0227
0228 // Example 1: SDM845 TSENS
0229 soc {
0230 #address-cells = <2>;
0231 #size-cells = <2>;
0232
0233 /* ... */
0234
0235 tsens0: thermal-sensor@c263000 {
0236 compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
0237 reg = <0 0x0c263000 0 0x1ff>, /* TM */
0238 <0 0x0c222000 0 0x1ff>; /* SROT */
0239 #qcom,sensors = <13>;
0240 interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>,
0241 <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>;
0242 interrupt-names = "uplow", "critical";
0243 #thermal-sensor-cells = <1>;
0244 };
0245
0246 tsens1: thermal-sensor@c265000 {
0247 compatible = "qcom,sdm845-tsens", "qcom,tsens-v2";
0248 reg = <0 0x0c265000 0 0x1ff>, /* TM */
0249 <0 0x0c223000 0 0x1ff>; /* SROT */
0250 #qcom,sensors = <8>;
0251 interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>,
0252 <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>;
0253 interrupt-names = "uplow", "critical";
0254 #thermal-sensor-cells = <1>;
0255 };
0256 };
0257
0258 /* ... */
0259
0260 thermal-zones {
0261 cpu0-thermal {
0262 polling-delay-passive = <250>;
0263 polling-delay = <1000>;
0264
0265 thermal-sensors = <&tsens0 1>;
0266
0267 trips {
0268 cpu0_alert0: trip-point0 {
0269 temperature = <90000>;
0270 hysteresis = <2000>;
0271 type = "passive";
0272 };
0273
0274 cpu0_alert1: trip-point1 {
0275 temperature = <95000>;
0276 hysteresis = <2000>;
0277 type = "passive";
0278 };
0279
0280 cpu0_crit: cpu_crit {
0281 temperature = <110000>;
0282 hysteresis = <1000>;
0283 type = "critical";
0284 };
0285 };
0286
0287 cooling-maps {
0288 map0 {
0289 trip = <&cpu0_alert0>;
0290 /* Corresponds to 1400MHz in OPP table */
0291 cooling-device = <&CPU0 3 3>, <&CPU1 3 3>,
0292 <&CPU2 3 3>, <&CPU3 3 3>;
0293 };
0294
0295 map1 {
0296 trip = <&cpu0_alert1>;
0297 /* Corresponds to 1000MHz in OPP table */
0298 cooling-device = <&CPU0 5 5>, <&CPU1 5 5>,
0299 <&CPU2 5 5>, <&CPU3 5 5>;
0300 };
0301 };
0302 };
0303
0304 /* ... */
0305
0306 cluster0-thermal {
0307 polling-delay-passive = <250>;
0308 polling-delay = <1000>;
0309
0310 thermal-sensors = <&tsens0 5>;
0311
0312 trips {
0313 cluster0_alert0: trip-point0 {
0314 temperature = <90000>;
0315 hysteresis = <2000>;
0316 type = "hot";
0317 };
0318 cluster0_crit: cluster0_crit {
0319 temperature = <110000>;
0320 hysteresis = <2000>;
0321 type = "critical";
0322 };
0323 };
0324 };
0325
0326 /* ... */
0327
0328 gpu-top-thermal {
0329 polling-delay-passive = <250>;
0330 polling-delay = <1000>;
0331
0332 thermal-sensors = <&tsens0 11>;
0333
0334 trips {
0335 gpu1_alert0: trip-point0 {
0336 temperature = <90000>;
0337 hysteresis = <2000>;
0338 type = "hot";
0339 };
0340 };
0341 };
0342 };
0343 ...
