blob: b61e46f449aa1e0bf376de21ddf2eec55c196a39 [file] [log] [blame]
Zhang Rui203d3d42008-01-17 15:51:08 +08001Generic Thermal Sysfs driver How To
Frans Pop38bb0842009-10-26 08:38:59 +01002===================================
Zhang Rui203d3d42008-01-17 15:51:08 +08003
4Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com>
5
6Updated: 2 January 2008
7
8Copyright (c) 2008 Intel Corporation
9
10
110. Introduction
12
Frans Pop38bb0842009-10-26 08:38:59 +010013The generic thermal sysfs provides a set of interfaces for thermal zone
14devices (sensors) and thermal cooling devices (fan, processor...) to register
15with the thermal management solution and to be a part of it.
Zhang Rui203d3d42008-01-17 15:51:08 +080016
Frans Pop38bb0842009-10-26 08:38:59 +010017This how-to focuses on enabling new thermal zone and cooling devices to
18participate in thermal management.
19This solution is platform independent and any type of thermal zone devices
20and cooling devices should be able to make use of the infrastructure.
Zhang Rui203d3d42008-01-17 15:51:08 +080021
Frans Pop38bb0842009-10-26 08:38:59 +010022The main task of the thermal sysfs driver is to expose thermal zone attributes
23as well as cooling device attributes to the user space.
24An intelligent thermal management application can make decisions based on
25inputs from thermal zone attributes (the current temperature and trip point
26temperature) and throttle appropriate devices.
Zhang Rui203d3d42008-01-17 15:51:08 +080027
28[0-*] denotes any positive number starting from 0
29[1-*] denotes any positive number starting from 1
30
311. thermal sysfs driver interface functions
32
331.1 thermal zone device interface
Frans Pop38bb0842009-10-26 08:38:59 +0100341.1.1 struct thermal_zone_device *thermal_zone_device_register(char *name,
35 int trips, void *devdata, struct thermal_zone_device_ops *ops)
Zhang Rui203d3d42008-01-17 15:51:08 +080036
Frans Pop38bb0842009-10-26 08:38:59 +010037 This interface function adds a new thermal zone device (sensor) to
38 /sys/class/thermal folder as thermal_zone[0-*]. It tries to bind all the
39 thermal cooling devices registered at the same time.
Zhang Rui203d3d42008-01-17 15:51:08 +080040
Frans Pop38bb0842009-10-26 08:38:59 +010041 name: the thermal zone name.
42 trips: the total number of trip points this thermal zone supports.
43 devdata: device private data
44 ops: thermal zone device call-backs.
45 .bind: bind the thermal zone device with a thermal cooling device.
46 .unbind: unbind the thermal zone device with a thermal cooling device.
47 .get_temp: get the current temperature of the thermal zone.
48 .get_mode: get the current mode (user/kernel) of the thermal zone.
49 - "kernel" means thermal management is done in kernel.
50 - "user" will prevent kernel thermal driver actions upon trip points
51 so that user applications can take charge of thermal management.
52 .set_mode: set the mode (user/kernel) of the thermal zone.
53 .get_trip_type: get the type of certain trip point.
54 .get_trip_temp: get the temperature above which the certain trip point
55 will be fired.
Zhang Rui203d3d42008-01-17 15:51:08 +080056
571.1.2 void thermal_zone_device_unregister(struct thermal_zone_device *tz)
58
Frans Pop38bb0842009-10-26 08:38:59 +010059 This interface function removes the thermal zone device.
60 It deletes the corresponding entry form /sys/class/thermal folder and
61 unbind all the thermal cooling devices it uses.
Zhang Rui203d3d42008-01-17 15:51:08 +080062
631.2 thermal cooling device interface
641.2.1 struct thermal_cooling_device *thermal_cooling_device_register(char *name,
Frans Pop38bb0842009-10-26 08:38:59 +010065 void *devdata, struct thermal_cooling_device_ops *)
Zhang Rui203d3d42008-01-17 15:51:08 +080066
Frans Pop38bb0842009-10-26 08:38:59 +010067 This interface function adds a new thermal cooling device (fan/processor/...)
68 to /sys/class/thermal/ folder as cooling_device[0-*]. It tries to bind itself
69 to all the thermal zone devices register at the same time.
70 name: the cooling device name.
71 devdata: device private data.
72 ops: thermal cooling devices call-backs.
73 .get_max_state: get the Maximum throttle state of the cooling device.
74 .get_cur_state: get the Current throttle state of the cooling device.
75 .set_cur_state: set the Current throttle state of the cooling device.
Zhang Rui203d3d42008-01-17 15:51:08 +080076
771.2.2 void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)
78
Frans Pop38bb0842009-10-26 08:38:59 +010079 This interface function remove the thermal cooling device.
80 It deletes the corresponding entry form /sys/class/thermal folder and
81 unbind itself from all the thermal zone devices using it.
Zhang Rui203d3d42008-01-17 15:51:08 +080082
831.3 interface for binding a thermal zone device with a thermal cooling device
841.3.1 int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz,
Frans Pop38bb0842009-10-26 08:38:59 +010085 int trip, struct thermal_cooling_device *cdev);
Zhang Rui203d3d42008-01-17 15:51:08 +080086
Frans Pop38bb0842009-10-26 08:38:59 +010087 This interface function bind a thermal cooling device to the certain trip
88 point of a thermal zone device.
89 This function is usually called in the thermal zone device .bind callback.
90 tz: the thermal zone device
91 cdev: thermal cooling device
92 trip: indicates which trip point the cooling devices is associated with
93 in this thermal zone.
Zhang Rui203d3d42008-01-17 15:51:08 +080094
951.3.2 int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
Frans Pop38bb0842009-10-26 08:38:59 +010096 int trip, struct thermal_cooling_device *cdev);
Zhang Rui203d3d42008-01-17 15:51:08 +080097
Frans Pop38bb0842009-10-26 08:38:59 +010098 This interface function unbind a thermal cooling device from the certain
99 trip point of a thermal zone device. This function is usually called in
100 the thermal zone device .unbind callback.
101 tz: the thermal zone device
102 cdev: thermal cooling device
103 trip: indicates which trip point the cooling devices is associated with
104 in this thermal zone.
Zhang Rui203d3d42008-01-17 15:51:08 +0800105
1062. sysfs attributes structure
107
108RO read only value
109RW read/write value
110
Zhang Ruie9ae7102008-04-22 08:50:09 +0800111Thermal sysfs attributes will be represented under /sys/class/thermal.
112Hwmon sysfs I/F extension is also available under /sys/class/hwmon
113if hwmon is compiled in or built as a module.
Zhang Rui203d3d42008-01-17 15:51:08 +0800114
115Thermal zone device sys I/F, created once it's registered:
Zhang Ruie9ae7102008-04-22 08:50:09 +0800116/sys/class/thermal/thermal_zone[0-*]:
Frans Pop38bb0842009-10-26 08:38:59 +0100117 |---type: Type of the thermal zone
118 |---temp: Current temperature
119 |---mode: Working mode of the thermal zone
120 |---trip_point_[0-*]_temp: Trip point temperature
121 |---trip_point_[0-*]_type: Trip point type
Zhang Rui203d3d42008-01-17 15:51:08 +0800122
123Thermal cooling device sys I/F, created once it's registered:
Zhang Ruie9ae7102008-04-22 08:50:09 +0800124/sys/class/thermal/cooling_device[0-*]:
Frans Pop38bb0842009-10-26 08:38:59 +0100125 |---type: Type of the cooling device(processor/fan/...)
126 |---max_state: Maximum cooling state of the cooling device
127 |---cur_state: Current cooling state of the cooling device
Zhang Rui203d3d42008-01-17 15:51:08 +0800128
129
Frans Pop38bb0842009-10-26 08:38:59 +0100130Then next two dynamic attributes are created/removed in pairs. They represent
131the relationship between a thermal zone and its associated cooling device.
132They are created/removed for each successful execution of
133thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device.
Zhang Rui203d3d42008-01-17 15:51:08 +0800134
Frans Pop38bb0842009-10-26 08:38:59 +0100135/sys/class/thermal/thermal_zone[0-*]:
136 |---cdev[0-*]: [0-*]th cooling device in current thermal zone
137 |---cdev[0-*]_trip_point: Trip point that cdev[0-*] is associated with
Zhang Rui203d3d42008-01-17 15:51:08 +0800138
Zhang Ruie9ae7102008-04-22 08:50:09 +0800139Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,
Frans Pop38bb0842009-10-26 08:38:59 +0100140the generic thermal driver also creates a hwmon sysfs I/F for each _type_
141of thermal zone device. E.g. the generic thermal driver registers one hwmon
142class device and build the associated hwmon sysfs I/F for all the registered
143ACPI thermal zones.
144
Zhang Ruie9ae7102008-04-22 08:50:09 +0800145/sys/class/hwmon/hwmon[0-*]:
Frans Pop38bb0842009-10-26 08:38:59 +0100146 |---name: The type of the thermal zone devices
147 |---temp[1-*]_input: The current temperature of thermal zone [1-*]
148 |---temp[1-*]_critical: The critical trip point of thermal zone [1-*]
149
Zhang Ruie9ae7102008-04-22 08:50:09 +0800150Please read Documentation/hwmon/sysfs-interface for additional information.
Zhang Rui203d3d42008-01-17 15:51:08 +0800151
152***************************
153* Thermal zone attributes *
154***************************
155
Frans Pop38bb0842009-10-26 08:38:59 +0100156type
157 Strings which represent the thermal zone type.
158 This is given by thermal zone driver as part of registration.
159 E.g: "acpitz" indicates it's an ACPI thermal device.
160 In order to keep it consistent with hwmon sys attribute; this should
161 be a short, lowercase string, not containing spaces nor dashes.
162 RO, Required
Zhang Rui203d3d42008-01-17 15:51:08 +0800163
Frans Pop38bb0842009-10-26 08:38:59 +0100164temp
165 Current temperature as reported by thermal zone (sensor).
166 Unit: millidegree Celsius
167 RO, Required
Zhang Rui203d3d42008-01-17 15:51:08 +0800168
Frans Pop38bb0842009-10-26 08:38:59 +0100169mode
170 One of the predefined values in [kernel, user].
171 This file gives information about the algorithm that is currently
172 managing the thermal zone. It can be either default kernel based
173 algorithm or user space application.
174 kernel = Thermal management in kernel thermal zone driver.
175 user = Preventing kernel thermal zone driver actions upon
176 trip points so that user application can take full
177 charge of the thermal management.
178 RW, Optional
Zhang Rui203d3d42008-01-17 15:51:08 +0800179
Frans Pop38bb0842009-10-26 08:38:59 +0100180trip_point_[0-*]_temp
181 The temperature above which trip point will be fired.
182 Unit: millidegree Celsius
183 RO, Optional
Zhang Rui203d3d42008-01-17 15:51:08 +0800184
Frans Pop38bb0842009-10-26 08:38:59 +0100185trip_point_[0-*]_type
186 Strings which indicate the type of the trip point.
187 E.g. it can be one of critical, hot, passive, active[0-*] for ACPI
188 thermal zone.
189 RO, Optional
Zhang Rui203d3d42008-01-17 15:51:08 +0800190
Frans Pop38bb0842009-10-26 08:38:59 +0100191cdev[0-*]
192 Sysfs link to the thermal cooling device node where the sys I/F
193 for cooling device throttling control represents.
194 RO, Optional
Zhang Rui203d3d42008-01-17 15:51:08 +0800195
Frans Pop38bb0842009-10-26 08:38:59 +0100196cdev[0-*]_trip_point
197 The trip point with which cdev[0-*] is associated in this thermal
198 zone; -1 means the cooling device is not associated with any trip
199 point.
200 RO, Optional
Zhang Rui203d3d42008-01-17 15:51:08 +0800201
Frans Pop29226ed2009-10-26 08:39:00 +0100202passive
203 Attribute is only present for zones in which the passive cooling
204 policy is not supported by native thermal driver. Default is zero
205 and can be set to a temperature (in millidegrees) to enable a
206 passive trip point for the zone. Activation is done by polling with
207 an interval of 1 second.
208 Unit: millidegrees Celsius
Frans Pop3d8e3ad2009-10-26 08:39:02 +0100209 Valid values: 0 (disabled) or greater than 1000
Frans Pop29226ed2009-10-26 08:39:00 +0100210 RW, Optional
211
Frans Pop38bb0842009-10-26 08:38:59 +0100212*****************************
213* Cooling device attributes *
214*****************************
Zhang Rui203d3d42008-01-17 15:51:08 +0800215
Frans Pop38bb0842009-10-26 08:38:59 +0100216type
217 String which represents the type of device, e.g:
218 - for generic ACPI: should be "Fan", "Processor" or "LCD"
219 - for memory controller device on intel_menlow platform:
220 should be "Memory controller".
221 RO, Required
Zhang Rui203d3d42008-01-17 15:51:08 +0800222
Frans Pop38bb0842009-10-26 08:38:59 +0100223max_state
224 The maximum permissible cooling state of this cooling device.
225 RO, Required
Zhang Rui203d3d42008-01-17 15:51:08 +0800226
Frans Pop38bb0842009-10-26 08:38:59 +0100227cur_state
228 The current cooling state of this cooling device.
229 The value can any integer numbers between 0 and max_state:
230 - cur_state == 0 means no cooling
231 - cur_state == max_state means the maximum cooling.
232 RW, Required
Zhang Rui203d3d42008-01-17 15:51:08 +0800233
2343. A simple implementation
235
Frans Pop38bb0842009-10-26 08:38:59 +0100236ACPI thermal zone may support multiple trip points like critical, hot,
237passive, active. If an ACPI thermal zone supports critical, passive,
238active[0] and active[1] at the same time, it may register itself as a
239thermal_zone_device (thermal_zone1) with 4 trip points in all.
240It has one processor and one fan, which are both registered as
241thermal_cooling_device.
242
243If the processor is listed in _PSL method, and the fan is listed in _AL0
244method, the sys I/F structure will be built like this:
Zhang Rui203d3d42008-01-17 15:51:08 +0800245
246/sys/class/thermal:
247
248|thermal_zone1:
Frans Pop38bb0842009-10-26 08:38:59 +0100249 |---type: acpitz
250 |---temp: 37000
251 |---mode: kernel
252 |---trip_point_0_temp: 100000
253 |---trip_point_0_type: critical
254 |---trip_point_1_temp: 80000
255 |---trip_point_1_type: passive
256 |---trip_point_2_temp: 70000
257 |---trip_point_2_type: active0
258 |---trip_point_3_temp: 60000
259 |---trip_point_3_type: active1
260 |---cdev0: --->/sys/class/thermal/cooling_device0
261 |---cdev0_trip_point: 1 /* cdev0 can be used for passive */
262 |---cdev1: --->/sys/class/thermal/cooling_device3
263 |---cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/
Zhang Rui203d3d42008-01-17 15:51:08 +0800264
265|cooling_device0:
Frans Pop38bb0842009-10-26 08:38:59 +0100266 |---type: Processor
267 |---max_state: 8
268 |---cur_state: 0
Zhang Rui203d3d42008-01-17 15:51:08 +0800269
270|cooling_device3:
Frans Pop38bb0842009-10-26 08:38:59 +0100271 |---type: Fan
272 |---max_state: 2
273 |---cur_state: 0
Zhang Ruie9ae7102008-04-22 08:50:09 +0800274
275/sys/class/hwmon:
276
277|hwmon0:
Frans Pop38bb0842009-10-26 08:38:59 +0100278 |---name: acpitz
279 |---temp1_input: 37000
280 |---temp1_crit: 100000
R.Durgadoss4cb18722010-10-27 03:33:29 +0530281
2824. Event Notification
283
284The framework includes a simple notification mechanism, in the form of a
285netlink event. Netlink socket initialization is done during the _init_
286of the framework. Drivers which intend to use the notification mechanism
287just need to call generate_netlink_event() with two arguments viz
288(originator, event). Typically the originator will be an integer assigned
289to a thermal_zone_device when it registers itself with the framework. The
290event will be one of:{THERMAL_AUX0, THERMAL_AUX1, THERMAL_CRITICAL,
291THERMAL_DEV_FAULT}. Notification can be sent when the current temperature
292crosses any of the configured thresholds.