About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / devicetree / bindings / thermal




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

1	* Thermal Framework Device Tree descriptor
2	
3	This file describes a generic binding to provide a way of
4	defining hardware thermal structure using device tree.
5	A thermal structure includes thermal zones and their components,
6	such as trip points, polling intervals, sensors and cooling devices
7	binding descriptors.
8	
9	The target of device tree thermal descriptors is to describe only
10	the hardware thermal aspects. The thermal device tree bindings are
11	not about how the system must control or which algorithm or policy
12	must be taken in place.
13	
14	There are five types of nodes involved to describe thermal bindings:
15	- thermal sensors: devices which may be used to take temperature
16	  measurements.
17	- cooling devices: devices which may be used to dissipate heat.
18	- trip points: describe key temperatures at which cooling is recommended. The
19	  set of points should be chosen based on hardware limits.
20	- cooling maps: used to describe links between trip points and cooling devices;
21	- thermal zones: used to describe thermal data within the hardware;
22	
23	The following is a description of each of these node types.
24	
25	* Thermal sensor devices
26	
27	Thermal sensor devices are nodes providing temperature sensing capabilities on
28	thermal zones. Typical devices are I2C ADC converters and bandgaps. These are
29	nodes providing temperature data to thermal zones. Thermal sensor devices may
30	control one or more internal sensors.
31	
32	Required property:
33	- #thermal-sensor-cells: Used to provide sensor device specific information
34	  Type: unsigned	 while referring to it. Typically 0 on thermal sensor
35	  Size: one cell	 nodes with only one sensor, and at least 1 on nodes
36				 with several internal sensors, in order
37				 to identify uniquely the sensor instances within
38				 the IC. See thermal zone binding for more details
39				 on how consumers refer to sensor devices.
40	
41	* Cooling device nodes
42	
43	Cooling devices are nodes providing control on power dissipation. There
44	are essentially two ways to provide control on power dissipation. First
45	is by means of regulating device performance, which is known as passive
46	cooling. A typical passive cooling is a CPU that has dynamic voltage and
47	frequency scaling (DVFS), and uses lower frequencies as cooling states.
48	Second is by means of activating devices in order to remove
49	the dissipated heat, which is known as active cooling, e.g. regulating
50	fan speeds. In both cases, cooling devices shall have a way to determine
51	the state of cooling in which the device is.
52	
53	Any cooling device has a range of cooling states (i.e. different levels
54	of heat dissipation). For example a fan's cooling states correspond to
55	the different fan speeds possible. Cooling states are referred to by
56	single unsigned integers, where larger numbers mean greater heat
57	dissipation. The precise set of cooling states associated with a device
58	(as referred to be the cooling-min-state and cooling-max-state
59	properties) should be defined in a particular device's binding.
60	For more examples of cooling devices, refer to the example sections below.
61	
62	Required properties:
63	- cooling-min-state:	An integer indicating the smallest
64	  Type: unsigned	cooling state accepted. Typically 0.
65	  Size: one cell
66	
67	- cooling-max-state:	An integer indicating the largest
68	  Type: unsigned	cooling state accepted.
69	  Size: one cell
70	
71	- #cooling-cells:	Used to provide cooling device specific information
72	  Type: unsigned	while referring to it. Must be at least 2, in order
73	  Size: one cell      	to specify minimum and maximum cooling state used
74				in the reference. The first cell is the minimum
75				cooling state requested and the second cell is
76				the maximum cooling state requested in the reference.
77				See Cooling device maps section below for more details
78				on how consumers refer to cooling devices.
79	
80	* Trip points
81	
82	The trip node is a node to describe a point in the temperature domain
83	in which the system takes an action. This node describes just the point,
84	not the action.
85	
86	Required properties:
87	- temperature:		An integer indicating the trip temperature level,
88	  Type: signed		in millicelsius.
89	  Size: one cell
90	
91	- hysteresis:		A low hysteresis value on temperature property (above).
92	  Type: unsigned	This is a relative value, in millicelsius.
93	  Size: one cell
94	
95	- type:			a string containing the trip type. Expected values are:
96		"active":	A trip point to enable active cooling
97		"passive":	A trip point to enable passive cooling
98		"hot":		A trip point to notify emergency
99		"critical":	Hardware not reliable.
100	  Type: string
101	
102	* Cooling device maps
103	
104	The cooling device maps node is a node to describe how cooling devices
105	get assigned to trip points of the zone. The cooling devices are expected
106	to be loaded in the target system.
107	
108	Required properties:
109	- cooling-device:	A phandle of a cooling device with its specifier,
110	  Type: phandle +	referring to which cooling device is used in this
111	    cooling specifier	binding. In the cooling specifier, the first cell
112				is the minimum cooling state and the second cell
113				is the maximum cooling state used in this map.
114	- trip:			A phandle of a trip point node within the same thermal
115	  Type: phandle of	zone.
116	   trip point node
117	
118	Optional property:
119	- contribution:		The cooling contribution to the thermal zone of the
120	  Type: unsigned	referred cooling device at the referred trip point.
121	  Size: one cell      	The contribution is a ratio of the sum
122				of all cooling contributions within a thermal zone.
123	
124	Note: Using the THERMAL_NO_LIMIT (-1UL) constant in the cooling-device phandle
125	limit specifier means:
126	(i)   - minimum state allowed for minimum cooling state used in the reference.
127	(ii)  - maximum state allowed for maximum cooling state used in the reference.
128	Refer to include/dt-bindings/thermal/thermal.h for definition of this constant.
129	
130	* Thermal zone nodes
131	
132	The thermal zone node is the node containing all the required info
133	for describing a thermal zone, including its cooling device bindings. The
134	thermal zone node must contain, apart from its own properties, one sub-node
135	containing trip nodes and one sub-node containing all the zone cooling maps.
136	
137	Required properties:
138	- polling-delay:	The maximum number of milliseconds to wait between polls
139	  Type: unsigned	when checking this thermal zone.
140	  Size: one cell
141	
142	- polling-delay-passive: The maximum number of milliseconds to wait
143	  Type: unsigned	between polls when performing passive cooling.
144	  Size: one cell
145	
146	- thermal-sensors:	A list of thermal sensor phandles and sensor specifier
147	  Type: list of 	used while monitoring the thermal zone.
148	  phandles + sensor
149	  specifier
150	
151	- trips:		A sub-node which is a container of only trip point nodes
152	  Type: sub-node	required to describe the thermal zone.
153	
154	- cooling-maps:		A sub-node which is a container of only cooling device
155	  Type: sub-node	map nodes, used to describe the relation between trips
156				and cooling devices.
157	
158	Optional property:
159	- coefficients:		An array of integers (one signed cell) containing
160	  Type: array		coefficients to compose a linear relation between
161	  Elem size: one cell	the sensors listed in the thermal-sensors property.
162	  Elem type: signed	Coefficients defaults to 1, in case this property
163				is not specified. A simple linear polynomial is used:
164				Z = c0 * x0 + c1 + x1 + ... + c(n-1) * x(n-1) + cn.
165	
166				The coefficients are ordered and they match with sensors
167				by means of sensor ID. Additional coefficients are
168				interpreted as constant offset.
169	
170	Note: The delay properties are bound to the maximum dT/dt (temperature
171	derivative over time) in two situations for a thermal zone:
172	(i)  - when passive cooling is activated (polling-delay-passive); and
173	(ii) - when the zone just needs to be monitored (polling-delay) or
174	when active cooling is activated.
175	
176	The maximum dT/dt is highly bound to hardware power consumption and dissipation
177	capability. The delays should be chosen to account for said max dT/dt,
178	such that a device does not cross several trip boundaries unexpectedly
179	between polls. Choosing the right polling delays shall avoid having the
180	device in temperature ranges that may damage the silicon structures and
181	reduce silicon lifetime.
182	
183	* The thermal-zones node
184	
185	The "thermal-zones" node is a container for all thermal zone nodes. It shall
186	contain only sub-nodes describing thermal zones as in the section
187	"Thermal zone nodes". The "thermal-zones" node appears under "/".
188	
189	* Examples
190	
191	Below are several examples on how to use thermal data descriptors
192	using device tree bindings:
193	
194	(a) - CPU thermal zone
195	
196	The CPU thermal zone example below describes how to setup one thermal zone
197	using one single sensor as temperature source and many cooling devices and
198	power dissipation control sources.
199	
200	#include <dt-bindings/thermal/thermal.h>
201	
202	cpus {
203		/*
204		 * Here is an example of describing a cooling device for a DVFS
205		 * capable CPU. The CPU node describes its four OPPs.
206		 * The cooling states possible are 0..3, and they are
207		 * used as OPP indexes. The minimum cooling state is 0, which means
208		 * all four OPPs can be available to the system. The maximum
209		 * cooling state is 3, which means only the lowest OPPs (198MHz@0.85V)
210		 * can be available in the system.
211		 */
212		cpu0: cpu@0 {
213			...
214			operating-points = <
215				/* kHz    uV */
216				970000  1200000
217				792000  1100000
218				396000  950000
219				198000  850000
220			>;
221			cooling-min-state = <0>;
222			cooling-max-state = <3>;
223			#cooling-cells = <2>; /* min followed by max */
224		};
225		...
226	};
227	
228	&i2c1 {
229		...
230		/*
231		 * A simple fan controller which supports 10 speeds of operation
232		 * (represented as 0-9).
233		 */
234		fan0: fan@0x48 {
235			...
236			cooling-min-state = <0>;
237			cooling-max-state = <9>;
238			#cooling-cells = <2>; /* min followed by max */
239		};
240	};
241	
242	ocp {
243		...
244		/*
245		 * A simple IC with a single bandgap temperature sensor.
246		 */
247		bandgap0: bandgap@0x0000ED00 {
248			...
249			#thermal-sensor-cells = <0>;
250		};
251	};
252	
253	thermal-zones {
254		cpu-thermal: cpu-thermal {
255			polling-delay-passive = <250>; /* milliseconds */
256			polling-delay = <1000>; /* milliseconds */
257	
258			thermal-sensors = <&bandgap0>;
259	
260			trips {
261				cpu-alert0: cpu-alert {
262					temperature = <90000>; /* millicelsius */
263					hysteresis = <2000>; /* millicelsius */
264					type = "active";
265				};
266				cpu-alert1: cpu-alert {
267					temperature = <100000>; /* millicelsius */
268					hysteresis = <2000>; /* millicelsius */
269					type = "passive";
270				};
271				cpu-crit: cpu-crit {
272					temperature = <125000>; /* millicelsius */
273					hysteresis = <2000>; /* millicelsius */
274					type = "critical";
275				};
276			};
277	
278			cooling-maps {
279				map0 {
280					trip = <&cpu-alert0>;
281					cooling-device = <&fan0 THERMAL_NO_LIMITS 4>;
282				};
283				map1 {
284					trip = <&cpu-alert1>;
285					cooling-device = <&fan0 5 THERMAL_NO_LIMITS>;
286				};
287				map2 {
288					trip = <&cpu-alert1>;
289					cooling-device =
290					    <&cpu0 THERMAL_NO_LIMITS THERMAL_NO_LIMITS>;
291				};
292			};
293		};
294	};
295	
296	In the example above, the ADC sensor (bandgap0) at address 0x0000ED00 is
297	used to monitor the zone 'cpu-thermal' using its sole sensor. A fan
298	device (fan0) is controlled via I2C bus 1, at address 0x48, and has ten
299	different cooling states 0-9. It is used to remove the heat out of
300	the thermal zone 'cpu-thermal' using its cooling states
301	from its minimum to 4, when it reaches trip point 'cpu-alert0'
302	at 90C, as an example of active cooling. The same cooling device is used at
303	'cpu-alert1', but from 5 to its maximum state. The cpu@0 device is also
304	linked to the same thermal zone, 'cpu-thermal', as a passive cooling device,
305	using all its cooling states at trip point 'cpu-alert1',
306	which is a trip point at 100C. On the thermal zone 'cpu-thermal', at the
307	temperature of 125C, represented by the trip point 'cpu-crit', the silicon
308	is not reliable anymore.
309	
310	(b) - IC with several internal sensors
311	
312	The example below describes how to deploy several thermal zones based off a
313	single sensor IC, assuming it has several internal sensors. This is a common
314	case on SoC designs with several internal IPs that may need different thermal
315	requirements, and thus may have their own sensor to monitor or detect internal
316	hotspots in their silicon.
317	
318	#include <dt-bindings/thermal/thermal.h>
319	
320	ocp {
321		...
322		/*
323		 * A simple IC with several bandgap temperature sensors.
324		 */
325		bandgap0: bandgap@0x0000ED00 {
326			...
327			#thermal-sensor-cells = <1>;
328		};
329	};
330	
331	thermal-zones {
332		cpu-thermal: cpu-thermal {
333			polling-delay-passive = <250>; /* milliseconds */
334			polling-delay = <1000>; /* milliseconds */
335	
336					/* sensor       ID */
337			thermal-sensors = <&bandgap0     0>;
338	
339			trips {
340				/* each zone within the SoC may have its own trips */
341				cpu-alert: cpu-alert {
342					temperature = <100000>; /* millicelsius */
343					hysteresis = <2000>; /* millicelsius */
344					type = "passive";
345				};
346				cpu-crit: cpu-crit {
347					temperature = <125000>; /* millicelsius */
348					hysteresis = <2000>; /* millicelsius */
349					type = "critical";
350				};
351			};
352	
353			cooling-maps {
354				/* each zone within the SoC may have its own cooling */
355				...
356			};
357		};
358	
359		gpu-thermal: gpu-thermal {
360			polling-delay-passive = <120>; /* milliseconds */
361			polling-delay = <1000>; /* milliseconds */
362	
363					/* sensor       ID */
364			thermal-sensors = <&bandgap0     1>;
365	
366			trips {
367				/* each zone within the SoC may have its own trips */
368				gpu-alert: gpu-alert {
369					temperature = <90000>; /* millicelsius */
370					hysteresis = <2000>; /* millicelsius */
371					type = "passive";
372				};
373				gpu-crit: gpu-crit {
374					temperature = <105000>; /* millicelsius */
375					hysteresis = <2000>; /* millicelsius */
376					type = "critical";
377				};
378			};
379	
380			cooling-maps {
381				/* each zone within the SoC may have its own cooling */
382				...
383			};
384		};
385	
386		dsp-thermal: dsp-thermal {
387			polling-delay-passive = <50>; /* milliseconds */
388			polling-delay = <1000>; /* milliseconds */
389	
390					/* sensor       ID */
391			thermal-sensors = <&bandgap0     2>;
392	
393			trips {
394				/* each zone within the SoC may have its own trips */
395				dsp-alert: gpu-alert {
396					temperature = <90000>; /* millicelsius */
397					hysteresis = <2000>; /* millicelsius */
398					type = "passive";
399				};
400				dsp-crit: gpu-crit {
401					temperature = <135000>; /* millicelsius */
402					hysteresis = <2000>; /* millicelsius */
403					type = "critical";
404				};
405			};
406	
407			cooling-maps {
408				/* each zone within the SoC may have its own cooling */
409				...
410			};
411		};
412	};
413	
414	In the example above, there is one bandgap IC which has the capability to
415	monitor three sensors. The hardware has been designed so that sensors are
416	placed on different places in the DIE to monitor different temperature
417	hotspots: one for CPU thermal zone, one for GPU thermal zone and the
418	other to monitor a DSP thermal zone.
419	
420	Thus, there is a need to assign each sensor provided by the bandgap IC
421	to different thermal zones. This is achieved by means of using the
422	#thermal-sensor-cells property and using the first cell of the sensor
423	specifier as sensor ID. In the example, then, <bandgap 0> is used to
424	monitor CPU thermal zone, <bandgap 1> is used to monitor GPU thermal
425	zone and <bandgap 2> is used to monitor DSP thermal zone. Each zone
426	may be uncorrelated, having its own dT/dt requirements, trips
427	and cooling maps.
428	
429	
430	(c) - Several sensors within one single thermal zone
431	
432	The example below illustrates how to use more than one sensor within
433	one thermal zone.
434	
435	#include <dt-bindings/thermal/thermal.h>
436	
437	&i2c1 {
438		...
439		/*
440		 * A simple IC with a single temperature sensor.
441		 */
442		adc: sensor@0x49 {
443			...
444			#thermal-sensor-cells = <0>;
445		};
446	};
447	
448	ocp {
449		...
450		/*
451		 * A simple IC with a single bandgap temperature sensor.
452		 */
453		bandgap0: bandgap@0x0000ED00 {
454			...
455			#thermal-sensor-cells = <0>;
456		};
457	};
458	
459	thermal-zones {
460		cpu-thermal: cpu-thermal {
461			polling-delay-passive = <250>; /* milliseconds */
462			polling-delay = <1000>; /* milliseconds */
463	
464			thermal-sensors = <&bandgap0>,	/* cpu */
465					  <&adc>;	/* pcb north */
466	
467			/* hotspot = 100 * bandgap - 120 * adc + 484 */
468			coefficients = 		<100	-120	484>;
469	
470			trips {
471				...
472			};
473	
474			cooling-maps {
475				...
476			};
477		};
478	};
479	
480	In some cases, there is a need to use more than one sensor to extrapolate
481	a thermal hotspot in the silicon. The above example illustrates this situation.
482	For instance, it may be the case that a sensor external to CPU IP may be placed
483	close to CPU hotspot and together with internal CPU sensor, it is used
484	to determine the hotspot. Assuming this is the case for the above example,
485	the hypothetical extrapolation rule would be:
486			hotspot = 100 * bandgap - 120 * adc + 484
487	
488	In other context, the same idea can be used to add fixed offset. For instance,
489	consider the hotspot extrapolation rule below:
490			hotspot = 1 * adc + 6000
491	
492	In the above equation, the hotspot is always 6C higher than what is read
493	from the ADC sensor. The binding would be then:
494	        thermal-sensors =  <&adc>;
495	
496			/* hotspot = 1 * adc + 6000 */
497		coefficients = 		<1	6000>;
498	
499	(d) - Board thermal
500	
501	The board thermal example below illustrates how to setup one thermal zone
502	with many sensors and many cooling devices.
503	
504	#include <dt-bindings/thermal/thermal.h>
505	
506	&i2c1 {
507		...
508		/*
509		 * An IC with several temperature sensor.
510		 */
511		adc-dummy: sensor@0x50 {
512			...
513			#thermal-sensor-cells = <1>; /* sensor internal ID */
514		};
515	};
516	
517	thermal-zones {
518		batt-thermal {
519			polling-delay-passive = <500>; /* milliseconds */
520			polling-delay = <2500>; /* milliseconds */
521	
522					/* sensor       ID */
523			thermal-sensors = <&adc-dummy     4>;
524	
525			trips {
526				...
527			};
528	
529			cooling-maps {
530				...
531			};
532		};
533	
534		board-thermal: board-thermal {
535			polling-delay-passive = <1000>; /* milliseconds */
536			polling-delay = <2500>; /* milliseconds */
537	
538					/* sensor       ID */
539			thermal-sensors = <&adc-dummy     0>, /* pcb top edge */
540					  <&adc-dummy     1>, /* lcd */
541					  <&adc-dymmy     2>; /* back cover */
542			/*
543			 * An array of coefficients describing the sensor
544			 * linear relation. E.g.:
545			 * z = c1*x1 + c2*x2 + c3*x3
546			 */
547			coefficients =		<1200	-345	890>;
548	
549			trips {
550				/* Trips are based on resulting linear equation */
551				cpu-trip: cpu-trip {
552					temperature = <60000>; /* millicelsius */
553					hysteresis = <2000>; /* millicelsius */
554					type = "passive";
555				};
556				gpu-trip: gpu-trip {
557					temperature = <55000>; /* millicelsius */
558					hysteresis = <2000>; /* millicelsius */
559					type = "passive";
560				}
561				lcd-trip: lcp-trip {
562					temperature = <53000>; /* millicelsius */
563					hysteresis = <2000>; /* millicelsius */
564					type = "passive";
565				};
566				crit-trip: crit-trip {
567					temperature = <68000>; /* millicelsius */
568					hysteresis = <2000>; /* millicelsius */
569					type = "critical";
570				};
571			};
572	
573			cooling-maps {
574				map0 {
575					trip = <&cpu-trip>;
576					cooling-device = <&cpu0 0 2>;
577					contribution = <55>;
578				};
579				map1 {
580					trip = <&gpu-trip>;
581					cooling-device = <&gpu0 0 2>;
582					contribution = <20>;
583				};
584				map2 {
585					trip = <&lcd-trip>;
586					cooling-device = <&lcd0 5 10>;
587					contribution = <15>;
588				};
589			};
590		};
591	};
592	
593	The above example is a mix of previous examples, a sensor IP with several internal
594	sensors used to monitor different zones, one of them is composed by several sensors and
595	with different cooling devices.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.