blob: eb2f5986e1eb911e94c760c5107dccef5b053f76 [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 Holschuhc78d5c92007-07-18 23:45:47 -03003 Version 0.15
4 July 1st, 2007
Linus Torvalds1da177e2005-04-16 15:20:36 -07005
6 Borislav Deianov <borislav@users.sf.net>
Henrique de Moraes Holschuhc78d5c92007-07-18 23:45:47 -03007 Henrique de Moraes Holschuh <hmh@hmh.eng.br>
8 http://ibm-acpi.sf.net/
Linus Torvalds1da177e2005-04-16 15:20:36 -07009
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,
Henrique de Moraes Holschuh9de1cc42007-08-11 00:08:33 -0300108for 2.6.20 this is /sys/bus/platform/drivers/thinkpad_acpi/.
Henrique de Moraes Holschuh176750d2007-04-24 11:48:13 -0300109
110Sysfs device attributes are on the driver's sysfs attribute space,
Henrique de Moraes Holschuh9de1cc42007-08-11 00:08:33 -0300111for 2.6.20 this is /sys/devices/platform/thinkpad_acpi/.
Henrique de Moraes Holschuh176750d2007-04-24 11:48:13 -0300112
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
Henrique de Moraes Holschuh3d6f99c2007-07-18 23:45:46 -0300713Most ThinkPads include six or more separate temperature sensors but only
714expose the CPU temperature through the standard ACPI methods. This
715feature shows readings from up to eight different sensors on older
716ThinkPads, and up to sixteen different sensors on newer ThinkPads.
Henrique de Moraes Holschuh60eb0b32006-11-24 11:47:08 -0200717
718For example, on the X40, a typical output may be:
719temperatures: 42 42 45 41 36 -128 33 -128
720
Henrique de Moraes Holschuh3d6f99c2007-07-18 23:45:46 -0300721On the T43/p, a typical output may be:
Henrique de Moraes Holschuh60eb0b32006-11-24 11:47:08 -0200722temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
723
724The mapping of thermal sensors to physical locations varies depending on
725system-board model (and thus, on ThinkPad model).
726
727http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that
728tries to track down these locations for various models.
729
730Most (newer?) models seem to follow this pattern:
731
7321: CPU
7332: (depends on model)
7343: (depends on model)
7354: GPU
7365: Main battery: main sensor
7376: Bay battery: main sensor
7387: Main battery: secondary sensor
7398: Bay battery: secondary sensor
7409-15: (depends on model)
741
742For the R51 (source: Thomas Gruber):
7432: Mini-PCI
7443: Internal HDD
745
746For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
747http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
7482: System board, left side (near PCMCIA slot), reported as HDAPS temp
7493: PCMCIA slot
7509: MCH (northbridge) to DRAM Bus
Henrique de Moraes Holschuhb8b26402007-07-18 23:45:28 -030075110: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
752 card, under touchpad
Henrique de Moraes Holschuh60eb0b32006-11-24 11:47:08 -020075311: Power regulator, underside of system board, below F2 key
754
Henrique de Moraes Holschuh88679a12006-11-24 11:47:09 -0200755The A31 has a very atypical layout for the thermal sensors
756(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
7571: CPU
7582: Main Battery: main sensor
7593: Power Converter
7604: Bay Battery: main sensor
7615: MCH (northbridge)
7626: PCMCIA/ambient
7637: Main Battery: secondary sensor
7648: Bay Battery: secondary sensor
765
Henrique de Moraes Holschuh60eb0b32006-11-24 11:47:08 -0200766
Henrique de Moraes Holschuh2c37aa42007-04-24 11:48:16 -0300767Procfs notes:
768 Readings from sensors that are not available return -128.
769 No commands can be written to this file.
770
771Sysfs notes:
772 Sensors that are not available return the ENXIO error. This
773 status may change at runtime, as there are hotplug thermal
774 sensors, like those inside the batteries and docks.
775
776 thinkpad-acpi thermal sensors are reported through the hwmon
777 subsystem, and follow all of the hwmon guidelines at
778 Documentation/hwmon.
779
780
Matt LaPlanted6bc8ac2006-10-03 22:54:15 +0200781EXPERIMENTAL: Embedded controller register dump -- /proc/acpi/ibm/ecdump
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400782------------------------------------------------------------------------
783
784This feature is marked EXPERIMENTAL because the implementation
785directly accesses hardware registers and may not work as expected. USE
786WITH CAUTION! To use this feature, you need to supply the
787experimental=1 parameter when loading the module.
788
789This feature dumps the values of 256 embedded controller
790registers. Values which have changed since the last time the registers
791were dumped are marked with a star:
792
Henrique de Moraes Holschuh837ca6d2007-03-23 17:33:54 -0300793[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400794EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f
795EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00
796EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00
797EC 0x20: 00 00 00 00 00 00 00 00 00 00 00 03 43 00 00 80
798EC 0x30: 01 07 1a 00 30 04 00 00 *85 00 00 10 00 50 00 00
799EC 0x40: 00 00 00 00 00 00 14 01 00 04 00 00 00 00 00 00
800EC 0x50: 00 c0 02 0d 00 01 01 02 02 03 03 03 03 *bc *02 *bc
801EC 0x60: *02 *bc *02 00 00 00 00 00 00 00 00 00 00 00 00 00
802EC 0x70: 00 00 00 00 00 12 30 40 *24 *26 *2c *27 *20 80 *1f 80
803EC 0x80: 00 00 00 06 *37 *0e 03 00 00 00 0e 07 00 00 00 00
804EC 0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
805EC 0xa0: *ff 09 ff 09 ff ff *64 00 *00 *00 *a2 41 *ff *ff *e0 00
806EC 0xb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
807EC 0xc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
808EC 0xd0: 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
809EC 0xe0: 00 00 00 00 00 00 00 00 11 20 49 04 24 06 55 03
810EC 0xf0: 31 55 48 54 35 38 57 57 08 2f 45 73 07 65 6c 1a
811
812This feature can be used to determine the register holding the fan
813speed on some models. To do that, do the following:
814
815 - make sure the battery is fully charged
816 - make sure the fan is running
817 - run 'cat /proc/acpi/ibm/ecdump' several times, once per second or so
818
819The first step makes sure various charging-related values don't
820vary. The second ensures that the fan-related values do vary, since
821the fan speed fluctuates a bit. The third will (hopefully) mark the
822fan register with a star:
823
Henrique de Moraes Holschuh837ca6d2007-03-23 17:33:54 -0300824[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400825EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f
826EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00
827EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00
828EC 0x20: 00 00 00 00 00 00 00 00 00 00 00 03 43 00 00 80
829EC 0x30: 01 07 1a 00 30 04 00 00 85 00 00 10 00 50 00 00
830EC 0x40: 00 00 00 00 00 00 14 01 00 04 00 00 00 00 00 00
831EC 0x50: 00 c0 02 0d 00 01 01 02 02 03 03 03 03 bc 02 bc
832EC 0x60: 02 bc 02 00 00 00 00 00 00 00 00 00 00 00 00 00
833EC 0x70: 00 00 00 00 00 12 30 40 24 27 2c 27 21 80 1f 80
834EC 0x80: 00 00 00 06 *be 0d 03 00 00 00 0e 07 00 00 00 00
835EC 0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
836EC 0xa0: ff 09 ff 09 ff ff 64 00 00 00 a2 41 ff ff e0 00
837EC 0xb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
838EC 0xc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
839EC 0xd0: 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
840EC 0xe0: 00 00 00 00 00 00 00 00 11 20 49 04 24 06 55 03
841EC 0xf0: 31 55 48 54 35 38 57 57 08 2f 45 73 07 65 6c 1a
842
843Another set of values that varies often is the temperature
844readings. Since temperatures don't change vary fast, you can take
845several quick dumps to eliminate them.
846
847You can use a similar method to figure out the meaning of other
848embedded controller registers - e.g. make sure nothing else changes
849except the charging or discharging battery to determine which
850registers contain the current battery capacity, etc. If you experiment
851with this, do send me your results (including some complete dumps with
852a description of the conditions when they were taken.)
853
Henrique de Moraes Holschuh7d5a0152007-04-24 11:48:20 -0300854LCD brightness control
855----------------------
856
857procfs: /proc/acpi/ibm/brightness
858sysfs backlight device "thinkpad_screen"
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400859
860This feature allows software control of the LCD brightness on ThinkPad
Henrique de Moraes Holschuh7d5a0152007-04-24 11:48:20 -0300861models which don't have a hardware brightness slider.
862
863It has some limitations: the LCD backlight cannot be actually turned on or off
864by this interface, and in many ThinkPad models, the "dim while on battery"
865functionality will be enabled by the BIOS when this interface is used, and
866cannot be controlled.
867
868The backlight control has eight levels, ranging from 0 to 7. Some of the
869levels may not be distinct.
870
Henrique de Moraes Holschuh24d3b772007-07-18 23:45:43 -0300871There are two interfaces to the firmware for brightness control, EC and CMOS.
872To select which one should be used, use the brightness_mode module parameter:
873brightness_mode=1 selects EC mode, brightness_mode=2 selects CMOS mode,
874brightness_mode=3 selects both EC and CMOS. The driver tries to autodetect
875which interface to use.
876
Henrique de Moraes Holschuh7d5a0152007-04-24 11:48:20 -0300877Procfs notes:
878
879 The available commands are:
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400880
881 echo up >/proc/acpi/ibm/brightness
882 echo down >/proc/acpi/ibm/brightness
883 echo 'level <level>' >/proc/acpi/ibm/brightness
884
Henrique de Moraes Holschuh7d5a0152007-04-24 11:48:20 -0300885Sysfs notes:
886
887The interface is implemented through the backlight sysfs class, which is poorly
888documented at this time.
889
890Locate the thinkpad_screen device under /sys/class/backlight, and inside it
891there will be the following attributes:
892
893 max_brightness:
894 Reads the maximum brightness the hardware can be set to.
895 The minimum is always zero.
896
897 actual_brightness:
898 Reads what brightness the screen is set to at this instant.
899
900 brightness:
901 Writes request the driver to change brightness to the given
902 value. Reads will tell you what brightness the driver is trying
903 to set the display to when "power" is set to zero and the display
904 has not been dimmed by a kernel power management event.
905
906 power:
907 power management mode, where 0 is "display on", and 1 to 3 will
908 dim the display backlight to brightness level 0 because
909 thinkpad-acpi cannot really turn the backlight off. Kernel
910 power management events can temporarily increase the current
911 power management level, i.e. they can dim the display.
912
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400913
Stefan Schmidt24f7ff02006-09-22 12:19:15 +0200914Volume control -- /proc/acpi/ibm/volume
915---------------------------------------
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400916
917This feature allows volume control on ThinkPad models which don't have
918a hardware volume knob. The available commands are:
919
920 echo up >/proc/acpi/ibm/volume
921 echo down >/proc/acpi/ibm/volume
922 echo mute >/proc/acpi/ibm/volume
923 echo 'level <level>' >/proc/acpi/ibm/volume
924
925The <level> number range is 0 to 15 although not all of them may be
926distinct. The unmute the volume after the mute command, use either the
927up or down command (the level command will not unmute the volume).
928The current volume level and mute state is shown in the file.
929
Henrique de Moraes Holschuhecf2a802007-04-27 22:00:09 -0300930Fan control and monitoring: fan speed, fan enable/disable
931---------------------------------------------------------
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300932
933procfs: /proc/acpi/ibm/fan
934sysfs device attributes: (hwmon) fan_input, pwm1, pwm1_enable
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400935
Henrique de Moraes Holschuhecf2a802007-04-27 22:00:09 -0300936NOTE NOTE NOTE: fan control operations are disabled by default for
937safety reasons. To enable them, the module parameter "fan_control=1"
938must be given to thinkpad-acpi.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400939
Henrique de Moraes Holschuha12095c2006-11-24 11:47:13 -0200940This feature attempts to show the current fan speed, control mode and
941other fan data that might be available. The speed is read directly
942from the hardware registers of the embedded controller. This is known
Henrique de Moraes Holschuhecf2a802007-04-27 22:00:09 -0300943to work on later R, T, X and Z series ThinkPads but may show a bogus
Henrique de Moraes Holschuha12095c2006-11-24 11:47:13 -0200944value on other models.
945
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300946Fan levels:
Henrique de Moraes Holschuha12095c2006-11-24 11:47:13 -0200947
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300948Most ThinkPad fans work in "levels" at the firmware interface. Level 0
949stops the fan. The higher the level, the higher the fan speed, although
950adjacent levels often map to the same fan speed. 7 is the highest
951level, where the fan reaches the maximum recommended speed.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400952
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300953Level "auto" means the EC changes the fan level according to some
954internal algorithm, usually based on readings from the thermal sensors.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400955
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300956There is also a "full-speed" level, also known as "disengaged" level.
957In this level, the EC disables the speed-locked closed-loop fan control,
958and drives the fan as fast as it can go, which might exceed hardware
959limits, so use this level with caution.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400960
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300961The fan usually ramps up or down slowly from one speed to another, and
962it is normal for the EC to take several seconds to react to fan
963commands. The full-speed level may take up to two minutes to ramp up to
964maximum speed, and in some ThinkPads, the tachometer readings go stale
965while the EC is transitioning to the full-speed level.
Borislav Deianov78f81cc2005-08-17 00:00:00 -0400966
Henrique de Moraes Holschuha12095c2006-11-24 11:47:13 -0200967WARNING WARNING WARNING: do not leave the fan disabled unless you are
968monitoring all of the temperature sensor readings and you are ready to
969enable it if necessary to avoid overheating.
970
971An enabled fan in level "auto" may stop spinning if the EC decides the
972ThinkPad is cool enough and doesn't need the extra airflow. This is
973normal, and the EC will spin the fan up if the varios thermal readings
974rise too much.
975
976On the X40, this seems to depend on the CPU and HDD temperatures.
977Specifically, the fan is turned on when either the CPU temperature
978climbs to 56 degrees or the HDD temperature climbs to 46 degrees. The
979fan is turned off when the CPU temperature drops to 49 degrees and the
980HDD temperature drops to 41 degrees. These thresholds cannot
981currently be controlled.
982
Henrique de Moraes Holschuha12095c2006-11-24 11:47:13 -0200983The ThinkPad's ACPI DSDT code will reprogram the fan on its own when
984certain conditions are met. It will override any fan programming done
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -0300985through thinkpad-acpi.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700986
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -0300987The thinkpad-acpi kernel driver can be programmed to revert the fan
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300988level to a safe setting if userspace does not issue one of the procfs
989fan commands: "enable", "disable", "level" or "watchdog", or if there
990are no writes to pwm1_enable (or to pwm1 *if and only if* pwm1_enable is
991set to 1, manual mode) within a configurable amount of time of up to
992120 seconds. This functionality is called fan safety watchdog.
Henrique de Moraes Holschuh38f996e2007-03-23 17:33:59 -0300993
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -0300994Note that the watchdog timer stops after it enables the fan. It will be
995rearmed again automatically (using the same interval) when one of the
996above mentioned fan commands is received. The fan watchdog is,
997therefore, not suitable to protect against fan mode changes made through
998means other than the "enable", "disable", and "level" procfs fan
999commands, or the hwmon fan control sysfs interface.
Henrique de Moraes Holschuh38f996e2007-03-23 17:33:59 -03001000
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001001Procfs notes:
Henrique de Moraes Holschuh38f996e2007-03-23 17:33:59 -03001002
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001003The fan may be enabled or disabled with the following commands:
1004
1005 echo enable >/proc/acpi/ibm/fan
1006 echo disable >/proc/acpi/ibm/fan
1007
1008Placing a fan on level 0 is the same as disabling it. Enabling a fan
1009will try to place it in a safe level if it is too slow or disabled.
1010
1011The fan level can be controlled with the command:
1012
1013 echo 'level <level>' > /proc/acpi/ibm/fan
1014
1015Where <level> is an integer from 0 to 7, or one of the words "auto" or
1016"full-speed" (without the quotes). Not all ThinkPads support the "auto"
1017and "full-speed" levels. The driver accepts "disengaged" as an alias for
1018"full-speed", and reports it as "disengaged" for backwards
1019compatibility.
1020
1021On the X31 and X40 (and ONLY on those models), the fan speed can be
1022controlled to a certain degree. Once the fan is running, it can be
1023forced to run faster or slower with the following command:
1024
1025 echo 'speed <speed>' > /proc/acpi/ibm/fan
1026
1027The sustainable range of fan speeds on the X40 appears to be from about
10283700 to about 7350. Values outside this range either do not have any
1029effect or the fan speed eventually settles somewhere in that range. The
1030fan cannot be stopped or started with this command. This functionality
1031is incomplete, and not available through the sysfs interface.
1032
1033To program the safety watchdog, use the "watchdog" command.
1034
1035 echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan
1036
1037If you want to disable the watchdog, use 0 as the interval.
1038
1039Sysfs notes:
1040
1041The sysfs interface follows the hwmon subsystem guidelines for the most
1042part, and the exception is the fan safety watchdog.
1043
Henrique de Moraes Holschuhb39fe582007-04-27 22:00:13 -03001044Writes to any of the sysfs attributes may return the EINVAL error if
1045that operation is not supported in a given ThinkPad or if the parameter
1046is out-of-bounds, and EPERM if it is forbidden. They may also return
1047EINTR (interrupted system call), and EIO (I/O error while trying to talk
1048to the firmware).
1049
1050Features not yet implemented by the driver return ENOSYS.
1051
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001052hwmon device attribute pwm1_enable:
1053 0: PWM offline (fan is set to full-speed mode)
1054 1: Manual PWM control (use pwm1 to set fan level)
1055 2: Hardware PWM control (EC "auto" mode)
1056 3: reserved (Software PWM control, not implemented yet)
1057
Henrique de Moraes Holschuhb39fe582007-04-27 22:00:13 -03001058 Modes 0 and 2 are not supported by all ThinkPads, and the
1059 driver is not always able to detect this. If it does know a
1060 mode is unsupported, it will return -EINVAL.
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001061
1062hwmon device attribute pwm1:
1063 Fan level, scaled from the firmware values of 0-7 to the hwmon
1064 scale of 0-255. 0 means fan stopped, 255 means highest normal
1065 speed (level 7).
1066
1067 This attribute only commands the fan if pmw1_enable is set to 1
1068 (manual PWM control).
1069
1070hwmon device attribute fan1_input:
1071 Fan tachometer reading, in RPM. May go stale on certain
1072 ThinkPads while the EC transitions the PWM to offline mode,
1073 which can take up to two minutes. May return rubbish on older
1074 ThinkPads.
1075
1076driver attribute fan_watchdog:
1077 Fan safety watchdog timer interval, in seconds. Minimum is
1078 1 second, maximum is 120 seconds. 0 disables the watchdog.
1079
1080To stop the fan: set pwm1 to zero, and pwm1_enable to 1.
1081
1082To start the fan in a safe mode: set pwm1_enable to 2. If that fails
Henrique de Moraes Holschuhb39fe582007-04-27 22:00:13 -03001083with EINVAL, try to set pwm1_enable to 1 and pwm1 to at least 128 (255
1084would be the safest choice, though).
Henrique de Moraes Holschuhfe98a522007-04-24 11:48:17 -03001085
Henrique de Moraes Holschuh38f996e2007-03-23 17:33:59 -03001086
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -03001087EXPERIMENTAL: WAN
1088-----------------
1089
1090procfs: /proc/acpi/ibm/wan
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -03001091sysfs device attribute: wwan_enable
Stefan Schmidt28b779d2006-09-22 12:19:16 +02001092
1093This feature is marked EXPERIMENTAL because the implementation
1094directly accesses hardware registers and may not work as expected. USE
1095WITH CAUTION! To use this feature, you need to supply the
1096experimental=1 parameter when loading the module.
1097
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -03001098This feature shows the presence and current state of a W-WAN (Sierra
1099Wireless EV-DO) device.
1100
1101It was tested on a Lenovo Thinkpad X60. It should probably work on other
1102Thinkpad models which come with this module installed.
1103
1104Procfs notes:
1105
1106If the W-WAN card is installed, the following commands can be used:
Stefan Schmidt28b779d2006-09-22 12:19:16 +02001107
1108 echo enable > /proc/acpi/ibm/wan
1109 echo disable > /proc/acpi/ibm/wan
1110
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -03001111Sysfs notes:
1112
1113 If the W-WAN card is installed, it can be enabled /
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -03001114 disabled through the "wwan_enable" thinkpad-acpi device
Henrique de Moraes Holschuhd3a6ade2007-04-27 22:00:17 -03001115 attribute, and its current status can also be queried.
1116
1117 enable:
1118 0: disables WWAN card / WWAN card is disabled
1119 1: enables WWAN card / WWAN card is enabled.
1120
1121 Note: this interface will be probably be superseeded by the
Henrique de Moraes Holschuhcc4c24e2007-05-30 20:50:14 -03001122 generic rfkill class, so it is NOT to be considered stable yet.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001123
Borislav Deianov78f81cc2005-08-17 00:00:00 -04001124Multiple Commands, Module Parameters
1125------------------------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -07001126
1127Multiple commands can be written to the proc files in one shot by
1128separating them with commas, for example:
1129
1130 echo enable,0xffff > /proc/acpi/ibm/hotkey
1131 echo lcd_disable,crt_enable > /proc/acpi/ibm/video
1132
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -03001133Commands can also be specified when loading the thinkpad-acpi module,
1134for example:
Linus Torvalds1da177e2005-04-16 15:20:36 -07001135
Henrique de Moraes Holschuh643f12d2007-03-29 01:58:43 -03001136 modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
Linus Torvalds1da177e2005-04-16 15:20:36 -07001137
Henrique de Moraes Holschuh132ce092007-04-21 11:08:30 -03001138Enabling debugging output
1139-------------------------
1140
1141The module takes a debug paramater which can be used to selectively
1142enable various classes of debugging output, for example:
1143
1144 modprobe ibm_acpi debug=0xffff
1145
1146will enable all debugging output classes. It takes a bitmask, so
1147to enable more than one output class, just add their values.
1148
Henrique de Moraes Holschuhfe08bc42007-04-21 11:08:32 -03001149 Debug bitmask Description
1150 0x0001 Initialization and probing
1151 0x0002 Removal
1152
Henrique de Moraes Holschuh132ce092007-04-21 11:08:30 -03001153There is also a kernel build option to enable more debugging
1154information, which may be necessary to debug driver problems.
Henrique de Moraes Holschuh0dcef772007-04-21 11:08:34 -03001155
Henrique de Moraes Holschuh176750d2007-04-24 11:48:13 -03001156The level of debugging information output by the driver can be changed
1157at runtime through sysfs, using the driver attribute debug_level. The
1158attribute takes the same bitmask as the debug module parameter above.
1159
Henrique de Moraes Holschuh0dcef772007-04-21 11:08:34 -03001160Force loading of module
1161-----------------------
1162
1163If thinkpad-acpi refuses to detect your ThinkPad, you can try to specify
1164the module parameter force_load=1. Regardless of whether this works or
1165not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
Henrique de Moraes Holschuh176750d2007-04-24 11:48:13 -03001166
1167
1168Sysfs interface changelog:
1169
11700x000100: Initial sysfs support, as a single platform driver and
1171 device.
Henrique de Moraes Holschuh94b08712007-07-18 23:45:32 -030011720x000200: Hot key support for 32 hot keys, and radio slider switch
1173 support.
Henrique de Moraes Holschuh741553c2007-07-18 23:45:39 -030011740x010000: Hot keys are now handled by default over the input
1175 layer, the radio switch generates input event EV_RADIO,
1176 and the driver enables hot key handling by default in
1177 the firmware.