1 ===================================
2 Generic Thermal Sysfs driver How To
3 ===================================
4
5 Written by Sujith Thomas <sujith.thomas@intel.c
6
7 Copyright (c) 2008 Intel Corporation
8
9
10 0. Introduction
11 ===============
12
13 The generic thermal sysfs provides a set of in
14 devices (sensors) and thermal cooling devices
15 with the thermal management solution and to be
16
17 This how-to focuses on enabling new thermal zo
18 participate in thermal management.
19 This solution is platform independent and any
20 and cooling devices should be able to make use
21
22 The main task of the thermal sysfs driver is t
23 as well as cooling device attributes to the us
24 An intelligent thermal management application
25 inputs from thermal zone attributes (the curre
26 temperature) and throttle appropriate devices.
27
28 - `[0-*]` denotes any positive number st
29 - `[1-*]` denotes any positive number st
30
31 1. thermal sysfs driver interface functions
32 ===========================================
33
34 1.1 thermal zone device interface
35 ---------------------------------
36
37 ::
38
39 struct thermal_zone_device *
40 thermal_zone_device_register_with_trip
41 const
42 int nu
43 const
44 const
45 unsign
46 unsign
47
48 This interface function adds a new thermal
49 /sys/class/thermal folder as `thermal_zone
50 thermal cooling devices registered to it a
51
52 type:
53 the thermal zone type.
54 trips:
55 the table of trip points for this ther
56 devdata:
57 device private data
58 ops:
59 thermal zone device call-backs.
60
61 .should_bind:
62 check whether or not a given c
63 a given trip point in this the
64 .get_temp:
65 get the current temperature of
66 .set_trips:
67 set the trip points window. Wh
68 is updated, the trip points im
69 current temperature are found.
70 .change_mode:
71 change the mode (enabled/disab
72 .set_trip_temp:
73 set the temperature of a given
74 .get_crit_temp:
75 get the critical temperature f
76 .set_emul_temp:
77 set the emulation temperature
78 different threshold temperatur
79 .get_trend:
80 get the trend of most recent z
81 .hot:
82 hot trip point crossing handle
83 .critical:
84 critical trip point crossing h
85 tzp:
86 thermal zone platform parameters.
87 passive_delay:
88 number of milliseconds to wait between
89 cooling.
90 polling_delay:
91 number of milliseconds to wait between
92 whether trip points have been crossed
93
94 ::
95
96 void thermal_zone_device_unregister(st
97
98 This interface function removes the therma
99 It deletes the corresponding entry from /s
100 unbinds all the thermal cooling devices it
101
102 ::
103
104 struct thermal_zone_device
105 *thermal_zone_of_sensor_register(st
106 void *data,
107 const struct t
108
109 This interface adds a new sensor to a
110 This function will search the list of
111 device tree and look for the zone that
112 pointed by dev->of_node as temperature
113 pointing to the sensor node, the senso
114 thermal zone device.
115
116 The parameters for this interface are:
117
118 dev:
119 Device node of sensor
120 dev->of_node.
121 sensor_id:
122 a sensor identifier, i
123 than one sensors
124 data:
125 a private pointer (own
126 passed back, when a te
127 ops:
128 `struct thermal_zone_o
129
130 ============== ======
131 get_temp a poin
132 sensor
133 callba
134 set_trips a poin
135 temper
136 left t
137 core v
138 get_trend a poin
139 sensor
140 set_emul_temp a poin
141 sensor
142 ============== ======
143
144 The thermal zone temperature is provid
145 pointer of thermal_zone_of_device_ops.
146 have the private pointer @data back.
147
148 It returns error pointer if fails othe
149 handle. Caller should check the return
150 whether success or not.
151
152 ::
153
154 void thermal_zone_of_sensor_unregi
155
156
157 This interface unregisters a sensor fr
158 successfully added by interface therma
159 This function removes the sensor callb
160 thermal zone device registered with th
161 interface. It will also silent the zon
162 get_trend() thermal zone device callba
163
164 ::
165
166 struct thermal_zone_device
167 *devm_thermal_zone_of_sensor_registe
168 int sensor_id,
169 void *data,
170 const struct t
171
172 This interface is resource managed ver
173 thermal_zone_of_sensor_register().
174
175 All details of thermal_zone_of_sensor_
176 section 1.1.3 is applicable here.
177
178 The benefit of using this interface to
179 is not require to explicitly call ther
180 in error path or during driver unbindi
181 resource manager.
182
183 ::
184
185 void devm_thermal_zone_of_sens
186
187
188 This interface is resource managed ver
189 thermal_zone_of_sensor_unregister().
190 All details of thermal_zone_of_sensor_
191 section 1.1.4 is applicable here.
192 Normally this function will not need t
193 management code will ensure that the r
194
195 ::
196
197 int thermal_zone_get_slope(str
198
199 This interface is used to read the slo
200 for the thermal zone device, which mig
201 drivers for temperature calculations.
202
203 ::
204
205 int thermal_zone_get_offset(st
206
207 This interface is used to read the off
208 for the thermal zone device, which mig
209 drivers for temperature calculations.
210
211 1.2 thermal cooling device interface
212 ------------------------------------
213
214
215 ::
216
217 struct thermal_cooling_device
218 *thermal_cooling_device_register(char
219 void *devdata, struct
220
221 This interface function adds a new thermal
222 to /sys/class/thermal/ folder as `cooling_
223 to all the thermal zone devices registered
224
225 name:
226 the cooling device name.
227 devdata:
228 device private data.
229 ops:
230 thermal cooling devices call-backs.
231
232 .get_max_state:
233 get the Maximum throttle state
234 .get_cur_state:
235 get the Currently requested th
236 cooling device.
237 .set_cur_state:
238 set the Current throttle state
239
240 ::
241
242 void thermal_cooling_device_unregister
243
244 This interface function removes the therma
245 It deletes the corresponding entry from /s
246 unbinds itself from all the thermal zone d
247
248 1.4 Thermal Zone Parameters
249 ---------------------------
250
251 ::
252
253 struct thermal_zone_params
254
255 This structure defines the platform level
256 This data, for each thermal zone should co
257 This is an optional feature where some pla
258 provide this data.
259
260 .governor_name:
261 Name of the thermal governor us
262 .no_hwmon:
263 a boolean to indicate if the th
264 is required. when no_hwmon == f
265 will be created. when no_hwmon
266 In case the thermal_zone_params
267 will be created (for backward c
268
269 2. sysfs attributes structure
270 =============================
271
272 == ================
273 RO read only value
274 WO write only value
275 RW read/write value
276 == ================
277
278 Thermal sysfs attributes will be represented u
279 Hwmon sysfs I/F extension is also available un
280 if hwmon is compiled in or built as a module.
281
282 Thermal zone device sys I/F, created once it's
283
284 /sys/class/thermal/thermal_zone[0-*]:
285 |---type: Type of the th
286 |---temp: Current temper
287 |---mode: Working mode o
288 |---policy: Thermal govern
289 |---available_policies: Available ther
290 |---trip_point_[0-*]_temp: Trip point tem
291 |---trip_point_[0-*]_type: Trip point typ
292 |---trip_point_[0-*]_hyst: Hysteresis val
293 |---emul_temp: Emulated tempe
294 |---sustainable_power: Sustainable di
295 |---k_po: Proportional t
296 |---k_pu: Proportional t
297 |---k_i: PID's integral
298 |---k_d: PID's derivati
299 |---integral_cutoff: Offset above w
300 |---slope: Slope constant
301 |---offset: Offset constan
302
303 Thermal cooling device sys I/F, created once i
304
305 /sys/class/thermal/cooling_device[0-*]:
306 |---type: Type of the co
307 |---max_state: Maximum coolin
308 |---cur_state: Current coolin
309 |---stats: Directory cont
310 |---stats/reset: Writing any va
311 |---stats/time_in_state_ms: Time (msec) sp
312 |---stats/total_trans: Total number o
313 |---stats/trans_table: Cooling state
314
315
316 Then next two dynamic attributes are created/r
317 the relationship between a thermal zone and it
318
319 ::
320
321 /sys/class/thermal/thermal_zone[0-*]:
322 |---cdev[0-*]: [0-*]th coolin
323 |---cdev[0-*]_trip_point: Trip point tha
324 |---cdev[0-*]_weight: Influence of t
325 this thermal z
326
327 Besides the thermal zone device sysfs I/F and
328 the generic thermal driver also creates a hwmo
329 of thermal zone device. E.g. the generic therm
330 class device and build the associated hwmon sy
331 ACPI thermal zones.
332
333 Please read Documentation/ABI/testing/sysfs-cl
334 zone and cooling device attribute details.
335
336 ::
337
338 /sys/class/hwmon/hwmon[0-*]:
339 |---name: The type of th
340 |---temp[1-*]_input: The current te
341 |---temp[1-*]_critical: The critical t
342
343 Please read Documentation/hwmon/sysfs-interfac
344
345 3. A simple implementation
346 ==========================
347
348 ACPI thermal zone may support multiple trip po
349 passive, active. If an ACPI thermal zone suppo
350 active[0] and active[1] at the same time, it m
351 thermal_zone_device (thermal_zone1) with 4 tri
352 It has one processor and one fan, which are bo
353 thermal_cooling_device. Both are considered to
354 effectiveness in cooling the thermal zone.
355
356 If the processor is listed in _PSL method, and
357 method, the sys I/F structure will be built li
358
359 /sys/class/thermal:
360 |thermal_zone1:
361 |---type: acpitz
362 |---temp: 37000
363 |---mode: enabled
364 |---policy: step_wise
365 |---available_policies: step_wise fair
366 |---trip_point_0_temp: 100000
367 |---trip_point_0_type: critical
368 |---trip_point_1_temp: 80000
369 |---trip_point_1_type: passive
370 |---trip_point_2_temp: 70000
371 |---trip_point_2_type: active0
372 |---trip_point_3_temp: 60000
373 |---trip_point_3_type: active1
374 |---cdev0: --->/sys/class
375 |---cdev0_trip_point: 1 /* cde
376 |---cdev0_weight: 1024
377 |---cdev1: --->/sys/class
378 |---cdev1_trip_point: 2 /* cde
379 |---cdev1_weight: 1024
380
381 |cooling_device0:
382 |---type: Processor
383 |---max_state: 8
384 |---cur_state: 0
385
386 |cooling_device3:
387 |---type: Fan
388 |---max_state: 2
389 |---cur_state: 0
390
391 /sys/class/hwmon:
392 |hwmon0:
393 |---name: acpitz
394 |---temp1_input: 37000
395 |---temp1_crit: 100000
396
397 4. Export Symbol APIs
398 =====================
399
400 4.1. get_tz_trend
401 -----------------
402
403 This function returns the trend of a thermal z
404 of temperature of the thermal zone. Ideally, t
405 are supposed to implement the callback. If the
406 framework calculated the trend by comparing th
407 temperature values.
408
409 4.2. thermal_cdev_update
410 ------------------------
411
412 This function serves as an arbitrator to set t
413 device. It sets the cooling device to the deep
414 possible.
415
416 5. thermal_emergency_poweroff
417 =============================
418
419 On an event of critical trip temperature cross
420 shuts down the system by calling hw_protection
421 hw_protection_shutdown() first attempts to per
422 but accepts a delay after which it proceeds do
423 or as last resort an emergency_restart.
424
425 The delay should be carefully profiled so as t
426 orderly poweroff.
427
428 If the delay is set to 0 emergency poweroff wi
429 carefully profiled non-zero positive value is
430 poweroff to be triggered.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.