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