[ACPI] IBM ThinkPad ACPI Extras Driver v0.12

		    IBM ThinkPad ACPI Extras Driver

                            Version 0.8

                          8 November 2004

                            Version 0.12

                           17 August 2005

               Borislav Deianov <borislav@users.sf.net>

		      http://ibm-acpi.sf.net/

This is a Linux ACPI driver for the IBM ThinkPad laptops. It aims to

support various features of these laptops which are accessible through

the ACPI framework but not otherwise supported by the generic Linux

ACPI drivers.

This is a Linux ACPI driver for the IBM ThinkPad laptops. It supports

various features of these laptops which are accessible through the

ACPI framework but not otherwise supported by the generic Linux ACPI

drivers.

Status

	- ThinkLight on and off

	- limited docking and undocking

	- UltraBay eject

	- Experimental: CMOS control

	- Experimental: LED control

	- Experimental: ACPI sounds

	- CMOS control

	- LED control

	- ACPI sounds

	- temperature sensors

	- Experimental: embedded controller register dump

	- Experimental: LCD brightness control

	- Experimental: volume control

	- Experimental: fan speed, fan enable/disable

A compatibility table by model and feature is maintained on the web

site, http://ibm-acpi.sf.net/. I appreciate any success or failure

commands supported by the various features is guaranteed to change

frequently.

Driver Version -- /proc/acpi/ibm/driver

--------------------------------------

Driver version -- /proc/acpi/ibm/driver

---------------------------------------

The driver name and version. No commands can be written to this file.

Hot Keys -- /proc/acpi/ibm/hotkey

Hot keys -- /proc/acpi/ibm/hotkey

---------------------------------

Without this driver, only the Fn-F4 key (sleep button) generates an

the flickering or video corruption can be avoided.

The video_switch command cycles through the available video outputs

(it sumulates the behavior of Fn-F7).

(it simulates the behavior of Fn-F7).

Video expansion can be toggled through this feature. This controls

whether the display is expanded to fill the entire LCD screen when a

features of this driver, as it uses the same ACPI methods as

Fn-F7. Video switching on the console should still work.

UPDATE: There's now a patch for the X.org Radeon driver which

addresses this issue. Some people are reporting success with the patch

while others are still having problems. For more information:

https://bugs.freedesktop.org/show_bug.cgi?id=2000

ThinkLight control -- /proc/acpi/ibm/light

------------------------------------------

	echo on  > /proc/acpi/ibm/light

	echo off > /proc/acpi/ibm/light

Docking / Undocking -- /proc/acpi/ibm/dock

Docking / undocking -- /proc/acpi/ibm/dock

------------------------------------------

Docking and undocking (e.g. with the X4 UltraBase) requires some

when originally booted. This is due to the current lack of support for

hot plugging of devices in the Linux ACPI framework. If the laptop was

booted while not in the dock, the following message is shown in the

logs: "ibm_acpi: dock device not present". No dock-related events are

generated but the dock and undock commands described below still

work. They can be executed manually or triggered by Fn key

combinations (see the example acpid configuration files included in

the driver tarball package available on the web site).

logs:

	Mar 17 01:42:34 aero kernel: ibm_acpi: dock device not present

In this case, no dock-related events are generated but the dock and

undock commands described below still work. They can be executed

manually or triggered by Fn key combinations (see the example acpid

configuration files included in the driver tarball package available

on the web site).

When the eject request button on the dock is pressed, the first event

above is generated. The handler for this event should issue the

UltraBase docks and "dumb" port replicators like the Mini Dock (the

latter don't need any ACPI support, actually).

UltraBay Eject -- /proc/acpi/ibm/bay

UltraBay eject -- /proc/acpi/ibm/bay

------------------------------------

Inserting or ejecting an UltraBay device requires some actions to be

is in the dock, so it may not be present if the laptop was undocked).

This is due to the current lack of support for hot plugging of devices

in the Linux ACPI framework. If the laptop was booted without the

