path: root/Documentation/laptops/thinkpad-acpi.txt

		     ThinkPad ACPI Extras Driver

                            Version 0.24
                        December 11th,  2009

               Borislav Deianov <borislav@users.sf.net>
             Henrique de Moraes Holschuh <hmh@hmh.eng.br>
                      http://ibm-acpi.sf.net/


This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
supports various features of these laptops which are accessible
through the ACPI and ACPI EC framework, but not otherwise fully
supported by the generic Linux ACPI drivers.

This driver used to be named ibm-acpi until kernel 2.6.21 and release
0.13-20070314.  It used to be in the drivers/acpi tree, but it was
moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel
2.6.22, and release 0.14.  It was moved to drivers/platform/x86 for
kernel 2.6.29 and release 0.22.

The driver is named "thinkpad-acpi".  In some places, like module
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.

Status
------

The features currently supported are the following (see below for
detailed description):

	- Fn key combinations
	- Bluetooth enable and disable
	- video output switching, expansion control
	- ThinkLight on and off
	- CMOS/UCMS control
	- LED control
	- ACPI sounds
	- temperature sensors
	- Experimental: embedded controller register dump
	- LCD brightness control
	- 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
reports, especially if they add to or correct the compatibility table.
Please include the following information in your report:

	- ThinkPad model name
	- 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
	- the observed behavior of non-working features

Any other comments or patches are also more than welcome.


Installation
------------

If you are compiling this driver as included in the Linux kernel
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 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
interface is mostly frozen, and will change very little if at all: it
will not be extended to add any new functionality in the driver, instead
all new functionality will be implemented on the sysfs interface.

The sysfs interface tries to blend in the generic Linux sysfs subsystems
and classes as much as possible.  Since some of these subsystems are not
yet ready or stabilized, it is expected that this interface will change,
and any and all userspace programs must deal with it.


Notes about the sysfs interface:

Unlike what was done with the procfs interface, correctness when talking
to the sysfs interfaces will be enforced, as will correctness in the
thinkpad-acpi's implementation of sysfs interfaces.

Also, any bugs in the thinkpad-acpi sysfs driver code or in the
thinkpad-acpi's implementation of the sysfs interfaces will be fixed for
maximum correctness, even if that means changing an interface in
non-compatible ways.  As these interfaces mature both in the kernel and
in thinkpad-acpi, such changes should become quite rare.

Applications interfacing to the thinkpad-acpi sysfs interfaces must
follow all sysfs guidelines and correc