1 files changed, 151 insertions, 0 deletions

diff --git a/Documentation/thinkpad-acpi.txt b/Documentation/thinkpad-acpi.txt
index bd00d14538c6..91d08921a4ca 100644
--- a/Documentation/thinkpad-acpi.txt
+++ b/Documentation/thinkpad-acpi.txt
@@ -167,6 +167,17 @@ 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.
+
+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
@@ -248,6 +259,146 @@ sysfs notes:
                 disabled" postition, and 1 if the switch is in the
                 "radios enabled" position.
 
+input layer notes:
+
+A Hot key is mapped to a single input layer EV_KEY event, possibly
+followed by an EV_MSC MSC_SCAN event that shall contain that key's scan
+code.  An EV_SYN event will always be generated to mark the end of the
+event block.
+
+Do not use the EV_MSC MSC_SCAN events to process keys.  They are to be
+used as a helper to remap keys, only.  They are particularly useful when
+remapping KEY_UNKNOWN keys.
+
+The events are available in an input device, with the following id:
+
+        Bus:            BUS_HOST
+        vendor:         0x1014 (PCI_VENDOR_ID_IBM)
+        product:        0x5054 ("TP")
+        version:        0x4101
+
+The version will have its LSB incremented if the keymap changes in a
+backwards-compatible way.  The MSB shall always be 0x41 for this input
+device.  If the MSB is not 0x41, do not use the device as described in
+this section, as it is either something else (e.g. another input device
+exported by a thinkpad driver, such as HDAPS) or its functionality has
+been changed in a non-backwards compatible way.
+
+Adding other event types for other functionalities shall be considered a
+backwards-compatible change for this input device.
+
+Thinkpad-acpi Hot Key event map (version 0x4101):
+
+ACPI    Scan
+event   code    Key             Notes
+
+0x1001  0x00    FN+F1           -
+0x1002  0x01    FN+F2           -
+
+0x1003  0x02    FN+F3           Many models always report this
+                                hot key, even with hot keys
+                                disabled or with Fn+F3 masked
+                                off
+
+0x1004  0x03    FN+F4           Sleep button (ACPI sleep button
+                                semanthics, i.e. sleep-to-RAM).
+                                It is always generate some kind
+                                of event, either the hot key
+                                event or a ACPI sleep button
+                                event. The firmware may
+                                refuse to generate further FN+F4
+                                key presses until a S3 or S4 ACPI
+                                sleep cycle is performed or some
+                                time passes.
+
+0x1005  0x04    FN+F5           Radio.  Enables/disables
+                                the internal BlueTooth hardware
+                                and W-WAN card if left in control
+                                of the firmware.  Does not affect
+                                the WLAN card.
+
+0x1006  0x05    FN+F6           -
+
+0x1007  0x06    FN+F7           Video output cycle.
+                                Do you feel lucky today?
+
+0x1008  0x07    FN+F8           -
+        ..      ..              ..
+0x100B  0x0A    FN+F11          -
+
+0x100C  0x0B    FN+F12          Sleep to disk.  You are always
+                                supposed to handle it yourself,
+                                either through the ACPI event,
+                                or through a hotkey event.
+                                The firmware may refuse to
+                                generate further FN+F4 key
+                                press events until a S3 or S4
+                                ACPI sleep cycle is performed,
+                                or some time passes.
+
+0x100D  0x0C    FN+BACKSPACE    -
+0x100E  0x0D    FN+INSERT       -
+0x100F  0x0E    FN+DELETE       -
+
+0x1010  0x0F    FN+HOME         Brightness up.  This key is
+                                always handled by the firmware,
+                                even when unmasked.  Just leave
+                                it alone.
+0x1011  0x10    FN+END          Brightness down. This key is
+                                always handled by the firmware,
+                                even when unmasked.  Just leave
+                                it alone.
+0x1012  0x11    FN+PGUP         Thinklight toggle.  This key is
+                                always handled by the firmware,
+                                even when unmasked.
+
+0x1013  0x12    FN+PGDOWN       -
+
+0x1014  0x13    FN+SPACE        Zoom key
+
+0x1015  0x14    VOLUME UP       Internal mixer volume up. This
+                                key is always handled by the
+                                firmware, even when unmasked.
+0x1016  0x15    VOLUME DOWN     Internal mixer volume up. This
+                                key is always handled by the
+                                firmware, even when unmasked.
+0x1017  0x16    MUTE            Mute internal mixer. This
+                                key is always handled by the
+                                firmware, even when unmasked.
+
+0x1018  0x17    THINKPAD        Thinkpad/Access IBM/Lenovo key
+
+0x1019  0x18    unknown
+..      ..      ..
+0x1020  0x1F    unknown
+
+The ThinkPad firmware does not allow one to differentiate when most hot
+keys are pressed or released (either that, or we don't know how to, yet).
+For these keys, the driver generates a set of events for a key press and
+immediately issues the same set of events for a key release.  It is
+unknown by the driver if the ThinkPad firmware triggered these events on
+hot key press or release, but the firmware will do it for either one, not
+both.
+
+If a key is mapped to KEY_RESERVED, it generates no input events at all,
+and it may generate a legacy thinkpad-acpi ACPI hotkey event.
+
+If a key is mapped to KEY_UNKNOWN, it generates an input event that
+includes an scan code, and it may also generate a legacy thinkpad-acpi
+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
+0x7000          Radio Switch may have changed state
+
 
 Bluetooth
 ---------