UltraBay, the following message is shown in the logs: "ibm_acpi: bay

device not present". No bay-related events are generated but the eject

UltraBay, the following message is shown in the logs:

	Mar 17 01:42:34 aero kernel: ibm_acpi: bay device not present

In this case, no bay-related events are generated but the eject

command described below still works. It can be executed manually or

triggered by a hot key combination.

The contents of the /proc/acpi/ibm/bay file shows the current status

of the UltraBay, as provided by the ACPI framework.

Experimental Features

---------------------

EXPERIMENTAL warm eject support on the 600e/x, A22p and A3x (To use

this feature, you need to supply the experimental=1 parameter when

loading the module):

These models do not have a button near the UltraBay device to request

a hot eject but rather require the laptop to be put to sleep

(suspend-to-ram) before the bay device is ejected or inserted).

The sequence of steps to eject the device is as follows:

	echo eject > /proc/acpi/ibm/bay

	put the ThinkPad to sleep

	remove the drive

	resume from sleep

	cat /proc/acpi/ibm/bay should show that the drive was removed

On the A3x, both the UltraBay 2000 and UltraBay Plus devices are

supported. Use "eject2" instead of "eject" for the second bay.

The following features are marked experimental because using them

involves guessing the correct values of some parameters. Guessing

incorrectly may have undesirable effects like crashing your

ThinkPad. USE THESE WITH CAUTION! To activate them, you'll need to

supply the experimental=1 parameter when loading the module.

Note: the UltraBay eject support on the 600e/x, A22p and A3x is

EXPERIMENTAL and may not work as expected. USE WITH CAUTION!

Experimental: CMOS control - /proc/acpi/ibm/cmos

------------------------------------------------

CMOS control -- /proc/acpi/ibm/cmos

-----------------------------------

This feature is used internally by the ACPI firmware to control the

ThinkLight on most newer ThinkPad models. It appears that it can also

control LCD brightness, sounds volume and more, but only on some

models.

ThinkLight on most newer ThinkPad models. It may also control LCD

brightness, sounds volume and more, but only on some models.

The commands are non-negative integer numbers:

	echo 2 >/proc/acpi/ibm/cmos

	...

The range of numbers which are used internally by various models is 0

to 21, but it's possible that numbers outside this range have

interesting behavior. Here is the behavior on the X40 (tpb is the

ThinkPad Buttons utility):

The range of valid numbers is 0 to 21, but not all have an effect and

the behavior varies from model to model. Here is the behavior on the

X40 (tpb is the ThinkPad Buttons utility):

	0 - no effect but tpb reports "Volume down"

	1 - no effect but tpb reports "Volume up"

	13 - ThinkLight off

	14 - no effect but tpb reports ThinkLight status change

If you try this feature, please send me a report similar to the

above. On models which allow control of LCD brightness or sound

volume, I'd like to provide this functionality in an user-friendly

way, but first I need a way to identify the models which this is

possible.

Experimental: LED control - /proc/acpi/ibm/LED

----------------------------------------------

LED control -- /proc/acpi/ibm/led

---------------------------------

Some of the LED indicators can be controlled through this feature. The

available commands are:

	echo <led number> on >/proc/acpi/ibm/led

	echo <led number> off >/proc/acpi/ibm/led

	echo <led number> blink >/proc/acpi/ibm/led

	echo '<led number> on' >/proc/acpi/ibm/led

	echo '<led number> off' >/proc/acpi/ibm/led

	echo '<led number> blink' >/proc/acpi/ibm/led

The <led number> parameter is a non-negative integer. The range of LED

numbers used internally by various models is 0 to 7 but it's possible

that numbers outside this range are also valid. Here is the mapping on

the X40:

The <led number> range is 0 to 7. The set of LEDs that can be

controlled varies from model to model. Here is the mapping on the X40:

	0 - power

	1 - battery (orange)

All of the above can be turned on and off and can be made to blink.

If you try this feature, please send me a report similar to the

