1 files changed, 33 insertions, 150 deletions

diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt
index f2296ecedb89..aafcaa634191 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.txt
@@ -36,8 +36,6 @@ detailed description):
         - Bluetooth enable and disable
         - video output switching, expansion control
         - ThinkLight on and off
-        - limited docking and undocking
-        - UltraBay eject
         - CMOS/UCMS control
         - LED control
         - ACPI sounds
@@ -201,18 +199,22 @@ kind to allow it (and it often doesn't!).
 
 Not all bits in the mask can be modified.  Not all bits that can be
 modified do anything.  Not all hot keys can be individually controlled
-by the mask.  Some models do not support the mask at all, and in those
-models, hot keys cannot be controlled individually.  The behaviour of
-the mask is, therefore, highly dependent on the ThinkPad model.
+by the mask.  Some models do not support the mask at all.  The behaviour
+of the mask is, therefore, highly dependent on the ThinkPad model.
+
+The driver will filter out any unmasked hotkeys, so even if the firmware
+doesn't allow disabling an specific hotkey, the driver will not report
+events for unmasked hotkeys.
 
 Note that unmasking some keys prevents their default behavior.  For
 example, if Fn+F5 is unmasked, that key will no longer enable/disable
-Bluetooth by itself.
+Bluetooth by itself in firmware.
 
-Note also that not all Fn key combinations are supported through ACPI.
-For example, on the X40, the brightness, volume and "Access IBM" buttons
-do not generate ACPI events even with this driver.  They *can* be used
-through the "ThinkPad Buttons" utility, see http://www.nongnu.org/tpb/
+Note also that not all Fn key combinations are supported through ACPI
+depending on the ThinkPad model and firmware version.  On those
+ThinkPads, it is still possible to support some extra hotkeys by
+polling the "CMOS NVRAM" at least 10 times per second.  The driver
+attempts to enables this functionality automatically when required.
 
 procfs notes:
 
@@ -221,7 +223,7 @@ The following commands can be written to the /proc/acpi/ibm/hotkey file:
         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
+        echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask
 
 The following commands have been deprecated and will cause the kernel
 to log a warning:
@@ -242,9 +244,13 @@ sysfs notes:
                 Returns 0.
 
         hotkey_bios_mask:
+                DEPRECATED, DON'T USE, WILL BE REMOVED IN THE FUTURE.
+
                 Returns the hot keys mask when thinkpad-acpi was loaded.
                 Upon module unload, the hot keys mask will be restored
-                to this value.
+                to this value.   This is always 0x80c, because those are
+                the hotkeys that were supported by ancient firmware
+                without mask support.
 
         hotkey_enable:
                 DEPRECATED, WILL BE REMOVED SOON.
@@ -253,18 +259,11 @@ sysfs notes:
                 1: does nothing
 
         hotkey_mask:
-                bit mask to enable driver-handling (and depending on
+                bit mask to enable reporting (and depending on
                 the firmware, ACPI event generation) for each hot key
                 (see above).  Returns the current status of the hot keys
                 mask, and allows one to modify it.
 
-                Note: when NVRAM polling is active, the firmware mask
-                will be different from the value returned by
-                hotkey_mask.  The driver will retain enabled bits for
-                hotkeys that are under NVRAM polling even if the
-                firmware refuses them, and will not set these bits on
-                the firmware hot key mask.
-
         hotkey_all_mask:
                 bit mask that should enable event reporting for all
                 supported hot keys, when echoed to hotkey_mask above.
@@ -277,7 +276,8 @@ sysfs notes:
                 bit mask that should enable event reporting for all
                 supported hot keys, except those which are always
                 handled by the firmware anyway.  Echo it to
-                hotkey_mask above, to use.
+                hotkey_mask above, to use.  This is the default mask
+                used by the driver.
 
         hotkey_source_mask:
                 bit mask that selects which hot keys will the driver
@@ -285,9 +285,10 @@ sysfs notes:
                 based on the capabilities reported by the ACPI firmware,
                 but it can be overridden at runtime.
 
-                Hot keys whose bits are set in both hotkey_source_mask
-                and also on hotkey_mask are polled for in NVRAM.  Only a
-                few hot keys are available through CMOS NVRAM polling.
+                Hot keys whose bits are set in hotkey_source_mask are
+                polled for in NVRAM, and reported as hotkey events if
+                enabled in hotkey_mask.  Only a few hot keys are
+                available through CMOS NVRAM polling.
 
                 Warning: when in NVRAM mode, the volume up/down/mute
                 keys are synthesized according to changes in the mixer,
@@ -523,6 +524,7 @@ compatibility purposes when hotkey_report_mode is set to 1.
 0x2305          System is waking up from suspend to eject bay
 0x2404          System is waking up from hibernation to undock
 0x2405          System is waking up from hibernation to eject bay
+0x5010          Brightness level changed/control event
 
 The above events are never propagated by the driver.
 
@@ -530,7 +532,6 @@ The above events are never propagated by the driver.
 0x4003          Undocked (see 0x2x04), can sleep again
 0x500B          Tablet pen inserted into its storage bay
 0x500C          Tablet pen removed from its storage bay
-0x5010          Brightness level changed (newer Lenovo BIOSes)
 
 The above events are propagated by the driver.
 
@@ -619,6 +620,8 @@ For Lenovo models *with* ACPI backlight control:
 2. Do *NOT* load up ACPI video, enable the hotkeys in thinkpad-acpi,
    and map them to KEY_BRIGHTNESS_UP and KEY_BRIGHTNESS_DOWN.  Process
    these keys on userspace somehow (e.g. by calling xbacklight).
+   The driver will do this automatically if it detects that ACPI video
+   has been disabled.
 
 
 Bluetooth
@@ -729,131 +732,6 @@ 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
-------------------------------------------
-
-Docking and undocking (e.g. with the X4 UltraBase) requires some
-actions to be taken by the operating system to safely make or break
-the electrical connections with the dock.
-
-The docking feature of this driver generates the following ACPI events:
-
-        ibm/dock GDCK 00000003 00000001 -- eject request
-        ibm/dock GDCK 00000003 00000002 -- undocked
-        ibm/dock GDCK 00000000 00000003 -- docked
-
-NOTE: These events will only be generated if the laptop was docked
-when originally booted. This is due to the current lack of support for
-hot plugging of devices in the Linux ACPI framework. If the laptop was
-booted while not in the dock, the following message is shown in the
-logs:
-
-        Mar 17 01:42:34 aero kernel: thinkpad_acpi: dock device not present
-
-In this case, no dock-related events are generated but the dock and
-undock commands described below still work. They can be executed
-manually or triggered by Fn key combinations (see the example acpid
-configuration files included in the driver tarball package available
-on the web site).
-
-When the eject request button on the dock is pressed, the first event
-above is generated. The handler for this event should issue the
-following command:
-
-        echo undock > /proc/acpi/ibm/dock
-
-After the LED on the dock goes off, it is safe to eject the laptop.
-Note: if you pressed this key by mistake, go ahead and eject the
-laptop, then dock it back in. Otherwise, the dock may not function as
-expected.
-
-When the laptop is docked, the third event above is generated. The
-handler for this event should issue the following command to fully
-enable the dock:
-
-        echo dock > /proc/acpi/ibm/dock
-
-The contents of the /proc/acpi/ibm/dock file shows the current status
-of the dock, as provided by the ACPI framework.
-
-The docking support in this driver does not take care of enabling or
-disabling any other devices you may have attached to the dock. For
-example, a CD drive plugged into the UltraBase needs to be disabled or
-enabled separately. See the provided example acpid configuration files
-for how this can be accomplished.
-
-There is no support yet for PCI devices that may be attached to a
-docking station, e.g. in the ThinkPad Dock II. The driver currently
-does not recognize, enable or disable such devices. This means that
-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
-------------------------------------
-
-Inserting or ejecting an UltraBay device requires some actions to be
-taken by the operating system to safely make or break the electrical
-connections with the device.
-
-This feature generates the following ACPI events:
-
-        ibm/bay MSTR 00000003 00000000 -- eject request
-        ibm/bay MSTR 00000001 00000000 -- eject lever inserted
-
-NOTE: These events will only be generated if the UltraBay was present
-when the laptop was originally booted (on the X series, the UltraBay
-is in the dock, so it may not be present if the laptop was undocked).
-This is due to the current lack of support for hot plugging of devices
-in the Linux ACPI framework. If the laptop was booted without the
-UltraBay, the following message is shown in the logs:
-
-        Mar 17 01:42:34 aero kernel: thinkpad_acpi: bay device not present
-
-In this case, no bay-related events are generated but the eject
-command described below still works. It can be executed manually or
-triggered by a hot key combination.
-
-Sliding the eject lever generates the first event shown above. The
-handler for this event should take whatever actions are necessary to
-shut down the device in the UltraBay (e.g. call idectl), then issue
-the following command:
-
-        echo eject > /proc/acpi/ibm/bay
-
-After the LED on the UltraBay goes off, it is safe to pull out the
-device.
-
-When the eject lever is inserted, the second event above is
-generated. The handler for this event should take whatever actions are
-necessary to enable the UltraBay device (e.g. call idectl).
-
-The contents of the /proc/acpi/ibm/bay file shows the current status
-of the UltraBay, as provided by the ACPI framework.
-
-EXPERIMENTAL warm eject support on the 600e/x, A22p and A3x (To use
-this feature, you need to supply the experimental=1 parameter when
-loading the module):
-
-These models do not have a button near the UltraBay device to request
-a hot eject but rather require the laptop to be put to sleep
-(suspend-to-ram) before the bay device is ejected or inserted).
-The sequence of steps to eject the device is as follows:
-
-        echo eject > /proc/acpi/ibm/bay
-        put the ThinkPad to sleep
-        remove the drive
-        resume from sleep
-        cat /proc/acpi/ibm/bay should show that the drive was removed
-
-On the A3x, both the UltraBay 2000 and UltraBay Plus devices are
-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/UCMS control
 -----------------
 
@@ -1582,3 +1460,8 @@ Sysfs interface changelog:
 0x020400:       Marker for 16 LEDs support.  Also, LEDs that are known
                 to not exist in a given model are not registered with
                 the LED sysfs class anymore.
+
+0x020500:       Updated hotkey driver, hotkey_mask is always available
+                and it is always able to disable hot keys.  Very old
+                thinkpads are properly supported.  hotkey_bios_mask
+                is deprecated and marked for removal.