thinkpad-acpi: documentation cleanup

kernel 2.6.29 and release 0.22.

The driver is named "thinkpad-acpi".  In some places, like module

names, "thinkpad_acpi" is used because of userspace issues.

names and log messages, "thinkpad_acpi" is used because of userspace

issues.

"tpacpi" is used as a shorthand where "thinkpad-acpi" would be too

long due to length limitations on some Linux kernel versions.

	- ThinkLight on and off

	- limited docking and undocking

	- UltraBay eject

	- CMOS control

	- CMOS/UCMS control

	- LED control

	- ACPI sounds

	- temperature sensors

	- Volume control

	- Fan control and monitoring: fan speed, fan enable/disable

	- WAN enable and disable

	- UWB enable and 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

Please include the following information in your report:

	- ThinkPad model name

	- a copy of your DSDT, from /proc/acpi/dsdt

	- a copy of your ACPI tables, using the "acpidump" utility

	- a copy of the output of dmidecode, with serial numbers

	  and UUIDs masked off

	- which driver features work and which don't

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

If you are compiling this driver as included in the Linux kernel

sources, simply enable the CONFIG_THINKPAD_ACPI option, and optionally

enable the CONFIG_THINKPAD_ACPI_BAY option if you want the

thinkpad-specific bay functionality.

sources, look for the CONFIG_THINKPAD_ACPI Kconfig option.

It is located on the menu path: "Device Drivers" -> "X86 Platform

Specific Device Drivers" -> "ThinkPad ACPI Laptop Extras".

Features

--------

The driver exports two different interfaces to userspace, which can be

used to access the features it provides.  One is a legacy procfs-based

interface, which will be removed at some time in the distant future.

The other is a new sysfs-based interface which is not complete yet.

interface, which will be removed at some time in the future.  The other

is a new sysfs-based interface which is not complete yet.

The procfs interface creates the /proc/acpi/ibm directory.  There is a

file under that directory for each feature it supports.  The procfs

as a driver attribute (see below).

Sysfs driver attributes are on the driver's sysfs attribute space,

for 2.6.23 this is /sys/bus/platform/drivers/thinkpad_acpi/ and

for 2.6.23+ this is /sys/bus/platform/drivers/thinkpad_acpi/ and

/sys/bus/platform/drivers/thinkpad_hwmon/

Sysfs device attributes are on the thinkpad_acpi device sysfs attribute

space, for 2.6.23 this is /sys/devices/platform/thinkpad_acpi/.

space, for 2.6.23+ this is /sys/devices/platform/thinkpad_acpi/.

Sysfs device attributes for the sensors and fan are on the

thinkpad_hwmon device's sysfs attribute space, but you should locate it

looking for a hwmon device with the name attribute of "thinkpad".

looking for a hwmon device with the name attribute of "thinkpad", or

better yet, through libsensors.

Driver version

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

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

Sysfs interface version

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

(an attribute not being there *is* a valid way to make it clear that a

feature is not available in sysfs).

Hot keys

--------

   and map them to KEY_BRIGHTNESS_UP and KEY_BRIGHTNESS_DOWN.  Process

   these keys on userspace somehow (e.g. by calling xbacklight).

Bluetooth

---------

This feature shows the presence and current state of a ThinkPad

Bluetooth device in the internal ThinkPad CDC slot.

If the ThinkPad supports it, the Bluetooth state is stored in NVRAM,

so it is kept across reboots and power-off.

Procfs notes:

If Bluetooth is installed, the following commands can be used:

	rfkill controller switch "tpacpi_bluetooth_sw": refer to

	Documentation/rfkill.txt for details.

Video output control -- /proc/acpi/ibm/video

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

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:

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

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

ThinkLight control

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

documentation, in Documentation/leds-class.txt.  The ThinkLight LED name

is "tpacpi::thinklight".

Due to limitations in the sysfs LED class, if the status of the thinklight

Due to limitations in the sysfs LED class, if the status of the ThinkLight

cannot be read or if it is unknown, thinkpad-acpi will report it as "off".

It is impossible to know if the status returned through sysfs is valid.

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

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

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

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

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

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

CMOS control

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

CMOS/UCMS control

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

procfs: /proc/acpi/ibm/cmos

sysfs device attribute: cmos_command

in newer ThinkPads it is just a compatibility layer.  Do not use it, it is

exported just as a debug tool.

LED control

-----------

"timer" trigger, and leave the delay_on and delay_off parameters set to

zero (to request hardware acceleration autodetection).

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

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

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

	17 - stop 16

Temperature sensors

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

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

a description of the conditions when they were taken.)

LCD brightness control

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

This feature allows software control of the LCD brightness on ThinkPad

models which don't have a hardware brightness slider.

It has some limitations: the LCD backlight cannot be actually turned on or

off by this interface, and in many ThinkPad models, the "dim while on

battery" functionality will be enabled by the BIOS when this interface is

used, and cannot be controlled.

It has some limitations: the LCD backlight cannot be actually turned

on or off by this interface, it just controls the backlight brightness

level.

On IBM (and some of the earlier Lenovo) ThinkPads, the backlight control

has eight brightness levels, ranging from 0 to 7.  Some of the levels

    and maybe reduce the life of the backlight lamps by needlessly kicking

    its level up and down at every change.

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

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

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

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

The ALSA mixer interface to this feature is still missing, but patches

to add it exist.  That problem should be addressed in the not so

distant future.

Fan control and monitoring: fan speed, fan enable/disable

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

sysfs device attribute: wwan_enable (deprecated)

sysfs rfkill class: switch "tpacpi_wwan_sw"

This feature shows the presence and current state of a W-WAN (Sierra

Wireless EV-DO) device.

This feature shows the presence and current state of the built-in

Wireless WAN device.

If the ThinkPad supports it, the WWAN state is stored in NVRAM,

so it is kept across reboots and power-off.

It was tested on a Lenovo ThinkPad X60. It should probably work on other

ThinkPad models which come with this module installed.

	rfkill controller switch "tpacpi_wwan_sw": refer to

	Documentation/rfkill.txt for details.

EXPERIMENTAL: UWB

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

	rfkill controller switch "tpacpi_uwb_sw": refer to

	Documentation/rfkill.txt for details.

Multiple Commands, Module Parameters

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

	modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable

Enabling debugging output

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

at runtime through sysfs, using the driver attribute debug_level.  The

attribute takes the same bitmask as the debug module parameter above.

Force loading of module

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