above. I'd like to provide this functionality in an user-friendly way,

but first I need to identify the which numbers correspond to which

LEDs on various models.

Experimental: ACPI sounds - /proc/acpi/ibm/beep

-----------------------------------------------

ACPI sounds -- /proc/acpi/ibm/beep

----------------------------------

The BEEP method is used internally by the ACPI firmware to provide

audible alerts in various situtation. This feature allows the same

audible alerts in various situations. This feature allows the same

sounds to be triggered manually.

The commands are non-negative integer numbers:

	echo 0 >/proc/acpi/ibm/beep

	echo 1 >/proc/acpi/ibm/beep

	echo 2 >/proc/acpi/ibm/beep

	...

	echo <number> >/proc/acpi/ibm/beep

The range of numbers which are used internally by various models is 0

to 17, but it's possible that numbers outside this range are also

valid. Here is the behavior on the X40:

The valid <number> range is 0 to 17. Not all numbers trigger sounds

and the sounds vary from model to model. Here is the behavior on the

X40:

	2 - two beeps, pause, third beep

	0 - stop a sound in progress (but use 17 to stop 16)

	2 - two beeps, pause, third beep ("low battery")

	3 - single beep

	4 - "unable"	

	4 - high, followed by low-pitched beep ("unable")

	5 - single beep

	6 - "AC/DC"

	6 - very high, followed by high-pitched beep ("AC/DC")

	7 - high-pitched beep

	9 - three short beeps

	10 - very long beep

	12 - low-pitched beep

	15 - three high-pitched beeps repeating constantly, stop with 0

	16 - one medium-pitched beep repeating constantly, stop with 17

	17 - stop 16

Temperature sensors -- /proc/acpi/ibm/thermal

---------------------------------------------

Most ThinkPads include six or more separate temperature sensors but

only expose the CPU temperature through the standard ACPI methods.

This feature shows readings from up to eight different sensors. Some

readings may not be valid, e.g. may show large negative values. For

example, on the X40, a typical output may be:

temperatures:   42 42 45 41 36 -128 33 -128

Thomas Gruber took his R51 apart and traced all six active sensors in

his laptop (the location of sensors may vary on other models):

1:  CPU

2:  Mini PCI Module

3:  HDD

4:  GPU

5:  Battery

6:  N/A

7:  Battery

8:  N/A

No commands can be written to this file.

EXPERIMENTAL: Embedded controller reigster dump -- /proc/acpi/ibm/ecdump

------------------------------------------------------------------------

This feature is marked EXPERIMENTAL because the implementation

directly accesses hardware registers and may not work as expected. USE

WITH CAUTION! To use this feature, you need to supply the

experimental=1 parameter when loading the module.

This feature dumps the values of 256 embedded controller

registers. Values which have changed since the last time the registers

were dumped are marked with a star:

