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.
-
-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/
+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 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:
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.
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
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
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.
+
+Non hot-key ACPI HKEY event map:
+0x5001 Lid closed
+0x5002 Lid opened
+0x7000 Radio Switch may have changed state
+
Bluetooth
---------
procfs: /proc/acpi/ibm/cmos
sysfs device attribute: cmos_command
-This feature is used internally by the ACPI firmware to control the
-ThinkLight on most newer ThinkPad models. It may also control LCD
-brightness, sounds volume and more, but only on some models.
+This feature is mostly used internally by the ACPI firmware to keep the legacy
+CMOS NVRAM bits in sync with the current machine state, and to record this
+state so that the ThinkPad will retain such settings across reboots.
+
+Some of these commands actually perform actions in some ThinkPad models, but
+this is expected to disappear more and more in newer models. As an example, in
+a T43 and in a X40, commands 12 and 13 still control the ThinkLight state for
+real, but commands 0 to 2 don't control the mixer anymore (they have been
+phased out) and just update the NVRAM.
The range of valid cmos command numbers is 0 to 21, but not all have an
effect and the behavior varies from model to model. Here is the behavior
on the X40 (tpb is the ThinkPad Buttons utility):
- 0 - no effect but tpb reports "Volume down"
- 1 - no effect but tpb reports "Volume up"
- 2 - no effect but tpb reports "Mute on"
- 3 - simulate pressing the "Access IBM" button
- 4 - LCD brightness up
- 5 - LCD brightness down
- 11 - toggle screen expansion
- 12 - ThinkLight on
- 13 - ThinkLight off
- 14 - no effect but tpb reports ThinkLight status change
+ 0 - Related to "Volume down" key press
+ 1 - Related to "Volume up" key press
+ 2 - Related to "Mute on" key press
+ 3 - Related to "Access IBM" key press
+ 4 - Related to "LCD brightness up" key pess
+ 5 - Related to "LCD brightness down" key press
+ 11 - Related to "toggle screen expansion" key press/function
+ 12 - Related to "ThinkLight on"
+ 13 - Related to "ThinkLight off"
+ 14 - Related to "ThinkLight" key press (toggle thinklight)
The cmos command interface is prone to firmware split-brain problems, as
-in newer ThinkPads it is just a compatibility layer.
+in newer ThinkPads it is just a compatibility layer. Do not use it, it is
+exported just as a debug tool.
LED control -- /proc/acpi/ibm/led
---------------------------------