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 8title: Thermal zone 9 10maintainers: 11 - Daniel Lezcano <daniel.lezcano@linaro.org> 12 13description: | 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 40properties: 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 51patternProperties: 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 - thermal-sensors 232 - trips 233 234 additionalProperties: false 235 236additionalProperties: false 237 238examples: 239 - | 240 #include <dt-bindings/interrupt-controller/arm-gic.h> 241 #include <dt-bindings/thermal/thermal.h> 242 243 // Example 1: SDM845 TSENS 244 soc { 245 #address-cells = <2>; 246 #size-cells = <2>; 247 248 /* ... */ 249 250 tsens0: thermal-sensor@c263000 { 251 compatible = "qcom,sdm845-tsens", "qcom,tsens-v2"; 252 reg = <0 0x0c263000 0 0x1ff>, /* TM */ 253 <0 0x0c222000 0 0x1ff>; /* SROT */ 254 #qcom,sensors = <13>; 255 interrupts = <GIC_SPI 506 IRQ_TYPE_LEVEL_HIGH>, 256 <GIC_SPI 508 IRQ_TYPE_LEVEL_HIGH>; 257 interrupt-names = "uplow", "critical"; 258 #thermal-sensor-cells = <1>; 259 }; 260 261 tsens1: thermal-sensor@c265000 { 262 compatible = "qcom,sdm845-tsens", "qcom,tsens-v2"; 263 reg = <0 0x0c265000 0 0x1ff>, /* TM */ 264 <0 0x0c223000 0 0x1ff>; /* SROT */ 265 #qcom,sensors = <8>; 266 interrupts = <GIC_SPI 507 IRQ_TYPE_LEVEL_HIGH>, 267 <GIC_SPI 509 IRQ_TYPE_LEVEL_HIGH>; 268 interrupt-names = "uplow", "critical"; 269 #thermal-sensor-cells = <1>; 270 }; 271 }; 272 273 /* ... */ 274 275 thermal-zones { 276 cpu0-thermal { 277 polling-delay-passive = <250>; 278 polling-delay = <1000>; 279 280 thermal-sensors = <&tsens0 1>; 281 282 trips { 283 cpu0_alert0: trip-point0 { 284 temperature = <90000>; 285 hysteresis = <2000>; 286 type = "passive"; 287 }; 288 289 cpu0_alert1: trip-point1 { 290 temperature = <95000>; 291 hysteresis = <2000>; 292 type = "passive"; 293 }; 294 295 cpu0_crit: cpu_crit { 296 temperature = <110000>; 297 hysteresis = <1000>; 298 type = "critical"; 299 }; 300 }; 301 302 cooling-maps { 303 map0 { 304 trip = <&cpu0_alert0>; 305 /* Corresponds to 1400MHz in OPP table */ 306 cooling-device = <&CPU0 3 3>, <&CPU1 3 3>, 307 <&CPU2 3 3>, <&CPU3 3 3>; 308 }; 309 310 map1 { 311 trip = <&cpu0_alert1>; 312 /* Corresponds to 1000MHz in OPP table */ 313 cooling-device = <&CPU0 5 5>, <&CPU1 5 5>, 314 <&CPU2 5 5>, <&CPU3 5 5>; 315 }; 316 }; 317 }; 318 319 /* ... */ 320 321 cluster0-thermal { 322 polling-delay-passive = <250>; 323 polling-delay = <1000>; 324 325 thermal-sensors = <&tsens0 5>; 326 327 trips { 328 cluster0_alert0: trip-point0 { 329 temperature = <90000>; 330 hysteresis = <2000>; 331 type = "hot"; 332 }; 333 cluster0_crit: cluster0_crit { 334 temperature = <110000>; 335 hysteresis = <2000>; 336 type = "critical"; 337 }; 338 }; 339 }; 340 341 /* ... */ 342 343 gpu-top-thermal { 344 polling-delay-passive = <250>; 345 polling-delay = <1000>; 346 347 thermal-sensors = <&tsens0 11>; 348 349 trips { 350 gpu1_alert0: trip-point0 { 351 temperature = <90000>; 352 hysteresis = <2000>; 353 type = "hot"; 354 }; 355 }; 356 }; 357 }; 358... 359