1 files changed, 97 insertions, 47 deletions

diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt
index 41bc99fa1884..3d7650768bb5 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.txt
@@ -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.