Commit 336d63b8 authored by Len Brown's avatar Len Brown
Browse files

Merge branch 'thinkpad-acpi' into release

parents 07290bed 0e501834
......@@ -20,7 +20,8 @@ moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel
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.
......@@ -37,7 +38,7 @@ detailed description):
- ThinkLight on and off
- limited docking and undocking
- UltraBay eject
- CMOS control
- CMOS/UCMS control
- LED control
- ACPI sounds
- temperature sensors
......@@ -46,6 +47,7 @@ detailed description):
- 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
......@@ -53,7 +55,7 @@ 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 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
......@@ -66,17 +68,18 @@ Installation
------------
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
......@@ -111,15 +114,17 @@ 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
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
--------------
......@@ -129,6 +134,7 @@ sysfs driver attribute: version
The driver name and version. No commands can be written to this file.
Sysfs interface version
-----------------------
......@@ -160,6 +166,7 @@ expect that an attribute might not be there, and deal with it properly
(an attribute not being there *is* a valid way to make it clear that a
feature is not available in sysfs).
Hot keys
--------
......@@ -172,17 +179,14 @@ system. Enabling the hotkey functionality of thinkpad-acpi signals the
firmware that such a driver is present, and modifies how the ThinkPad
firmware will behave in many situations.
The driver enables the hot key feature automatically when loaded. The
feature can later be disabled and enabled back at runtime. The driver
will also restore the hot key feature to its previous state and mask
when it is unloaded.
The driver enables the HKEY ("hot key") event reporting automatically
when loaded, and disables it when it is removed.
When the hotkey feature is enabled and the hot key mask is set (see
below), the driver will report HKEY events in the following format:
The driver will report HKEY events in the following format:
ibm/hotkey HKEY 00000080 0000xxxx
Some of these events refer to hot key presses, but not all.
Some of these events refer to hot key presses, but not all of them.
The driver will generate events over the input layer for hot keys and
radio switches, and over the ACPI netlink layer for other events. The
......@@ -214,13 +218,17 @@ procfs notes:
The following commands can be written to the /proc/acpi/ibm/hotkey file:
echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature
echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature
echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
... any other 8-hex-digit mask ...
echo reset > /proc/acpi/ibm/hotkey -- restore the original mask
The following commands have been deprecated and will cause the kernel
to log a warning:
echo enable > /proc/acpi/ibm/hotkey -- does nothing
echo disable > /proc/acpi/ibm/hotkey -- returns an error
The procfs interface does not support NVRAM polling control. So as to
maintain maximum bug-to-bug compatibility, it does not report any masks,
nor does it allow one to manipulate the hot key mask when the firmware
......@@ -229,12 +237,9 @@ does not support masks at all, even if NVRAM polling is in use.
sysfs notes:
hotkey_bios_enabled:
Returns the status of the hot keys feature when
thinkpad-acpi was loaded. Upon module unload, the hot
key feature status will be restored to this value.
DEPRECATED, WILL BE REMOVED SOON.
0: hot keys were disabled
1: hot keys were enabled (unusual)
Returns 0.
hotkey_bios_mask:
Returns the hot keys mask when thinkpad-acpi was loaded.
......@@ -242,13 +247,10 @@ sysfs notes:
to this value.
hotkey_enable:
Enables/disables the hot keys feature in the ACPI
firmware, and reports current status of the hot keys
feature. Has no effect on the NVRAM hot key polling
functionality.
DEPRECATED, WILL BE REMOVED SOON.
0: disables the hot keys feature / feature disabled
1: enables the hot keys feature / feature enabled
0: returns -EPERM
1: does nothing
hotkey_mask:
bit mask to enable driver-handling (and depending on
......@@ -618,6 +620,7 @@ For Lenovo models *with* ACPI backlight control:
and map them to KEY_BRIGHTNESS_UP and KEY_BRIGHTNESS_DOWN. Process
these keys on userspace somehow (e.g. by calling xbacklight).
Bluetooth
---------
......@@ -628,6 +631,9 @@ sysfs rfkill class: switch "tpacpi_bluetooth_sw"
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:
......@@ -652,6 +658,7 @@ Sysfs notes:
rfkill controller switch "tpacpi_bluetooth_sw": refer to
Documentation/rfkill.txt for details.
Video output control -- /proc/acpi/ibm/video
--------------------------------------------
......@@ -693,11 +700,8 @@ Fn-F7 from working. This also disables the video output switching
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
------------------
......@@ -720,10 +724,11 @@ The ThinkLight sysfs interface is documented by the LED class
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
------------------------------------------
......@@ -784,6 +789,7 @@ the only docking stations currently supported are the X-series
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
------------------------------------
......@@ -847,8 +853,9 @@ supported. Use "eject2" instead of "eject" for the second 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
......@@ -882,6 +889,7 @@ The cmos command interface is prone to firmware split-brain problems, as
in newer ThinkPads it is just a compatibility layer. Do not use it, it is
exported just as a debug tool.
LED control
-----------
......@@ -893,6 +901,17 @@ some older ThinkPad models, it is possible to query the status of the
LED indicators as well. Newer ThinkPads cannot query the real status
of the LED indicators.
Because misuse of the LEDs could induce an unaware user to perform
dangerous actions (like undocking or ejecting a bay device while the
buses are still active), or mask an important alarm (such as a nearly
empty battery, or a broken battery), access to most LEDs is
restricted.
Unrestricted access to all LEDs requires that thinkpad-acpi be
compiled with the CONFIG_THINKPAD_ACPI_UNSAFE_LEDS option enabled.
Distributions must never enable this option. Individual users that
are aware of the consequences are welcome to enabling it.
procfs notes:
The available commands are:
......@@ -939,6 +958,7 @@ ThinkPad indicator LED should blink in hardware accelerated mode, use the
"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
----------------------------------
......@@ -968,6 +988,7 @@ X40:
16 - one medium-pitched beep repeating constantly, stop with 17
17 - stop 16
Temperature sensors
-------------------
......@@ -1115,6 +1136,7 @@ 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.)
LCD brightness control
----------------------
......@@ -1124,10 +1146,9 @@ sysfs backlight device "thinkpad_screen"
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
......@@ -1136,10 +1157,15 @@ display backlight brightness control methods have 16 levels, ranging
from 0 to 15.
There are two interfaces to the firmware for direct brightness control,
EC and CMOS. To select which one should be used, use the
EC and UCMS (or CMOS). To select which one should be used, use the
brightness_mode module parameter: brightness_mode=1 selects EC mode,
brightness_mode=2 selects CMOS mode, brightness_mode=3 selects both EC
and CMOS. The driver tries to auto-detect which interface to use.
brightness_mode=2 selects UCMS mode, brightness_mode=3 selects EC
mode with NVRAM backing (so that brightness changes are remembered
across shutdown/reboot).
The driver tries to select which interface to use from a table of
defaults for each ThinkPad model. If it makes a wrong choice, please
report this as a bug, so that we can fix it.
When display backlight brightness controls are available through the
standard ACPI interface, it is best to use it instead of this direct
......@@ -1201,6 +1227,7 @@ WARNING:
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
---------------------------------------
......@@ -1217,6 +1244,11 @@ 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.
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
---------------------------------------------------------
......@@ -1383,8 +1415,11 @@ procfs: /proc/acpi/ibm/wan
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.
......@@ -1413,6 +1448,7 @@ Sysfs notes:
rfkill controller switch "tpacpi_wwan_sw": refer to
Documentation/rfkill.txt for details.
EXPERIMENTAL: UWB
-----------------
......@@ -1431,6 +1467,7 @@ Sysfs notes:
rfkill controller switch "tpacpi_uwb_sw": refer to
Documentation/rfkill.txt for details.
Multiple Commands, Module Parameters
------------------------------------
......@@ -1445,6 +1482,7 @@ for example:
modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
Enabling debugging output
-------------------------
......@@ -1457,8 +1495,15 @@ will enable all debugging output classes. It takes a bitmask, so
to enable more than one output class, just add their values.
Debug bitmask Description
0x8000 Disclose PID of userspace programs
accessing some functions of the driver
0x0001 Initialization and probing
0x0002 Removal
0x0004 RF Transmitter control (RFKILL)
(bluetooth, WWAN, UWB...)
0x0008 HKEY event interface, hotkeys
0x0010 Fan control
0x0020 Backlight brightness
There is also a kernel build option to enable more debugging
information, which may be necessary to debug driver problems.
......@@ -1467,6 +1512,7 @@ The level of debugging information output by the driver can be changed
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
-----------------------
......@@ -1505,3 +1551,7 @@ Sysfs interface changelog:
0x020200: Add poll()/select() support to the following attributes:
hotkey_radio_sw, wakeup_hotunplug_complete, wakeup_reason
0x020300: hotkey enable/disable support removed, attributes
hotkey_bios_enabled and hotkey_enable deprecated and
marked for removal.
......@@ -226,6 +226,30 @@ config THINKPAD_ACPI_DEBUG
If you are not sure, say N here.
config THINKPAD_ACPI_UNSAFE_LEDS
bool "Allow control of important LEDs (unsafe)"
depends on THINKPAD_ACPI
default n
---help---
Overriding LED state on ThinkPads can mask important
firmware alerts (like critical battery condition), or misled
the user into damaging the hardware (undocking or ejecting
the bay while buses are still active), etc.
LED control on the ThinkPad is write-only (with very few
exceptions on very ancient models), which makes it
impossible to know beforehand if important information will
be lost when one changes LED state.
Users that know what they are doing can enable this option
and the driver will allow control of every LED, including
the ones on the dock stations.
Never enable this option on a distribution kernel.
Say N here, unless you are building a kernel for your own
use, and need to control the important firmware LEDs.
config THINKPAD_ACPI_DOCK
bool "Legacy Docking Station Support"
depends on THINKPAD_ACPI
......
This diff is collapsed.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment