blob: 5d827ded34d1c8bc271bb278c2d990918e164e9b [file] [log] [blame]
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -03001 ThinkPad ACPI Extras Driver
Linus Torvalds1da177e2005-04-16 15:20:36 -07002
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -03003 Version 0.14
Henrique de Moraes Holschuh54ae1502007-04-24 11:48:12 -03004 April 21st, 2007
Linus Torvalds1da177e2005-04-16 15:20:36 -07005
6 Borislav Deianov <borislav@users.sf.net>
Henrique de Moraes Holschuh38f996e2007-03-23 17:33:59 -03007 Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Linus Torvalds1da177e2005-04-16 15:20:36 -07008 http://ibm-acpi.sf.net/
9
10
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -030011This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
12supports various features of these laptops which are accessible
13through the ACPI and ACPI EC framework, but not otherwise fully
14supported by the generic Linux ACPI drivers.
15
16This driver used to be named ibm-acpi until kernel 2.6.21 and release
170.13-20070314. It used to be in the drivers/acpi tree, but it was
18moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel
192.6.22, and release 0.14.
Linus Torvalds1da177e2005-04-16 15:20:36 -070020
21
22Status
23------
24
25The features currently supported are the following (see below for
26detailed description):
27
28 - Fn key combinations
29 - Bluetooth enable and disable
Henrique de Moraes Holschuh837ca6d2007-03-23 17:33:54 -030030 - video output switching, expansion control
Linus Torvalds1da177e2005-04-16 15:20:36 -070031 - ThinkLight on and off
32 - limited docking and undocking
33 - UltraBay eject
Borislav Deianov78f81cc2005-08-17 00:00:00 -040034 - CMOS control
35 - LED control
36 - ACPI sounds
37 - temperature sensors
38 - Experimental: embedded controller register dump
Stefan Schmidt24f7ff02006-09-22 12:19:15 +020039 - LCD brightness control
40 - Volume control
Henrique de Moraes Holschuhecf2a802007-04-27 22:00:09 -030041 - Fan control and monitoring: fan speed, fan enable/disable
Stefan Schmidt28b779d2006-09-22 12:19:16 +020042 - Experimental: WAN enable and disable
Linus Torvalds1da177e2005-04-16 15:20:36 -070043
44A compatibility table by model and feature is maintained on the web
45site, http://ibm-acpi.sf.net/. I appreciate any success or failure
46reports, especially if they add to or correct the compatibility table.
47Please include the following information in your report:
48
49 - ThinkPad model name
50 - a copy of your DSDT, from /proc/acpi/dsdt
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -030051 - a copy of the output of dmidecode, with serial numbers
52 and UUIDs masked off
Linus Torvalds1da177e2005-04-16 15:20:36 -070053 - which driver features work and which don't
54 - the observed behavior of non-working features
55
56Any other comments or patches are also more than welcome.
57
58
59Installation
60------------
61
62If you are compiling this driver as included in the Linux kernel
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -030063sources, simply enable the CONFIG_THINKPAD_ACPI option, and optionally
64enable the CONFIG_THINKPAD_ACPI_BAY option if you want the
65thinkpad-specific bay functionality.
Linus Torvalds1da177e2005-04-16 15:20:36 -070066
67Features
68--------
69
Henrique de Moraes Holschuh54ae1502007-04-24 11:48:12 -030070The driver exports two different interfaces to userspace, which can be
71used to access the features it provides. One is a legacy procfs-based
72interface, which will be removed at some time in the distant future.
73The other is a new sysfs-based interface which is not complete yet.
74
75The procfs interface creates the /proc/acpi/ibm directory. There is a
76file under that directory for each feature it supports. The procfs
77interface is mostly frozen, and will change very little if at all: it
78will not be extended to add any new functionality in the driver, instead
79all new functionality will be implemented on the sysfs interface.
80
81The sysfs interface tries to blend in the generic Linux sysfs subsystems
82and classes as much as possible. Since some of these subsystems are not
83yet ready or stabilized, it is expected that this interface will change,
84and any and all userspace programs must deal with it.
85
86
87Notes about the sysfs interface:
88
89Unlike what was done with the procfs interface, correctness when talking
90to the sysfs interfaces will be enforced, as will correctness in the
91thinkpad-acpi's implementation of sysfs interfaces.
92
93Also, any bugs in the thinkpad-acpi sysfs driver code or in the
94thinkpad-acpi's implementation of the sysfs interfaces will be fixed for
95maximum correctness, even if that means changing an interface in
96non-compatible ways. As these interfaces mature both in the kernel and
97in thinkpad-acpi, such changes should become quite rare.
98
99Applications interfacing to the thinkpad-acpi sysfs interfaces must
100follow all sysfs guidelines and correctly process all errors (the sysfs
101interface makes extensive use of errors). File descriptors and open /
102close operations to the sysfs inodes must also be properly implemented.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700103
Henrique de Moraes Holschuh176750d2007-04-24 11:48:13 -0300104The version of thinkpad-acpi's sysfs interface is exported by the driver
105as a driver attribute (see below).
106
107Sysfs driver attributes are on the driver's sysfs attribute space,
108for 2.6.20 this is /sys/bus/platform/drivers/thinkpad-acpi/.
109
110Sysfs device attributes are on the driver's sysfs attribute space,
111for 2.6.20 this is /sys/devices/platform/thinkpad-acpi/.
112
113Driver version
114--------------
115
116procfs: /proc/acpi/ibm/driver
117sysfs driver attribute: version
Linus Torvalds1da177e2005-04-16 15:20:36 -0700118
119The driver name and version. No commands can be written to this file.
120
Henrique de Moraes Holschuh176750d2007-04-24 11:48:13 -0300121Sysfs interface version
122-----------------------
123
124sysfs driver attribute: interface_version
125
126Version of the thinkpad-acpi sysfs interface, as an unsigned long
127(output in hex format: 0xAAAABBCC), where:
128 AAAA - major revision
129 BB - minor revision
130 CC - bugfix revision
131
132The sysfs interface version changelog for the driver can be found at the
133end of this document. Changes to the sysfs interface done by the kernel
134subsystems are not documented here, nor are they tracked by this
135attribute.
136
Henrique de Moraes Holschuh94b08712007-07-18 23:45:32 -0300137Changes to the thinkpad-acpi sysfs interface are only considered
138non-experimental when they are submitted to Linux mainline, at which
139point the changes in this interface are documented and interface_version
140may be updated. If you are using any thinkpad-acpi features not yet
141sent to mainline for merging, you do so on your own risk: these features
142may disappear, or be implemented in a different and incompatible way by
143the time they are merged in Linux mainline.
144
145Changes that are backwards-compatible by nature (e.g. the addition of
146attributes that do not change the way the other attributes work) do not
147always warrant an update of interface_version. Therefore, one must
148expect that an attribute might not be there, and deal with it properly
149(an attribute not being there *is* a valid way to make it clear that a
150feature is not available in sysfs).
151
Henrique de Moraes Holschuha0416422007-04-27 22:00:16 -0300152Hot keys
153--------
154
155procfs: /proc/acpi/ibm/hotkey
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -0300156sysfs device attribute: hotkey_*
Linus Torvalds1da177e2005-04-16 15:20:36 -0700157
Henrique de Moraes Holschuh1a343762007-07-18 23:45:36 -0300158In a ThinkPad, the ACPI HKEY handler is responsible for comunicating
159some important events and also keyboard hot key presses to the operating
160system. Enabling the hotkey functionality of thinkpad-acpi signals the
161firmware that such a driver is present, and modifies how the ThinkPad
162firmware will behave in many situations.
163
164When the hotkey feature is enabled and the hot key mask is set (see
165below), the various hot keys either generate ACPI events in the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700166following format:
167
168 ibm/hotkey HKEY 00000080 0000xxxx
169
Henrique de Moraes Holschuh1a343762007-07-18 23:45:36 -0300170or events over the input layer. The input layer support accepts the
171standard IOCTLs to remap the keycodes assigned to each hotkey.
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -0300172
173When the input device is open, the driver will suppress any ACPI hot key
174events that get translated into a meaningful input layer event, in order
175to avoid sending duplicate events to userspace. Hot keys that are
Henrique de Moraes Holschuh1a343762007-07-18 23:45:36 -0300176mapped to KEY_RESERVED in the keymap are not translated, and will always
177generate an ACPI ibm/hotkey HKEY event, and no input layer events.
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -0300178
Henrique de Moraes Holschuh1a343762007-07-18 23:45:36 -0300179The hot key bit mask allows some control over which hot keys generate
180events. If a key is "masked" (bit set to 0 in the mask), the firmware
181will handle it. If it is "unmasked", it signals the firmware that
182thinkpad-acpi would prefer to handle it, if the firmware would be so
183kind to allow it (and it often doesn't!).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700184
Henrique de Moraes Holschuh1a343762007-07-18 23:45:36 -0300185Not all bits in the mask can be modified. Not all bits that can be
186modified do anything. Not all hot keys can be individually controlled
187by the mask. Some models do not support the mask at all, and in those
188models, hot keys cannot be controlled individually. The behaviour of
189the mask is, therefore, higly dependent on the ThinkPad model.
Henrique de Moraes Holschuhae92bd12007-07-18 23:45:29 -0300190
Henrique de Moraes Holschuh1a343762007-07-18 23:45:36 -0300191Note that unmasking some keys prevents their default behavior. For
192example, if Fn+F5 is unmasked, that key will no longer enable/disable
193Bluetooth by itself.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700194
Henrique de Moraes Holschuh1a343762007-07-18 23:45:36 -0300195Note also that not all Fn key combinations are supported through ACPI.
196For example, on the X40, the brightness, volume and "Access IBM" buttons
197do not generate ACPI events even with this driver. They *can* be used
198through the "ThinkPad Buttons" utility, see http://www.nongnu.org/tpb/
Linus Torvalds1da177e2005-04-16 15:20:36 -0700199
Henrique de Moraes Holschuha0416422007-04-27 22:00:16 -0300200procfs notes:
201
202The following commands can be written to the /proc/acpi/ibm/hotkey file:
203
204 echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature
205 echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature
Henrique de Moraes Holschuhae92bd12007-07-18 23:45:29 -0300206 echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
207 echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
208 ... any other 8-hex-digit mask ...
Henrique de Moraes Holschuha0416422007-04-27 22:00:16 -0300209 echo reset > /proc/acpi/ibm/hotkey -- restore the original mask
210
211sysfs notes:
212
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -0300213 hotkey_bios_enabled:
Henrique de Moraes Holschuha0416422007-04-27 22:00:16 -0300214 Returns the status of the hot keys feature when
215 thinkpad-acpi was loaded. Upon module unload, the hot
216 key feature status will be restored to this value.
217
218 0: hot keys were disabled
Henrique de Moraes Holschuh1a343762007-07-18 23:45:36 -0300219 1: hot keys were enabled (unusual)
Henrique de Moraes Holschuha0416422007-04-27 22:00:16 -0300220
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -0300221 hotkey_bios_mask:
Henrique de Moraes Holschuha0416422007-04-27 22:00:16 -0300222 Returns the hot keys mask when thinkpad-acpi was loaded.
223 Upon module unload, the hot keys mask will be restored
224 to this value.
225
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -0300226 hotkey_enable:
Henrique de Moraes Holschuha0416422007-04-27 22:00:16 -0300227 Enables/disables the hot keys feature, and reports
228 current status of the hot keys feature.
229
230 0: disables the hot keys feature / feature disabled
231 1: enables the hot keys feature / feature enabled
232
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -0300233 hotkey_mask:
Henrique de Moraes Holschuh1a343762007-07-18 23:45:36 -0300234 bit mask to enable driver-handling and ACPI event
235 generation for each hot key (see above). Returns the
236 current status of the hot keys mask, and allows one to
237 modify it.
Henrique de Moraes Holschuha0416422007-04-27 22:00:16 -0300238
Henrique de Moraes Holschuh9b010de2007-07-18 23:45:30 -0300239 hotkey_all_mask:
240 bit mask that should enable event reporting for all
241 supported hot keys, when echoed to hotkey_mask above.
242 Unless you know which events need to be handled
243 passively (because the firmware *will* handle them
244 anyway), do *not* use hotkey_all_mask. Use
245 hotkey_recommended_mask, instead. You have been warned.
246
247 hotkey_recommended_mask:
248 bit mask that should enable event reporting for all
Henrique de Moraes Holschuh1a343762007-07-18 23:45:36 -0300249 supported hot keys, except those which are always
250 handled by the firmware anyway. Echo it to
251 hotkey_mask above, to use.
Henrique de Moraes Holschuh9b010de2007-07-18 23:45:30 -0300252
Henrique de Moraes Holschuh74941a62007-07-18 23:45:31 -0300253 hotkey_radio_sw:
254 if the ThinkPad has a hardware radio switch, this
255 attribute will read 0 if the switch is in the "radios
256 disabled" postition, and 1 if the switch is in the
257 "radios enabled" position.
258
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -0300259input layer notes:
260
261A Hot key is mapped to a single input layer EV_KEY event, possibly
262followed by an EV_MSC MSC_SCAN event that shall contain that key's scan
263code. An EV_SYN event will always be generated to mark the end of the
264event block.
265
266Do not use the EV_MSC MSC_SCAN events to process keys. They are to be
267used as a helper to remap keys, only. They are particularly useful when
268remapping KEY_UNKNOWN keys.
269
270The events are available in an input device, with the following id:
271
272 Bus: BUS_HOST
Henrique de Moraes Holschuhedf0e0e2007-07-18 23:45:44 -0300273 vendor: 0x1014 (PCI_VENDOR_ID_IBM) or
274 0x17aa (PCI_VENDOR_ID_LENOVO)
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -0300275 product: 0x5054 ("TP")
276 version: 0x4101
277
278The version will have its LSB incremented if the keymap changes in a
279backwards-compatible way. The MSB shall always be 0x41 for this input
280device. If the MSB is not 0x41, do not use the device as described in
281this section, as it is either something else (e.g. another input device
282exported by a thinkpad driver, such as HDAPS) or its functionality has
283been changed in a non-backwards compatible way.
284
285Adding other event types for other functionalities shall be considered a
286backwards-compatible change for this input device.
287
288Thinkpad-acpi Hot Key event map (version 0x4101):
289
290ACPI Scan
291event code Key Notes
292
2930x1001 0x00 FN+F1 -
Henrique de Moraes Holschuhedf0e0e2007-07-18 23:45:44 -03002940x1002 0x01 FN+F2 IBM: battery (rare)
295 Lenovo: Screen lock
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -0300296
Henrique de Moraes Holschuhedf0e0e2007-07-18 23:45:44 -03002970x1003 0x02 FN+F3 Many IBM models always report
298 this hot key, even with hot keys
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -0300299 disabled or with Fn+F3 masked
300 off
Henrique de Moraes Holschuhedf0e0e2007-07-18 23:45:44 -0300301 IBM: screen lock
302 Lenovo: battery
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -0300303
3040x1004 0x03 FN+F4 Sleep button (ACPI sleep button
305 semanthics, i.e. sleep-to-RAM).
306 It is always generate some kind
307 of event, either the hot key
308 event or a ACPI sleep button
309 event. The firmware may
310 refuse to generate further FN+F4
311 key presses until a S3 or S4 ACPI
312 sleep cycle is performed or some
313 time passes.
314
3150x1005 0x04 FN+F5 Radio. Enables/disables
316 the internal BlueTooth hardware
317 and W-WAN card if left in control
318 of the firmware. Does not affect
319 the WLAN card.
Henrique de Moraes Holschuhedf0e0e2007-07-18 23:45:44 -0300320 Should be used to turn on/off all
321 radios (bluetooth+W-WAN+WLAN),
322 really.
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -0300323
3240x1006 0x05 FN+F6 -
325
3260x1007 0x06 FN+F7 Video output cycle.
327 Do you feel lucky today?
328
Henrique de Moraes Holschuhedf0e0e2007-07-18 23:45:44 -03003290x1008 0x07 FN+F8 IBM: toggle screen expand
330 Lenovo: configure ultranav
331
3320x1009 0x08 FN+F9 -
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -0300333 .. .. ..
3340x100B 0x0A FN+F11 -
335
3360x100C 0x0B FN+F12 Sleep to disk. You are always
337 supposed to handle it yourself,
338 either through the ACPI event,
339 or through a hotkey event.
340 The firmware may refuse to
341 generate further FN+F4 key
342 press events until a S3 or S4
343 ACPI sleep cycle is performed,
344 or some time passes.
345
3460x100D 0x0C FN+BACKSPACE -
3470x100E 0x0D FN+INSERT -
3480x100F 0x0E FN+DELETE -
349
3500x1010 0x0F FN+HOME Brightness up. This key is
Henrique de Moraes Holschuhedf0e0e2007-07-18 23:45:44 -0300351 always handled by the firmware
352 in IBM ThinkPads, even when
353 unmasked. Just leave it alone.
354 For Lenovo ThinkPads with a new
355 BIOS, it has to be handled either
356 by the ACPI OSI, or by userspace.
3570x1011 0x10 FN+END Brightness down. See brightness
358 up for details.
359
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -03003600x1012 0x11 FN+PGUP Thinklight toggle. This key is
361 always handled by the firmware,
362 even when unmasked.
363
3640x1013 0x12 FN+PGDOWN -
365
3660x1014 0x13 FN+SPACE Zoom key
367
3680x1015 0x14 VOLUME UP Internal mixer volume up. This
369 key is always handled by the
370 firmware, even when unmasked.
Henrique de Moraes Holschuhedf0e0e2007-07-18 23:45:44 -0300371 NOTE: Lenovo seems to be changing
372 this.
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -03003730x1016 0x15 VOLUME DOWN Internal mixer volume up. This
374 key is always handled by the
375 firmware, even when unmasked.
Henrique de Moraes Holschuhedf0e0e2007-07-18 23:45:44 -0300376 NOTE: Lenovo seems to be changing
377 this.
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -03003780x1017 0x16 MUTE Mute internal mixer. This
379 key is always handled by the
380 firmware, even when unmasked.
381
3820x1018 0x17 THINKPAD Thinkpad/Access IBM/Lenovo key
383
3840x1019 0x18 unknown
385.. .. ..
3860x1020 0x1F unknown
387
388The ThinkPad firmware does not allow one to differentiate when most hot
389keys are pressed or released (either that, or we don't know how to, yet).
390For these keys, the driver generates a set of events for a key press and
391immediately issues the same set of events for a key release. It is
392unknown by the driver if the ThinkPad firmware triggered these events on
393hot key press or release, but the firmware will do it for either one, not
394both.
395
396If a key is mapped to KEY_RESERVED, it generates no input events at all,
397and it may generate a legacy thinkpad-acpi ACPI hotkey event.
398
399If a key is mapped to KEY_UNKNOWN, it generates an input event that
400includes an scan code, and it may also generate a legacy thinkpad-acpi
401ACPI hotkey event.
402
403If a key is mapped to anything else, it will only generate legacy
404thinkpad-acpi ACPI hotkey events if nobody has opened the input device.
405
Henrique de Moraes Holschuh6a38abb2007-07-18 23:45:35 -0300406Non hot-key ACPI HKEY event map:
4070x5001 Lid closed
4080x5002 Lid opened
4090x7000 Radio Switch may have changed state
410
Henrique de Moraes Holschuha0416422007-04-27 22:00:16 -0300411
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -0300412Bluetooth
413---------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700414
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -0300415procfs: /proc/acpi/ibm/bluetooth
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -0300416sysfs device attribute: bluetooth_enable
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -0300417
418This feature shows the presence and current state of a ThinkPad
419Bluetooth device in the internal ThinkPad CDC slot.
420
421Procfs notes:
422
423If Bluetooth is installed, the following commands can be used:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700424
425 echo enable > /proc/acpi/ibm/bluetooth
426 echo disable > /proc/acpi/ibm/bluetooth
427
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -0300428Sysfs notes:
429
430 If the Bluetooth CDC card is installed, it can be enabled /
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -0300431 disabled through the "bluetooth_enable" thinkpad-acpi device
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -0300432 attribute, and its current status can also be queried.
433
434 enable:
435 0: disables Bluetooth / Bluetooth is disabled
436 1: enables Bluetooth / Bluetooth is enabled.
437
438 Note: this interface will be probably be superseeded by the
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -0300439 generic rfkill class, so it is NOT to be considered stable yet.
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -0300440
Linus Torvalds1da177e2005-04-16 15:20:36 -0700441Video output control -- /proc/acpi/ibm/video
442--------------------------------------------
443
444This feature allows control over the devices used for video output -
445LCD, CRT or DVI (if available). The following commands are available:
446
447 echo lcd_enable > /proc/acpi/ibm/video
448 echo lcd_disable > /proc/acpi/ibm/video
449 echo crt_enable > /proc/acpi/ibm/video
450 echo crt_disable > /proc/acpi/ibm/video
451 echo dvi_enable > /proc/acpi/ibm/video
452 echo dvi_disable > /proc/acpi/ibm/video
453 echo auto_enable > /proc/acpi/ibm/video
454 echo auto_disable > /proc/acpi/ibm/video
455 echo expand_toggle > /proc/acpi/ibm/video
456 echo video_switch > /proc/acpi/ibm/video
457
458Each video output device can be enabled or disabled individually.
459Reading /proc/acpi/ibm/video shows the status of each device.
460
461Automatic video switching can be enabled or disabled. When automatic
462video switching is enabled, certain events (e.g. opening the lid,
463docking or undocking) cause the video output device to change
464automatically. While this can be useful, it also causes flickering
465and, on the X40, video corruption. By disabling automatic switching,
466the flickering or video corruption can be avoided.
467
468The video_switch command cycles through the available video outputs
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400469(it simulates the behavior of Fn-F7).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700470
471Video expansion can be toggled through this feature. This controls
472whether the display is expanded to fill the entire LCD screen when a
473mode with less than full resolution is used. Note that the current
474video expansion status cannot be determined through this feature.
475
476Note that on many models (particularly those using Radeon graphics
477chips) the X driver configures the video card in a way which prevents
478Fn-F7 from working. This also disables the video output switching
479features of this driver, as it uses the same ACPI methods as
480Fn-F7. Video switching on the console should still work.
481
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400482UPDATE: There's now a patch for the X.org Radeon driver which
483addresses this issue. Some people are reporting success with the patch
484while others are still having problems. For more information:
485
486https://bugs.freedesktop.org/show_bug.cgi?id=2000
487
Linus Torvalds1da177e2005-04-16 15:20:36 -0700488ThinkLight control -- /proc/acpi/ibm/light
489------------------------------------------
490
491The current status of the ThinkLight can be found in this file. A few
492models which do not make the status available will show it as
493"unknown". The available commands are:
494
495 echo on > /proc/acpi/ibm/light
496 echo off > /proc/acpi/ibm/light
497
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400498Docking / undocking -- /proc/acpi/ibm/dock
Linus Torvalds1da177e2005-04-16 15:20:36 -0700499------------------------------------------
500
501Docking and undocking (e.g. with the X4 UltraBase) requires some
502actions to be taken by the operating system to safely make or break
503the electrical connections with the dock.
504
505The docking feature of this driver generates the following ACPI events:
506
507 ibm/dock GDCK 00000003 00000001 -- eject request
508 ibm/dock GDCK 00000003 00000002 -- undocked
509 ibm/dock GDCK 00000000 00000003 -- docked
510
511NOTE: These events will only be generated if the laptop was docked
512when originally booted. This is due to the current lack of support for
513hot plugging of devices in the Linux ACPI framework. If the laptop was
514booted while not in the dock, the following message is shown in the
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400515logs:
516
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -0300517 Mar 17 01:42:34 aero kernel: thinkpad_acpi: dock device not present
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400518
519In this case, no dock-related events are generated but the dock and
520undock commands described below still work. They can be executed
521manually or triggered by Fn key combinations (see the example acpid
522configuration files included in the driver tarball package available
523on the web site).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700524
525When the eject request button on the dock is pressed, the first event
526above is generated. The handler for this event should issue the
527following command:
528
529 echo undock > /proc/acpi/ibm/dock
530
531After the LED on the dock goes off, it is safe to eject the laptop.
532Note: if you pressed this key by mistake, go ahead and eject the
533laptop, then dock it back in. Otherwise, the dock may not function as
534expected.
535
536When the laptop is docked, the third event above is generated. The
537handler for this event should issue the following command to fully
538enable the dock:
539
540 echo dock > /proc/acpi/ibm/dock
541
542The contents of the /proc/acpi/ibm/dock file shows the current status
543of the dock, as provided by the ACPI framework.
544
545The docking support in this driver does not take care of enabling or
546disabling any other devices you may have attached to the dock. For
547example, a CD drive plugged into the UltraBase needs to be disabled or
548enabled separately. See the provided example acpid configuration files
549for how this can be accomplished.
550
551There is no support yet for PCI devices that may be attached to a
552docking station, e.g. in the ThinkPad Dock II. The driver currently
553does not recognize, enable or disable such devices. This means that
554the only docking stations currently supported are the X-series
555UltraBase docks and "dumb" port replicators like the Mini Dock (the
556latter don't need any ACPI support, actually).
557
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400558UltraBay eject -- /proc/acpi/ibm/bay
Linus Torvalds1da177e2005-04-16 15:20:36 -0700559------------------------------------
560
561Inserting or ejecting an UltraBay device requires some actions to be
562taken by the operating system to safely make or break the electrical
563connections with the device.
564
565This feature generates the following ACPI events:
566
567 ibm/bay MSTR 00000003 00000000 -- eject request
568 ibm/bay MSTR 00000001 00000000 -- eject lever inserted
569
570NOTE: These events will only be generated if the UltraBay was present
571when the laptop was originally booted (on the X series, the UltraBay
572is in the dock, so it may not be present if the laptop was undocked).
573This is due to the current lack of support for hot plugging of devices
574in the Linux ACPI framework. If the laptop was booted without the
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400575UltraBay, the following message is shown in the logs:
576
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -0300577 Mar 17 01:42:34 aero kernel: thinkpad_acpi: bay device not present
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400578
579In this case, no bay-related events are generated but the eject
Linus Torvalds1da177e2005-04-16 15:20:36 -0700580command described below still works. It can be executed manually or
581triggered by a hot key combination.
582
583Sliding the eject lever generates the first event shown above. The
584handler for this event should take whatever actions are necessary to
585shut down the device in the UltraBay (e.g. call idectl), then issue
586the following command:
587
588 echo eject > /proc/acpi/ibm/bay
589
590After the LED on the UltraBay goes off, it is safe to pull out the
591device.
592
593When the eject lever is inserted, the second event above is
594generated. The handler for this event should take whatever actions are
595necessary to enable the UltraBay device (e.g. call idectl).
596
597The contents of the /proc/acpi/ibm/bay file shows the current status
598of the UltraBay, as provided by the ACPI framework.
599
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400600EXPERIMENTAL warm eject support on the 600e/x, A22p and A3x (To use
601this feature, you need to supply the experimental=1 parameter when
602loading the module):
Linus Torvalds1da177e2005-04-16 15:20:36 -0700603
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400604These models do not have a button near the UltraBay device to request
605a hot eject but rather require the laptop to be put to sleep
606(suspend-to-ram) before the bay device is ejected or inserted).
607The sequence of steps to eject the device is as follows:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700608
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400609 echo eject > /proc/acpi/ibm/bay
610 put the ThinkPad to sleep
611 remove the drive
612 resume from sleep
613 cat /proc/acpi/ibm/bay should show that the drive was removed
614
615On the A3x, both the UltraBay 2000 and UltraBay Plus devices are
616supported. Use "eject2" instead of "eject" for the second bay.
617
618Note: the UltraBay eject support on the 600e/x, A22p and A3x is
619EXPERIMENTAL and may not work as expected. USE WITH CAUTION!
620
Henrique de Moraes Holschuhb6160042007-04-24 11:48:19 -0300621CMOS control
622------------
623
624procfs: /proc/acpi/ibm/cmos
625sysfs device attribute: cmos_command
Linus Torvalds1da177e2005-04-16 15:20:36 -0700626
Henrique de Moraes Holschuhd54b7d72007-07-18 23:45:33 -0300627This feature is mostly used internally by the ACPI firmware to keep the legacy
628CMOS NVRAM bits in sync with the current machine state, and to record this
629state so that the ThinkPad will retain such settings across reboots.
630
631Some of these commands actually perform actions in some ThinkPad models, but
632this is expected to disappear more and more in newer models. As an example, in
633a T43 and in a X40, commands 12 and 13 still control the ThinkLight state for
634real, but commands 0 to 2 don't control the mixer anymore (they have been
635phased out) and just update the NVRAM.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700636
Henrique de Moraes Holschuhb6160042007-04-24 11:48:19 -0300637The range of valid cmos command numbers is 0 to 21, but not all have an
638effect and the behavior varies from model to model. Here is the behavior
639on the X40 (tpb is the ThinkPad Buttons utility):
Linus Torvalds1da177e2005-04-16 15:20:36 -0700640
Henrique de Moraes Holschuhd54b7d72007-07-18 23:45:33 -0300641 0 - Related to "Volume down" key press
642 1 - Related to "Volume up" key press
643 2 - Related to "Mute on" key press
644 3 - Related to "Access IBM" key press
645 4 - Related to "LCD brightness up" key pess
646 5 - Related to "LCD brightness down" key press
647 11 - Related to "toggle screen expansion" key press/function
648 12 - Related to "ThinkLight on"
649 13 - Related to "ThinkLight off"
650 14 - Related to "ThinkLight" key press (toggle thinklight)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700651
Henrique de Moraes Holschuhb6160042007-04-24 11:48:19 -0300652The cmos command interface is prone to firmware split-brain problems, as
Henrique de Moraes Holschuhd54b7d72007-07-18 23:45:33 -0300653in newer ThinkPads it is just a compatibility layer. Do not use it, it is
654exported just as a debug tool.
Henrique de Moraes Holschuhb6160042007-04-24 11:48:19 -0300655
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400656LED control -- /proc/acpi/ibm/led
657---------------------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700658
659Some of the LED indicators can be controlled through this feature. The
660available commands are:
661
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400662 echo '<led number> on' >/proc/acpi/ibm/led
663 echo '<led number> off' >/proc/acpi/ibm/led
664 echo '<led number> blink' >/proc/acpi/ibm/led
Linus Torvalds1da177e2005-04-16 15:20:36 -0700665
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400666The <led number> range is 0 to 7. The set of LEDs that can be
667controlled varies from model to model. Here is the mapping on the X40:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700668
669 0 - power
670 1 - battery (orange)
671 2 - battery (green)
672 3 - UltraBase
673 4 - UltraBay
674 7 - standby
675
676All of the above can be turned on and off and can be made to blink.
677
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400678ACPI sounds -- /proc/acpi/ibm/beep
679----------------------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700680
681The BEEP method is used internally by the ACPI firmware to provide
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400682audible alerts in various situations. This feature allows the same
Linus Torvalds1da177e2005-04-16 15:20:36 -0700683sounds to be triggered manually.
684
685The commands are non-negative integer numbers:
686
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400687 echo <number> >/proc/acpi/ibm/beep
Linus Torvalds1da177e2005-04-16 15:20:36 -0700688
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400689The valid <number> range is 0 to 17. Not all numbers trigger sounds
690and the sounds vary from model to model. Here is the behavior on the
691X40:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700692
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400693 0 - stop a sound in progress (but use 17 to stop 16)
694 2 - two beeps, pause, third beep ("low battery")
Linus Torvalds1da177e2005-04-16 15:20:36 -0700695 3 - single beep
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400696 4 - high, followed by low-pitched beep ("unable")
Linus Torvalds1da177e2005-04-16 15:20:36 -0700697 5 - single beep
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400698 6 - very high, followed by high-pitched beep ("AC/DC")
Linus Torvalds1da177e2005-04-16 15:20:36 -0700699 7 - high-pitched beep
700 9 - three short beeps
701 10 - very long beep
702 12 - low-pitched beep
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400703 15 - three high-pitched beeps repeating constantly, stop with 0
704 16 - one medium-pitched beep repeating constantly, stop with 17
705 17 - stop 16
Linus Torvalds1da177e2005-04-16 15:20:36 -0700706
Henrique de Moraes Holschuh2c37aa42007-04-24 11:48:16 -0300707Temperature sensors
708-------------------
709
710procfs: /proc/acpi/ibm/thermal
711sysfs device attributes: (hwmon) temp*_input
Linus Torvalds1da177e2005-04-16 15:20:36 -0700712
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400713Most ThinkPads include six or more separate temperature sensors but
714only expose the CPU temperature through the standard ACPI methods.
Henrique de Moraes Holschuh60eb0b32006-11-24 11:47:08 -0200715This feature shows readings from up to eight different sensors on older
716ThinkPads, and it has experimental support for up to sixteen different
Henrique de Moraes Holschuh2c37aa42007-04-24 11:48:16 -0300717sensors on newer ThinkPads.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400718
Henrique de Moraes Holschuh60eb0b32006-11-24 11:47:08 -0200719EXPERIMENTAL: The 16-sensors feature is marked EXPERIMENTAL because the
720implementation directly accesses hardware registers and may not work as
721expected. USE WITH CAUTION! To use this feature, you need to supply the
722experimental=1 parameter when loading the module. When EXPERIMENTAL
723mode is enabled, reading the first 8 sensors on newer ThinkPads will
724also use an new experimental thermal sensor access mode.
725
726For example, on the X40, a typical output may be:
727temperatures: 42 42 45 41 36 -128 33 -128
728
729EXPERIMENTAL: On the T43/p, a typical output may be:
730temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
731
732The mapping of thermal sensors to physical locations varies depending on
733system-board model (and thus, on ThinkPad model).
734
735http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that
736tries to track down these locations for various models.
737
738Most (newer?) models seem to follow this pattern:
739
7401: CPU
7412: (depends on model)
7423: (depends on model)
7434: GPU
7445: Main battery: main sensor
7456: Bay battery: main sensor
7467: Main battery: secondary sensor
7478: Bay battery: secondary sensor
7489-15: (depends on model)
749
750For the R51 (source: Thomas Gruber):
7512: Mini-PCI
7523: Internal HDD
753
754For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
755http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
7562: System board, left side (near PCMCIA slot), reported as HDAPS temp
7573: PCMCIA slot
7589: MCH (northbridge) to DRAM Bus
Henrique de Moraes Holschuhb8b26402007-07-18 23:45:28 -030075910: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
760 card, under touchpad
Henrique de Moraes Holschuh60eb0b32006-11-24 11:47:08 -020076111: Power regulator, underside of system board, below F2 key
762
Henrique de Moraes Holschuh88679a12006-11-24 11:47:09 -0200763The A31 has a very atypical layout for the thermal sensors
764(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
7651: CPU
7662: Main Battery: main sensor
7673: Power Converter
7684: Bay Battery: main sensor
7695: MCH (northbridge)
7706: PCMCIA/ambient
7717: Main Battery: secondary sensor
7728: Bay Battery: secondary sensor
773
Henrique de Moraes Holschuh60eb0b32006-11-24 11:47:08 -0200774
Henrique de Moraes Holschuh2c37aa42007-04-24 11:48:16 -0300775Procfs notes:
776 Readings from sensors that are not available return -128.
777 No commands can be written to this file.
778
779Sysfs notes:
780 Sensors that are not available return the ENXIO error. This
781 status may change at runtime, as there are hotplug thermal
782 sensors, like those inside the batteries and docks.
783
784 thinkpad-acpi thermal sensors are reported through the hwmon
785 subsystem, and follow all of the hwmon guidelines at
786 Documentation/hwmon.
787
788
Matt LaPlanted6bc8ac2006-10-03 22:54:15 +0200789EXPERIMENTAL: Embedded controller register dump -- /proc/acpi/ibm/ecdump
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400790------------------------------------------------------------------------
791
792This feature is marked EXPERIMENTAL because the implementation
793directly accesses hardware registers and may not work as expected. USE
794WITH CAUTION! To use this feature, you need to supply the
795experimental=1 parameter when loading the module.
796
797This feature dumps the values of 256 embedded controller
798registers. Values which have changed since the last time the registers
799were dumped are marked with a star:
800
Henrique de Moraes Holschuh837ca6d2007-03-23 17:33:54 -0300801[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400802EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f
803EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00
804EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00
805EC 0x20: 00 00 00 00 00 00 00 00 00 00 00 03 43 00 00 80
806EC 0x30: 01 07 1a 00 30 04 00 00 *85 00 00 10 00 50 00 00
807EC 0x40: 00 00 00 00 00 00 14 01 00 04 00 00 00 00 00 00
808EC 0x50: 00 c0 02 0d 00 01 01 02 02 03 03 03 03 *bc *02 *bc
809EC 0x60: *02 *bc *02 00 00 00 00 00 00 00 00 00 00 00 00 00
810EC 0x70: 00 00 00 00 00 12 30 40 *24 *26 *2c *27 *20 80 *1f 80
811EC 0x80: 00 00 00 06 *37 *0e 03 00 00 00 0e 07 00 00 00 00
812EC 0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
813EC 0xa0: *ff 09 ff 09 ff ff *64 00 *00 *00 *a2 41 *ff *ff *e0 00
814EC 0xb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
815EC 0xc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
816EC 0xd0: 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
817EC 0xe0: 00 00 00 00 00 00 00 00 11 20 49 04 24 06 55 03
818EC 0xf0: 31 55 48 54 35 38 57 57 08 2f 45 73 07 65 6c 1a
819
820This feature can be used to determine the register holding the fan
821speed on some models. To do that, do the following:
822
823 - make sure the battery is fully charged
824 - make sure the fan is running
825 - run 'cat /proc/acpi/ibm/ecdump' several times, once per second or so
826
827The first step makes sure various charging-related values don't
828vary. The second ensures that the fan-related values do vary, since
829the fan speed fluctuates a bit. The third will (hopefully) mark the
830fan register with a star:
831
Henrique de Moraes Holschuh837ca6d2007-03-23 17:33:54 -0300832[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400833EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f
834EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00
835EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00
836EC 0x20: 00 00 00 00 00 00 00 00 00 00 00 03 43 00 00 80
837EC 0x30: 01 07 1a 00 30 04 00 00 85 00 00 10 00 50 00 00
838EC 0x40: 00 00 00 00 00 00 14 01 00 04 00 00 00 00 00 00
839EC 0x50: 00 c0 02 0d 00 01 01 02 02 03 03 03 03 bc 02 bc
840EC 0x60: 02 bc 02 00 00 00 00 00 00 00 00 00 00 00 00 00
841EC 0x70: 00 00 00 00 00 12 30 40 24 27 2c 27 21 80 1f 80
842EC 0x80: 00 00 00 06 *be 0d 03 00 00 00 0e 07 00 00 00 00
843EC 0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
844EC 0xa0: ff 09 ff 09 ff ff 64 00 00 00 a2 41 ff ff e0 00
845EC 0xb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
846EC 0xc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
847EC 0xd0: 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
848EC 0xe0: 00 00 00 00 00 00 00 00 11 20 49 04 24 06 55 03
849EC 0xf0: 31 55 48 54 35 38 57 57 08 2f 45 73 07 65 6c 1a
850
851Another set of values that varies often is the temperature
852readings. Since temperatures don't change vary fast, you can take
853several quick dumps to eliminate them.
854
855You can use a similar method to figure out the meaning of other
856embedded controller registers - e.g. make sure nothing else changes
857except the charging or discharging battery to determine which
858registers contain the current battery capacity, etc. If you experiment
859with this, do send me your results (including some complete dumps with
860a description of the conditions when they were taken.)
861
Henrique de Moraes Holschuh7d5a0152007-04-24 11:48:20 -0300862LCD brightness control
863----------------------
864
865procfs: /proc/acpi/ibm/brightness
866sysfs backlight device "thinkpad_screen"
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400867
868This feature allows software control of the LCD brightness on ThinkPad
Henrique de Moraes Holschuh7d5a0152007-04-24 11:48:20 -0300869models which don't have a hardware brightness slider.
870
871It has some limitations: the LCD backlight cannot be actually turned on or off
872by this interface, and in many ThinkPad models, the "dim while on battery"
873functionality will be enabled by the BIOS when this interface is used, and
874cannot be controlled.
875
876The backlight control has eight levels, ranging from 0 to 7. Some of the
877levels may not be distinct.
878
Henrique de Moraes Holschuh24d3b772007-07-18 23:45:43 -0300879There are two interfaces to the firmware for brightness control, EC and CMOS.
880To select which one should be used, use the brightness_mode module parameter:
881brightness_mode=1 selects EC mode, brightness_mode=2 selects CMOS mode,
882brightness_mode=3 selects both EC and CMOS. The driver tries to autodetect
883which interface to use.
884
Henrique de Moraes Holschuh7d5a0152007-04-24 11:48:20 -0300885Procfs notes:
886
887 The available commands are:
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400888
889 echo up >/proc/acpi/ibm/brightness
890 echo down >/proc/acpi/ibm/brightness
891 echo 'level <level>' >/proc/acpi/ibm/brightness
892
Henrique de Moraes Holschuh7d5a0152007-04-24 11:48:20 -0300893Sysfs notes:
894
895The interface is implemented through the backlight sysfs class, which is poorly
896documented at this time.
897
898Locate the thinkpad_screen device under /sys/class/backlight, and inside it
899there will be the following attributes:
900
901 max_brightness:
902 Reads the maximum brightness the hardware can be set to.
903 The minimum is always zero.
904
905 actual_brightness:
906 Reads what brightness the screen is set to at this instant.
907
908 brightness:
909 Writes request the driver to change brightness to the given
910 value. Reads will tell you what brightness the driver is trying
911 to set the display to when "power" is set to zero and the display
912 has not been dimmed by a kernel power management event.
913
914 power:
915 power management mode, where 0 is "display on", and 1 to 3 will
916 dim the display backlight to brightness level 0 because
917 thinkpad-acpi cannot really turn the backlight off. Kernel
918 power management events can temporarily increase the current
919 power management level, i.e. they can dim the display.
920
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400921
Stefan Schmidt24f7ff02006-09-22 12:19:15 +0200922Volume control -- /proc/acpi/ibm/volume
923---------------------------------------
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400924
925This feature allows volume control on ThinkPad models which don't have
926a hardware volume knob. The available commands are:
927
928 echo up >/proc/acpi/ibm/volume
929 echo down >/proc/acpi/ibm/volume
930 echo mute >/proc/acpi/ibm/volume
931 echo 'level <level>' >/proc/acpi/ibm/volume
932
933The <level> number range is 0 to 15 although not all of them may be
934distinct. The unmute the volume after the mute command, use either the
935up or down command (the level command will not unmute the volume).
936The current volume level and mute state is shown in the file.
937
Henrique de Moraes Holschuhecf2a802007-04-27 22:00:09 -0300938Fan control and monitoring: fan speed, fan enable/disable
939---------------------------------------------------------
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300940
941procfs: /proc/acpi/ibm/fan
942sysfs device attributes: (hwmon) fan_input, pwm1, pwm1_enable
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400943
Henrique de Moraes Holschuhecf2a802007-04-27 22:00:09 -0300944NOTE NOTE NOTE: fan control operations are disabled by default for
945safety reasons. To enable them, the module parameter "fan_control=1"
946must be given to thinkpad-acpi.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400947
Henrique de Moraes Holschuha12095c2006-11-24 11:47:13 -0200948This feature attempts to show the current fan speed, control mode and
949other fan data that might be available. The speed is read directly
950from the hardware registers of the embedded controller. This is known
Henrique de Moraes Holschuhecf2a802007-04-27 22:00:09 -0300951to work on later R, T, X and Z series ThinkPads but may show a bogus
Henrique de Moraes Holschuha12095c2006-11-24 11:47:13 -0200952value on other models.
953
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300954Fan levels:
Henrique de Moraes Holschuha12095c2006-11-24 11:47:13 -0200955
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300956Most ThinkPad fans work in "levels" at the firmware interface. Level 0
957stops the fan. The higher the level, the higher the fan speed, although
958adjacent levels often map to the same fan speed. 7 is the highest
959level, where the fan reaches the maximum recommended speed.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400960
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300961Level "auto" means the EC changes the fan level according to some
962internal algorithm, usually based on readings from the thermal sensors.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400963
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300964There is also a "full-speed" level, also known as "disengaged" level.
965In this level, the EC disables the speed-locked closed-loop fan control,
966and drives the fan as fast as it can go, which might exceed hardware
967limits, so use this level with caution.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400968
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300969The fan usually ramps up or down slowly from one speed to another, and
970it is normal for the EC to take several seconds to react to fan
971commands. The full-speed level may take up to two minutes to ramp up to
972maximum speed, and in some ThinkPads, the tachometer readings go stale
973while the EC is transitioning to the full-speed level.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400974
Henrique de Moraes Holschuha12095c2006-11-24 11:47:13 -0200975WARNING WARNING WARNING: do not leave the fan disabled unless you are
976monitoring all of the temperature sensor readings and you are ready to
977enable it if necessary to avoid overheating.
978
979An enabled fan in level "auto" may stop spinning if the EC decides the
980ThinkPad is cool enough and doesn't need the extra airflow. This is
981normal, and the EC will spin the fan up if the varios thermal readings
982rise too much.
983
984On the X40, this seems to depend on the CPU and HDD temperatures.
985Specifically, the fan is turned on when either the CPU temperature
986climbs to 56 degrees or the HDD temperature climbs to 46 degrees. The
987fan is turned off when the CPU temperature drops to 49 degrees and the
988HDD temperature drops to 41 degrees. These thresholds cannot
989currently be controlled.
990
Henrique de Moraes Holschuha12095c2006-11-24 11:47:13 -0200991The ThinkPad's ACPI DSDT code will reprogram the fan on its own when
992certain conditions are met. It will override any fan programming done
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -0300993through thinkpad-acpi.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700994
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -0300995The thinkpad-acpi kernel driver can be programmed to revert the fan
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300996level to a safe setting if userspace does not issue one of the procfs
997fan commands: "enable", "disable", "level" or "watchdog", or if there
998are no writes to pwm1_enable (or to pwm1 *if and only if* pwm1_enable is
999set to 1, manual mode) within a configurable amount of time of up to
1000120 seconds. This functionality is called fan safety watchdog.
Henrique de Moraes Holschuh38f996e2007-03-23 17:33:59 -03001001
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001002Note that the watchdog timer stops after it enables the fan. It will be
1003rearmed again automatically (using the same interval) when one of the
1004above mentioned fan commands is received. The fan watchdog is,
1005therefore, not suitable to protect against fan mode changes made through
1006means other than the "enable", "disable", and "level" procfs fan
1007commands, or the hwmon fan control sysfs interface.
Henrique de Moraes Holschuh38f996e2007-03-23 17:33:59 -03001008
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001009Procfs notes:
Henrique de Moraes Holschuh38f996e2007-03-23 17:33:59 -03001010
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001011The fan may be enabled or disabled with the following commands:
1012
1013 echo enable >/proc/acpi/ibm/fan
1014 echo disable >/proc/acpi/ibm/fan
1015
1016Placing a fan on level 0 is the same as disabling it. Enabling a fan
1017will try to place it in a safe level if it is too slow or disabled.
1018
1019The fan level can be controlled with the command:
1020
1021 echo 'level <level>' > /proc/acpi/ibm/fan
1022
1023Where <level> is an integer from 0 to 7, or one of the words "auto" or
1024"full-speed" (without the quotes). Not all ThinkPads support the "auto"
1025and "full-speed" levels. The driver accepts "disengaged" as an alias for
1026"full-speed", and reports it as "disengaged" for backwards
1027compatibility.
1028
1029On the X31 and X40 (and ONLY on those models), the fan speed can be
1030controlled to a certain degree. Once the fan is running, it can be
1031forced to run faster or slower with the following command:
1032
1033 echo 'speed <speed>' > /proc/acpi/ibm/fan
1034
1035The sustainable range of fan speeds on the X40 appears to be from about
10363700 to about 7350. Values outside this range either do not have any
1037effect or the fan speed eventually settles somewhere in that range. The
1038fan cannot be stopped or started with this command. This functionality
1039is incomplete, and not available through the sysfs interface.
1040
1041To program the safety watchdog, use the "watchdog" command.
1042
1043 echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan
1044
1045If you want to disable the watchdog, use 0 as the interval.
1046
1047Sysfs notes:
1048
1049The sysfs interface follows the hwmon subsystem guidelines for the most
1050part, and the exception is the fan safety watchdog.
1051
Henrique de Moraes Holschuhb39fe582007-04-27 22:00:13 -03001052Writes to any of the sysfs attributes may return the EINVAL error if
1053that operation is not supported in a given ThinkPad or if the parameter
1054is out-of-bounds, and EPERM if it is forbidden. They may also return
1055EINTR (interrupted system call), and EIO (I/O error while trying to talk
1056to the firmware).
1057
1058Features not yet implemented by the driver return ENOSYS.
1059
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001060hwmon device attribute pwm1_enable:
1061 0: PWM offline (fan is set to full-speed mode)
1062 1: Manual PWM control (use pwm1 to set fan level)
1063 2: Hardware PWM control (EC "auto" mode)
1064 3: reserved (Software PWM control, not implemented yet)
1065
Henrique de Moraes Holschuhb39fe582007-04-27 22:00:13 -03001066 Modes 0 and 2 are not supported by all ThinkPads, and the
1067 driver is not always able to detect this. If it does know a
1068 mode is unsupported, it will return -EINVAL.
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001069
1070hwmon device attribute pwm1:
1071 Fan level, scaled from the firmware values of 0-7 to the hwmon
1072 scale of 0-255. 0 means fan stopped, 255 means highest normal
1073 speed (level 7).
1074
1075 This attribute only commands the fan if pmw1_enable is set to 1
1076 (manual PWM control).
1077
1078hwmon device attribute fan1_input:
1079 Fan tachometer reading, in RPM. May go stale on certain
1080 ThinkPads while the EC transitions the PWM to offline mode,
1081 which can take up to two minutes. May return rubbish on older
1082 ThinkPads.
1083
1084driver attribute fan_watchdog:
1085 Fan safety watchdog timer interval, in seconds. Minimum is
1086 1 second, maximum is 120 seconds. 0 disables the watchdog.
1087
1088To stop the fan: set pwm1 to zero, and pwm1_enable to 1.
1089
1090To start the fan in a safe mode: set pwm1_enable to 2. If that fails
Henrique de Moraes Holschuhb39fe582007-04-27 22:00:13 -03001091with EINVAL, try to set pwm1_enable to 1 and pwm1 to at least 128 (255
1092would be the safest choice, though).
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001093
Henrique de Moraes Holschuh38f996e2007-03-23 17:33:59 -03001094
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -03001095EXPERIMENTAL: WAN
1096-----------------
1097
1098procfs: /proc/acpi/ibm/wan
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -03001099sysfs device attribute: wwan_enable
Stefan Schmidt28b779d2006-09-22 12:19:16 +02001100
1101This feature is marked EXPERIMENTAL because the implementation
1102directly accesses hardware registers and may not work as expected. USE
1103WITH CAUTION! To use this feature, you need to supply the
1104experimental=1 parameter when loading the module.
1105
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -03001106This feature shows the presence and current state of a W-WAN (Sierra
1107Wireless EV-DO) device.
1108
1109It was tested on a Lenovo Thinkpad X60. It should probably work on other
1110Thinkpad models which come with this module installed.
1111
1112Procfs notes:
1113
1114If the W-WAN card is installed, the following commands can be used:
Stefan Schmidt28b779d2006-09-22 12:19:16 +02001115
1116 echo enable > /proc/acpi/ibm/wan
1117 echo disable > /proc/acpi/ibm/wan
1118
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -03001119Sysfs notes:
1120
1121 If the W-WAN card is installed, it can be enabled /
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -03001122 disabled through the "wwan_enable" thinkpad-acpi device
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -03001123 attribute, and its current status can also be queried.
1124
1125 enable:
1126 0: disables WWAN card / WWAN card is disabled
1127 1: enables WWAN card / WWAN card is enabled.
1128
1129 Note: this interface will be probably be superseeded by the
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -03001130 generic rfkill class, so it is NOT to be considered stable yet.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001131
Borislav Deianov78f81cc2005-08-17 00:00:00 -04001132Multiple Commands, Module Parameters
1133------------------------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -07001134
1135Multiple commands can be written to the proc files in one shot by
1136separating them with commas, for example:
1137
1138 echo enable,0xffff > /proc/acpi/ibm/hotkey
1139 echo lcd_disable,crt_enable > /proc/acpi/ibm/video
1140
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -03001141Commands can also be specified when loading the thinkpad-acpi module,
1142for example:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001143
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -03001144 modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
Linus Torvalds1da177e2005-04-16 15:20:36 -07001145
Henrique de Moraes Holschuh132ce092007-04-21 11:08:30 -03001146Enabling debugging output
1147-------------------------
1148
1149The module takes a debug paramater which can be used to selectively
1150enable various classes of debugging output, for example:
1151
1152 modprobe ibm_acpi debug=0xffff
1153
1154will enable all debugging output classes. It takes a bitmask, so
1155to enable more than one output class, just add their values.
1156
Henrique de Moraes Holschuhfe08bc42007-04-21 11:08:32 -03001157 Debug bitmask Description
1158 0x0001 Initialization and probing
1159 0x0002 Removal
1160
Henrique de Moraes Holschuh132ce092007-04-21 11:08:30 -03001161There is also a kernel build option to enable more debugging
1162information, which may be necessary to debug driver problems.
Henrique de Moraes Holschuh0dcef772007-04-21 11:08:34 -03001163
Henrique de Moraes Holschuh176750d2007-04-24 11:48:13 -03001164The level of debugging information output by the driver can be changed
1165at runtime through sysfs, using the driver attribute debug_level. The
1166attribute takes the same bitmask as the debug module parameter above.
1167
Henrique de Moraes Holschuh0dcef772007-04-21 11:08:34 -03001168Force loading of module
1169-----------------------
1170
1171If thinkpad-acpi refuses to detect your ThinkPad, you can try to specify
1172the module parameter force_load=1. Regardless of whether this works or
1173not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
Henrique de Moraes Holschuh176750d2007-04-24 11:48:13 -03001174
1175
1176Sysfs interface changelog:
1177
11780x000100: Initial sysfs support, as a single platform driver and
1179 device.
Henrique de Moraes Holschuh94b08712007-07-18 23:45:32 -030011800x000200: Hot key support for 32 hot keys, and radio slider switch
1181 support.
Henrique de Moraes Holschuh741553c2007-07-18 23:45:39 -030011820x010000: Hot keys are now handled by default over the input
1183 layer, the radio switch generates input event EV_RADIO,
1184 and the driver enables hot key handling by default in
1185 the firmware.