[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump 

EC       +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f

EC 0x00:  a7  47  87  01  fe  96  00  08  01  00  cb  00  00  00  40  00

EC 0x10:  00  00  ff  ff  f4  3c  87  09  01  ff  42  01  ff  ff  0d  00

EC 0x20:  00  00  00  00  00  00  00  00  00  00  00  03  43  00  00  80

EC 0x30:  01  07  1a  00  30  04  00  00 *85  00  00  10  00  50  00  00

EC 0x40:  00  00  00  00  00  00  14  01  00  04  00  00  00  00  00  00

EC 0x50:  00  c0  02  0d  00  01  01  02  02  03  03  03  03 *bc *02 *bc

EC 0x60: *02 *bc *02  00  00  00  00  00  00  00  00  00  00  00  00  00

EC 0x70:  00  00  00  00  00  12  30  40 *24 *26 *2c *27 *20  80 *1f  80

EC 0x80:  00  00  00  06 *37 *0e  03  00  00  00  0e  07  00  00  00  00

EC 0x90:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00

EC 0xa0: *ff  09  ff  09  ff  ff *64  00 *00 *00 *a2  41 *ff *ff *e0  00

EC 0xb0:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00

EC 0xc0:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00

EC 0xd0:  03  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00

EC 0xe0:  00  00  00  00  00  00  00  00  11  20  49  04  24  06  55  03

EC 0xf0:  31  55  48  54  35  38  57  57  08  2f  45  73  07  65  6c  1a

This feature can be used to determine the register holding the fan

speed on some models. To do that, do the following:

	- make sure the battery is fully charged

	- make sure the fan is running

	- run 'cat /proc/acpi/ibm/ecdump' several times, once per second or so

The first step makes sure various charging-related values don't

vary. The second ensures that the fan-related values do vary, since

the fan speed fluctuates a bit. The third will (hopefully) mark the

fan register with a star:

[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump 

EC       +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f

EC 0x00:  a7  47  87  01  fe  96  00  08  01  00  cb  00  00  00  40  00

EC 0x10:  00  00  ff  ff  f4  3c  87  09  01  ff  42  01  ff  ff  0d  00

EC 0x20:  00  00  00  00  00  00  00  00  00  00  00  03  43  00  00  80

EC 0x30:  01  07  1a  00  30  04  00  00  85  00  00  10  00  50  00  00

EC 0x40:  00  00  00  00  00  00  14  01  00  04  00  00  00  00  00  00

EC 0x50:  00  c0  02  0d  00  01  01  02  02  03  03  03  03  bc  02  bc

EC 0x60:  02  bc  02  00  00  00  00  00  00  00  00  00  00  00  00  00

EC 0x70:  00  00  00  00  00  12  30  40  24  27  2c  27  21  80  1f  80

EC 0x80:  00  00  00  06 *be  0d  03  00  00  00  0e  07  00  00  00  00

EC 0x90:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00

EC 0xa0:  ff  09  ff  09  ff  ff  64  00  00  00  a2  41  ff  ff  e0  00

EC 0xb0:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00

EC 0xc0:  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00

EC 0xd0:  03  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00

EC 0xe0:  00  00  00  00  00  00  00  00  11  20  49  04  24  06  55  03

EC 0xf0:  31  55  48  54  35  38  57  57  08  2f  45  73  07  65  6c  1a

Another set of values that varies often is the temperature

readings. Since temperatures don't change vary fast, you can take

several quick dumps to eliminate them.

You can use a similar method to figure out the meaning of other

embedded controller registers - e.g. make sure nothing else changes

except the charging or discharging battery to determine which

registers contain the current battery capacity, etc. If you experiment

with this, do send me your results (including some complete dumps with

a description of the conditions when they were taken.)

EXPERIMENTAL: LCD brightness control -- /proc/acpi/ibm/brightness

-----------------------------------------------------------------

This feature is marked EXPERIMENTAL because the implementation

directly accesses hardware registers and may not work as expected. USE

WITH CAUTION! To use this feature, you need to supply the

experimental=1 parameter when loading the module.

This feature allows software control of the LCD brightness on ThinkPad

models which don't have a hardware brightness slider. The available

commands are:

	echo up   >/proc/acpi/ibm/brightness

	echo down >/proc/acpi/ibm/brightness

	echo 'level <level>' >/proc/acpi/ibm/brightness

The <level> number range is 0 to 7, although not all of them may be

distinct. The current brightness level is shown in the file.

EXPERIMENTAL: Volume control -- /proc/acpi/ibm/volume

-----------------------------------------------------

This feature is marked EXPERIMENTAL because the implementation

directly accesses hardware registers and may not work as expected. USE

WITH CAUTION! To use this feature, you need to supply the

experimental=1 parameter when loading the module.

This feature allows volume control on ThinkPad models which don't have

a hardware volume knob. The available commands are:

	echo up   >/proc/acpi/ibm/volume

	echo down >/proc/acpi/ibm/volume

	echo mute >/proc/acpi/ibm/volume

	echo 'level <level>' >/proc/acpi/ibm/volume

The <level> number range is 0 to 15 although not all of them may be

distinct. The unmute the volume after the mute command, use either the

up or down command (the level command will not unmute the volume).

The current volume level and mute state is shown in the file.

EXPERIMENTAL: fan speed, fan enable/disable -- /proc/acpi/ibm/fan

-----------------------------------------------------------------

This feature is marked EXPERIMENTAL because the implementation

directly accesses hardware registers and may not work as expected. USE

WITH CAUTION! To use this feature, you need to supply the

experimental=1 parameter when loading the module.

This feature attempts to show the current fan speed. The speed is read

directly from the hardware registers of the embedded controller. This

is known to work on later R, T and X series ThinkPads but may show a

bogus value on other models.

The fan may be enabled or disabled with the following commands:

	echo enable  >/proc/acpi/ibm/fan

	echo disable >/proc/acpi/ibm/fan

WARNING WARNING WARNING: do not leave the fan disabled unless you are

monitoring the temperature sensor readings and you are ready to enable

it if necessary to avoid overheating.

The fan only runs if it's enabled *and* the various temperature

sensors which control it read high enough. On the X40, this seems to

depend on the CPU and HDD temperatures. Specifically, the fan is

turned on when either the CPU temperature climbs to 56 degrees or the

HDD temperature climbs to 46 degrees. The fan is turned off when the

CPU temperature drops to 49 degrees and the HDD temperature drops to

41 degrees. These thresholds cannot currently be controlled.

On the X31 and X40 (and ONLY on those models), the fan speed can be

controlled to a certain degree. Once the fan is running, it can be

forced to run faster or slower with the following command:

	echo 'speed <speed>' > /proc/acpi/ibm/thermal

The sustainable range of fan speeds on the X40 appears to be from

about 3700 to about 7350. Values outside this range either do not have

any effect or the fan speed eventually settles somewhere in that

range. The fan cannot be stopped or started with this command.

On the 570, temperature readings are not available through this

feature and the fan control works a little differently. The fan speed

is reported in levels from 0 (off) to 7 (max) and can be controlled

with the following command:

(I've only been able to identify a couple of them).

If you try this feature, please send me a report similar to the

above. I'd like to provide this functionality in an user-friendly way,

but first I need to identify the which numbers correspond to which

sounds on various models.

	echo 'level <level>' > /proc/acpi/ibm/thermal

Multiple Command, Module Parameters

-----------------------------------

Multiple Commands, Module Parameters

------------------------------------

Multiple commands can be written to the proc files in one shot by

separating them with commas, for example:

	/usr/local/sbin/laptop_mode -- from the Linux kernel source

		distribution, see Documentation/laptop-mode.txt

	/sbin/service -- comes with Redhat/Fedora distributions

	/usr/sbin/hibernate -- from the Software Suspend 2 distribution,

		see http://softwaresuspend.berlios.de/

Toan T Nguyen <ntt@control.uchicago.edu> has written a SuSE powersave

script for the X20, included in config/usr/sbin/ibm_hotkeys_X20

Toan T Nguyen <ntt@physics.ucla.edu> notes that Suse uses the

powersave program to suspend ('powersave --suspend-to-ram') or

hibernate ('powersave --suspend-to-disk'). This means that the

hibernate script is not needed on that distribution.

Henrik Brix Andersen <brix@gentoo.org> has written a Gentoo ACPI event

handler script for the X31. You can get the latest version from

http://dev.gentoo.org/~brix/files/x31.sh

David Schweikert <dws@ee.eth.ch> has written an alternative blank.sh

script which works on Debian systems, included in

configs/etc/acpi/actions/blank-debian.sh

TODO

----

I'd like to implement the following features but haven't yet found the

time and/or I don't yet know how to implement them:

- UltraBay floppy drive support

script which works on Debian systems. This scripts has now been

extended to also work on Fedora systems and included as the default

blank.sh in the distribution.