ACPI: thinkpad-acpi: make the input event mode the default

Make the input layer the default way to deal with thinkpad-acpi hot keys,
but add a kernel config option to retain the old way of doing things.

This means we map a lot more keys to useful stuff by default, and also that
we enable hot key handling by default on driver load (like Windows does).

The documentation for proper use of this resource is also updated.

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Cc: Richard Hughes <hughsient@gmail.com>
Signed-off-by: Len Brown <len.brown@intel.com>

1 files changed, 41 insertions, 48 deletions

diff --git a/Documentation/thinkpad-acpi.txt b/Documentation/thinkpad-acpi.txt
index 91d08921a4ca..5b59cf50b2e9 100644
--- a/Documentation/thinkpad-acpi.txt
+++ b/Documentation/thinkpad-acpi.txt
@@ -155,52 +155,47 @@ Hot keys
 procfs: /proc/acpi/ibm/hotkey
 sysfs device attribute: hotkey_*
 
-Without this driver, only the Fn-F4 key (sleep button) generates an
-ACPI event. With the driver loaded, the hotkey feature enabled and the
-mask set (see below), the various hot keys generate ACPI events in the
+In a ThinkPad, the ACPI HKEY handler is responsible for comunicating
+some important events and also keyboard hot key presses to the operating
+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.
+
+When the hotkey feature is enabled and the hot key mask is set (see
+below), the various hot keys either generate ACPI events in the
 following format:
 
         ibm/hotkey HKEY 00000080 0000xxxx
 
-The last four digits vary depending on the key combination pressed.
-All labeled Fn-Fx key combinations generate distinct events. In
-addition, the lid microswitch and some docking station buttons may
-also generate such events.
-
-Hot keys also generate regular keyboard key press/release events through
-the input layer in addition to the ibm/hotkey ACPI events.  The input
-layer support accepts the standard IOCTLs to remap the keycodes assigned
-to each hotkey.
+or events over the input layer.  The input layer support accepts the
+standard IOCTLs to remap the keycodes assigned to each hotkey.
 
 When the input device is open, the driver will suppress any ACPI hot key
 events that get translated into a meaningful input layer event, in order
 to avoid sending duplicate events to userspace.  Hot keys that are
-mapped to KEY_RESERVED are not translated, and will always generate only
-ACPI hot key event, and no input layer events.
-
-The bit mask allows some control over which hot keys generate ACPI
-events. 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. On those
-models, hot keys cannot be controlled individually.
-
-Note that enabling ACPI events for some keys prevents their default
-behavior. For example, if events for Fn-F5 are enabled, that key will no
-longer enable/disable Bluetooth by itself. This can still be done from
-an acpid handler for the ibm/hotkey event.
-
-On some models, even enabling/disabling the entire hot key feature may
-change the way some keys behave (e.g. in a T43, Fn+F4 will generate an
-button/sleep ACPI event if hot keys are disabled, and it will ignore its
-mask when hot keys are enabled, so the key always does something.  On a
-X40, Fn+F4 respects its mask status, but generates the button/sleep ACPI
-event if masked off).
-
-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/
+mapped to KEY_RESERVED in the keymap are not translated, and will always
+generate an ACPI ibm/hotkey HKEY event, and no input layer events.
+
+The hot key bit mask allows some control over which hot keys generate
+events.  If a key is "masked" (bit set to 0 in the mask), the firmware
+will handle it.  If it is "unmasked", it signals the firmware that
+thinkpad-acpi would prefer to handle it, if the firmware would be so
+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, higly dependent on the ThinkPad model.
+
+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.
+
+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/
 
 procfs notes:
 
@@ -221,7 +216,7 @@ sysfs notes:
                 key feature status will be restored to this value.
 
                 0: hot keys were disabled
-                1: hot keys were enabled
+                1: hot keys were enabled (unusual)
 
         hotkey_bios_mask:
                 Returns the hot keys mask when thinkpad-acpi was loaded.
@@ -236,9 +231,10 @@ sysfs notes:
                 1: enables the hot keys feature / feature enabled
 
         hotkey_mask:
-                bit mask to enable ACPI event generation for each hot
-                key (see above).  Returns the current status of the hot
-                keys mask, and allows one to modify it.
+                bit mask to enable driver-handling and ACPI event
+                generation for each hot key (see above).  Returns the
+                current status of the hot keys mask, and allows one to
+                modify it.
 
         hotkey_all_mask:
                 bit mask that should enable event reporting for all
@@ -250,8 +246,9 @@ sysfs notes:
 
         hotkey_recommended_mask:
                 bit mask that should enable event reporting for all
-                supported hot keys, except those which are handled by
-                the firmware.  Echo it to hotkey_mask above, to use.
+                supported hot keys, except those which are always
+                handled by the firmware anyway.  Echo it to
+                hotkey_mask above, to use.
 
         hotkey_radio_sw:
                 if the ThinkPad has a hardware radio switch, this
@@ -390,10 +387,6 @@ ACPI hotkey event.
 If a key is mapped to anything else, it will only generate legacy
 thinkpad-acpi ACPI hotkey events if nobody has opened the input device.
 
-For userspace backwards-compatibility purposes, the keycode map is
-initially filled with KEY_RESERVED and KEY_UNKNOWN mappings for scan codes
-0x00 to 0x10 (and maybe others).
-
 Non hot-key ACPI HKEY event map:
 0x5001          Lid closed
 0x5002          Lid opened