Contents of /alx-src/tags/kernel26-2.6.12-alx-r9/Documentation/ibm-acpi.txt
Parent Directory | Revision Log
Revision 630 -
(show annotations)
(download)
Wed Mar 4 11:03:09 2009 UTC (15 years, 3 months ago) by niro
File MIME type: text/plain
File size: 17635 byte(s)
Wed Mar 4 11:03:09 2009 UTC (15 years, 3 months ago) by niro
File MIME type: text/plain
File size: 17635 byte(s)
Tag kernel26-2.6.12-alx-r9
1 | IBM ThinkPad ACPI Extras Driver |
2 | |
3 | Version 0.8 |
4 | 8 November 2004 |
5 | |
6 | Borislav Deianov <borislav@users.sf.net> |
7 | http://ibm-acpi.sf.net/ |
8 | |
9 | |
10 | This is a Linux ACPI driver for the IBM ThinkPad laptops. It aims to |
11 | support various features of these laptops which are accessible through |
12 | the ACPI framework but not otherwise supported by the generic Linux |
13 | ACPI drivers. |
14 | |
15 | |
16 | Status |
17 | ------ |
18 | |
19 | The features currently supported are the following (see below for |
20 | detailed description): |
21 | |
22 | - Fn key combinations |
23 | - Bluetooth enable and disable |
24 | - video output switching, expansion control |
25 | - ThinkLight on and off |
26 | - limited docking and undocking |
27 | - UltraBay eject |
28 | - Experimental: CMOS control |
29 | - Experimental: LED control |
30 | - Experimental: ACPI sounds |
31 | |
32 | A compatibility table by model and feature is maintained on the web |
33 | site, http://ibm-acpi.sf.net/. I appreciate any success or failure |
34 | reports, especially if they add to or correct the compatibility table. |
35 | Please include the following information in your report: |
36 | |
37 | - ThinkPad model name |
38 | - a copy of your DSDT, from /proc/acpi/dsdt |
39 | - which driver features work and which don't |
40 | - the observed behavior of non-working features |
41 | |
42 | Any other comments or patches are also more than welcome. |
43 | |
44 | |
45 | Installation |
46 | ------------ |
47 | |
48 | If you are compiling this driver as included in the Linux kernel |
49 | sources, simply enable the CONFIG_ACPI_IBM option (Power Management / |
50 | ACPI / IBM ThinkPad Laptop Extras). The rest of this section describes |
51 | how to install this driver when downloaded from the web site. |
52 | |
53 | First, you need to get a kernel with ACPI support up and running. |
54 | Please refer to http://acpi.sourceforge.net/ for help with this |
55 | step. How successful you will be depends a lot on you ThinkPad model, |
56 | the kernel you are using and any additional patches applied. The |
57 | kernel provided with your distribution may not be good enough. I |
58 | needed to compile a 2.6.7 kernel with the 20040715 ACPI patch to get |
59 | ACPI working reliably on my ThinkPad X40. Old ThinkPad models may not |
60 | be supported at all. |
61 | |
62 | Assuming you have the basic ACPI support working (e.g. you can see the |
63 | /proc/acpi directory), follow the following steps to install this |
64 | driver: |
65 | |
66 | - unpack the archive: |
67 | |
68 | tar xzvf ibm-acpi-x.y.tar.gz; cd ibm-acpi-x.y |
69 | |
70 | - compile the driver: |
71 | |
72 | make |
73 | |
74 | - install the module in your kernel modules directory: |
75 | |
76 | make install |
77 | |
78 | - load the module: |
79 | |
80 | modprobe ibm_acpi |
81 | |
82 | After loading the module, check the "dmesg" output for any error messages. |
83 | |
84 | |
85 | Features |
86 | -------- |
87 | |
88 | The driver creates the /proc/acpi/ibm directory. There is a file under |
89 | that directory for each feature described below. Note that while the |
90 | driver is still in the alpha stage, the exact proc file format and |
91 | commands supported by the various features is guaranteed to change |
92 | frequently. |
93 | |
94 | Driver Version -- /proc/acpi/ibm/driver |
95 | -------------------------------------- |
96 | |
97 | The driver name and version. No commands can be written to this file. |
98 | |
99 | Hot Keys -- /proc/acpi/ibm/hotkey |
100 | --------------------------------- |
101 | |
102 | Without this driver, only the Fn-F4 key (sleep button) generates an |
103 | ACPI event. With the driver loaded, the hotkey feature enabled and the |
104 | mask set (see below), the various hot keys generate ACPI events in the |
105 | following format: |
106 | |
107 | ibm/hotkey HKEY 00000080 0000xxxx |
108 | |
109 | The last four digits vary depending on the key combination pressed. |
110 | All labeled Fn-Fx key combinations generate distinct events. In |
111 | addition, the lid microswitch and some docking station buttons may |
112 | also generate such events. |
113 | |
114 | The following commands can be written to this file: |
115 | |
116 | echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature |
117 | echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature |
118 | echo 0xffff > /proc/acpi/ibm/hotkey -- enable all possible hot keys |
119 | echo 0x0000 > /proc/acpi/ibm/hotkey -- disable all possible hot keys |
120 | ... any other 4-hex-digit mask ... |
121 | echo reset > /proc/acpi/ibm/hotkey -- restore the original mask |
122 | |
123 | The bit mask allows some control over which hot keys generate ACPI |
124 | events. Not all bits in the mask can be modified. Not all bits that |
125 | can be modified do anything. Not all hot keys can be individually |
126 | controlled by the mask. Most recent ThinkPad models honor the |
127 | following bits (assuming the hot keys feature has been enabled): |
128 | |
129 | key bit behavior when set behavior when unset |
130 | |
131 | Fn-F3 always generates ACPI event |
132 | Fn-F4 always generates ACPI event |
133 | Fn-F5 0010 generate ACPI event enable/disable Bluetooth |
134 | Fn-F7 0040 generate ACPI event switch LCD and external display |
135 | Fn-F8 0080 generate ACPI event expand screen or none |
136 | Fn-F9 0100 generate ACPI event none |
137 | Fn-F12 always generates ACPI event |
138 | |
139 | Some models do not support all of the above. For example, the T30 does |
140 | not support Fn-F5 and Fn-F9. Other models do not support the mask at |
141 | all. On those models, hot keys cannot be controlled individually. |
142 | |
143 | Note that enabling ACPI events for some keys prevents their default |
144 | behavior. For example, if events for Fn-F5 are enabled, that key will |
145 | no longer enable/disable Bluetooth by itself. This can still be done |
146 | from an acpid handler for the ibm/hotkey event. |
147 | |
148 | Note also that not all Fn key combinations are supported through |
149 | ACPI. For example, on the X40, the brightness, volume and "Access IBM" |
150 | buttons do not generate ACPI events even with this driver. They *can* |
151 | be used through the "ThinkPad Buttons" utility, see |
152 | http://www.nongnu.org/tpb/ |
153 | |
154 | Bluetooth -- /proc/acpi/ibm/bluetooth |
155 | ------------------------------------- |
156 | |
157 | This feature shows the presence and current state of a Bluetooth |
158 | device. If Bluetooth is installed, the following commands can be used: |
159 | |
160 | echo enable > /proc/acpi/ibm/bluetooth |
161 | echo disable > /proc/acpi/ibm/bluetooth |
162 | |
163 | Video output control -- /proc/acpi/ibm/video |
164 | -------------------------------------------- |
165 | |
166 | This feature allows control over the devices used for video output - |
167 | LCD, CRT or DVI (if available). The following commands are available: |
168 | |
169 | echo lcd_enable > /proc/acpi/ibm/video |
170 | echo lcd_disable > /proc/acpi/ibm/video |
171 | echo crt_enable > /proc/acpi/ibm/video |
172 | echo crt_disable > /proc/acpi/ibm/video |
173 | echo dvi_enable > /proc/acpi/ibm/video |
174 | echo dvi_disable > /proc/acpi/ibm/video |
175 | echo auto_enable > /proc/acpi/ibm/video |
176 | echo auto_disable > /proc/acpi/ibm/video |
177 | echo expand_toggle > /proc/acpi/ibm/video |
178 | echo video_switch > /proc/acpi/ibm/video |
179 | |
180 | Each video output device can be enabled or disabled individually. |
181 | Reading /proc/acpi/ibm/video shows the status of each device. |
182 | |
183 | Automatic video switching can be enabled or disabled. When automatic |
184 | video switching is enabled, certain events (e.g. opening the lid, |
185 | docking or undocking) cause the video output device to change |
186 | automatically. While this can be useful, it also causes flickering |
187 | and, on the X40, video corruption. By disabling automatic switching, |
188 | the flickering or video corruption can be avoided. |
189 | |
190 | The video_switch command cycles through the available video outputs |
191 | (it sumulates the behavior of Fn-F7). |
192 | |
193 | Video expansion can be toggled through this feature. This controls |
194 | whether the display is expanded to fill the entire LCD screen when a |
195 | mode with less than full resolution is used. Note that the current |
196 | video expansion status cannot be determined through this feature. |
197 | |
198 | Note that on many models (particularly those using Radeon graphics |
199 | chips) the X driver configures the video card in a way which prevents |
200 | Fn-F7 from working. This also disables the video output switching |
201 | features of this driver, as it uses the same ACPI methods as |
202 | Fn-F7. Video switching on the console should still work. |
203 | |
204 | ThinkLight control -- /proc/acpi/ibm/light |
205 | ------------------------------------------ |
206 | |
207 | The current status of the ThinkLight can be found in this file. A few |
208 | models which do not make the status available will show it as |
209 | "unknown". The available commands are: |
210 | |
211 | echo on > /proc/acpi/ibm/light |
212 | echo off > /proc/acpi/ibm/light |
213 | |
214 | Docking / Undocking -- /proc/acpi/ibm/dock |
215 | ------------------------------------------ |
216 | |
217 | Docking and undocking (e.g. with the X4 UltraBase) requires some |
218 | actions to be taken by the operating system to safely make or break |
219 | the electrical connections with the dock. |
220 | |
221 | The docking feature of this driver generates the following ACPI events: |
222 | |
223 | ibm/dock GDCK 00000003 00000001 -- eject request |
224 | ibm/dock GDCK 00000003 00000002 -- undocked |
225 | ibm/dock GDCK 00000000 00000003 -- docked |
226 | |
227 | NOTE: These events will only be generated if the laptop was docked |
228 | when originally booted. This is due to the current lack of support for |
229 | hot plugging of devices in the Linux ACPI framework. If the laptop was |
230 | booted while not in the dock, the following message is shown in the |
231 | logs: "ibm_acpi: dock device not present". No dock-related events are |
232 | generated but the dock and undock commands described below still |
233 | work. They can be executed manually or triggered by Fn key |
234 | combinations (see the example acpid configuration files included in |
235 | the driver tarball package available on the web site). |
236 | |
237 | When the eject request button on the dock is pressed, the first event |
238 | above is generated. The handler for this event should issue the |
239 | following command: |
240 | |
241 | echo undock > /proc/acpi/ibm/dock |
242 | |
243 | After the LED on the dock goes off, it is safe to eject the laptop. |
244 | Note: if you pressed this key by mistake, go ahead and eject the |
245 | laptop, then dock it back in. Otherwise, the dock may not function as |
246 | expected. |
247 | |
248 | When the laptop is docked, the third event above is generated. The |
249 | handler for this event should issue the following command to fully |
250 | enable the dock: |
251 | |
252 | echo dock > /proc/acpi/ibm/dock |
253 | |
254 | The contents of the /proc/acpi/ibm/dock file shows the current status |
255 | of the dock, as provided by the ACPI framework. |
256 | |
257 | The docking support in this driver does not take care of enabling or |
258 | disabling any other devices you may have attached to the dock. For |
259 | example, a CD drive plugged into the UltraBase needs to be disabled or |
260 | enabled separately. See the provided example acpid configuration files |
261 | for how this can be accomplished. |
262 | |
263 | There is no support yet for PCI devices that may be attached to a |
264 | docking station, e.g. in the ThinkPad Dock II. The driver currently |
265 | does not recognize, enable or disable such devices. This means that |
266 | the only docking stations currently supported are the X-series |
267 | UltraBase docks and "dumb" port replicators like the Mini Dock (the |
268 | latter don't need any ACPI support, actually). |
269 | |
270 | UltraBay Eject -- /proc/acpi/ibm/bay |
271 | ------------------------------------ |
272 | |
273 | Inserting or ejecting an UltraBay device requires some actions to be |
274 | taken by the operating system to safely make or break the electrical |
275 | connections with the device. |
276 | |
277 | This feature generates the following ACPI events: |
278 | |
279 | ibm/bay MSTR 00000003 00000000 -- eject request |
280 | ibm/bay MSTR 00000001 00000000 -- eject lever inserted |
281 | |
282 | NOTE: These events will only be generated if the UltraBay was present |
283 | when the laptop was originally booted (on the X series, the UltraBay |
284 | is in the dock, so it may not be present if the laptop was undocked). |
285 | This is due to the current lack of support for hot plugging of devices |
286 | in the Linux ACPI framework. If the laptop was booted without the |
287 | UltraBay, the following message is shown in the logs: "ibm_acpi: bay |
288 | device not present". No bay-related events are generated but the eject |
289 | command described below still works. It can be executed manually or |
290 | triggered by a hot key combination. |
291 | |
292 | Sliding the eject lever generates the first event shown above. The |
293 | handler for this event should take whatever actions are necessary to |
294 | shut down the device in the UltraBay (e.g. call idectl), then issue |
295 | the following command: |
296 | |
297 | echo eject > /proc/acpi/ibm/bay |
298 | |
299 | After the LED on the UltraBay goes off, it is safe to pull out the |
300 | device. |
301 | |
302 | When the eject lever is inserted, the second event above is |
303 | generated. The handler for this event should take whatever actions are |
304 | necessary to enable the UltraBay device (e.g. call idectl). |
305 | |
306 | The contents of the /proc/acpi/ibm/bay file shows the current status |
307 | of the UltraBay, as provided by the ACPI framework. |
308 | |
309 | Experimental Features |
310 | --------------------- |
311 | |
312 | The following features are marked experimental because using them |
313 | involves guessing the correct values of some parameters. Guessing |
314 | incorrectly may have undesirable effects like crashing your |
315 | ThinkPad. USE THESE WITH CAUTION! To activate them, you'll need to |
316 | supply the experimental=1 parameter when loading the module. |
317 | |
318 | Experimental: CMOS control - /proc/acpi/ibm/cmos |
319 | ------------------------------------------------ |
320 | |
321 | This feature is used internally by the ACPI firmware to control the |
322 | ThinkLight on most newer ThinkPad models. It appears that it can also |
323 | control LCD brightness, sounds volume and more, but only on some |
324 | models. |
325 | |
326 | The commands are non-negative integer numbers: |
327 | |
328 | echo 0 >/proc/acpi/ibm/cmos |
329 | echo 1 >/proc/acpi/ibm/cmos |
330 | echo 2 >/proc/acpi/ibm/cmos |
331 | ... |
332 | |
333 | The range of numbers which are used internally by various models is 0 |
334 | to 21, but it's possible that numbers outside this range have |
335 | interesting behavior. Here is the behavior on the X40 (tpb is the |
336 | ThinkPad Buttons utility): |
337 | |
338 | 0 - no effect but tpb reports "Volume down" |
339 | 1 - no effect but tpb reports "Volume up" |
340 | 2 - no effect but tpb reports "Mute on" |
341 | 3 - simulate pressing the "Access IBM" button |
342 | 4 - LCD brightness up |
343 | 5 - LCD brightness down |
344 | 11 - toggle screen expansion |
345 | 12 - ThinkLight on |
346 | 13 - ThinkLight off |
347 | 14 - no effect but tpb reports ThinkLight status change |
348 | |
349 | If you try this feature, please send me a report similar to the |
350 | above. On models which allow control of LCD brightness or sound |
351 | volume, I'd like to provide this functionality in an user-friendly |
352 | way, but first I need a way to identify the models which this is |
353 | possible. |
354 | |
355 | Experimental: LED control - /proc/acpi/ibm/LED |
356 | ---------------------------------------------- |
357 | |
358 | Some of the LED indicators can be controlled through this feature. The |
359 | available commands are: |
360 | |
361 | echo <led number> on >/proc/acpi/ibm/led |
362 | echo <led number> off >/proc/acpi/ibm/led |
363 | echo <led number> blink >/proc/acpi/ibm/led |
364 | |
365 | The <led number> parameter is a non-negative integer. The range of LED |
366 | numbers used internally by various models is 0 to 7 but it's possible |
367 | that numbers outside this range are also valid. Here is the mapping on |
368 | the X40: |
369 | |
370 | 0 - power |
371 | 1 - battery (orange) |
372 | 2 - battery (green) |
373 | 3 - UltraBase |
374 | 4 - UltraBay |
375 | 7 - standby |
376 | |
377 | All of the above can be turned on and off and can be made to blink. |
378 | |
379 | If you try this feature, please send me a report similar to the |
380 | above. I'd like to provide this functionality in an user-friendly way, |
381 | but first I need to identify the which numbers correspond to which |
382 | LEDs on various models. |
383 | |
384 | Experimental: ACPI sounds - /proc/acpi/ibm/beep |
385 | ----------------------------------------------- |
386 | |
387 | The BEEP method is used internally by the ACPI firmware to provide |
388 | audible alerts in various situtation. This feature allows the same |
389 | sounds to be triggered manually. |
390 | |
391 | The commands are non-negative integer numbers: |
392 | |
393 | echo 0 >/proc/acpi/ibm/beep |
394 | echo 1 >/proc/acpi/ibm/beep |
395 | echo 2 >/proc/acpi/ibm/beep |
396 | ... |
397 | |
398 | The range of numbers which are used internally by various models is 0 |
399 | to 17, but it's possible that numbers outside this range are also |
400 | valid. Here is the behavior on the X40: |
401 | |
402 | 2 - two beeps, pause, third beep |
403 | 3 - single beep |
404 | 4 - "unable" |
405 | 5 - single beep |
406 | 6 - "AC/DC" |
407 | 7 - high-pitched beep |
408 | 9 - three short beeps |
409 | 10 - very long beep |
410 | 12 - low-pitched beep |
411 | |
412 | (I've only been able to identify a couple of them). |
413 | |
414 | If you try this feature, please send me a report similar to the |
415 | above. I'd like to provide this functionality in an user-friendly way, |
416 | but first I need to identify the which numbers correspond to which |
417 | sounds on various models. |
418 | |
419 | |
420 | Multiple Command, Module Parameters |
421 | ----------------------------------- |
422 | |
423 | Multiple commands can be written to the proc files in one shot by |
424 | separating them with commas, for example: |
425 | |
426 | echo enable,0xffff > /proc/acpi/ibm/hotkey |
427 | echo lcd_disable,crt_enable > /proc/acpi/ibm/video |
428 | |
429 | Commands can also be specified when loading the ibm_acpi module, for |
430 | example: |
431 | |
432 | modprobe ibm_acpi hotkey=enable,0xffff video=auto_disable |
433 | |
434 | |
435 | Example Configuration |
436 | --------------------- |
437 | |
438 | The ACPI support in the kernel is intended to be used in conjunction |
439 | with a user-space daemon, acpid. The configuration files for this |
440 | daemon control what actions are taken in response to various ACPI |
441 | events. An example set of configuration files are included in the |
442 | config/ directory of the tarball package available on the web |
443 | site. Note that these are provided for illustration purposes only and |
444 | may need to be adapted to your particular setup. |
445 | |
446 | The following utility scripts are used by the example action |
447 | scripts (included with ibm-acpi for completeness): |
448 | |
449 | /usr/local/sbin/idectl -- from the hdparm source distribution, |
450 | see http://www.ibiblio.org/pub/Linux/system/hardware |
451 | /usr/local/sbin/laptop_mode -- from the Linux kernel source |
452 | distribution, see Documentation/laptop-mode.txt |
453 | /sbin/service -- comes with Redhat/Fedora distributions |
454 | |
455 | Toan T Nguyen <ntt@control.uchicago.edu> has written a SuSE powersave |
456 | script for the X20, included in config/usr/sbin/ibm_hotkeys_X20 |
457 | |
458 | Henrik Brix Andersen <brix@gentoo.org> has written a Gentoo ACPI event |
459 | handler script for the X31. You can get the latest version from |
460 | http://dev.gentoo.org/~brix/files/x31.sh |
461 | |
462 | David Schweikert <dws@ee.eth.ch> has written an alternative blank.sh |
463 | script which works on Debian systems, included in |
464 | configs/etc/acpi/actions/blank-debian.sh |
465 | |
466 | |
467 | TODO |
468 | ---- |
469 | |
470 | I'd like to implement the following features but haven't yet found the |
471 | time and/or I don't yet know how to implement them: |
472 | |
473 | - UltraBay floppy drive support |
474 |