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