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