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

		     ThinkPad ACPI Extras Driver

                            Version 0.25
                        October 16th,  2013

               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 correctly process all errors (the sysfs
interface makes extensive use of errors).  File descriptors and open /
close operations to the sysfs inodes must also be properly implemented.

The version of thinkpad-acpi's sysfs interface is exported by the driver
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
/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/.

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", or
better yet, through libsensors.


Driver version
--------------

procfs: /proc/acpi/ibm/driver
sysfs driver attribute: version

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


Sysfs interface version
-----------------------

sysfs driver attribute: interface_version

Version of the thinkpad-acpi sysfs interface, as an unsigned long
(output in hex format: 0xAAAABBCC), where:
	AAAA - major revision
	BB - minor revision
	CC - bugfix revision

The sysfs interface version changelog for the driver can be found at the
end of this document.  Changes to the sysfs interface done by the kernel
subsystems are not documented here, nor are they tracked by this
attribute.

Changes to the thinkpad-acpi sysfs interface are only considered
non-experimental when they are submitted to Linux mainline, at which
point the changes in this interface are documented and interface_version
may be updated.  If you are using any thinkpad-acpi features not yet
sent to mainline for merg