ThinkPad ACPI Extras Driver
- Version 0.14
- April 21st, 2007
+ Version 0.15
+ July 1st, 2007
Borislav Deianov <borislav@users.sf.net>
- Henrique de Moraes Holschuh <hmh@hmh.eng.br>
- http://ibm-acpi.sf.net/
+ Henrique de Moraes Holschuh <hmh@hmh.eng.br>
+ http://ibm-acpi.sf.net/
This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
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:
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
The events are available in an input device, with the following id:
Bus: BUS_HOST
- vendor: 0x1014 (PCI_VENDOR_ID_IBM)
+ vendor: 0x1014 (PCI_VENDOR_ID_IBM) or
+ 0x17aa (PCI_VENDOR_ID_LENOVO)
product: 0x5054 ("TP")
version: 0x4101
event code Key Notes
0x1001 0x00 FN+F1 -
-0x1002 0x01 FN+F2 -
+0x1002 0x01 FN+F2 IBM: battery (rare)
+ Lenovo: Screen lock
-0x1003 0x02 FN+F3 Many models always report this
- hot key, even with hot keys
+0x1003 0x02 FN+F3 Many IBM models always report
+ this hot key, even with hot keys
disabled or with Fn+F3 masked
off
+ IBM: screen lock
+ Lenovo: battery
0x1004 0x03 FN+F4 Sleep button (ACPI sleep button
semanthics, i.e. sleep-to-RAM).
and W-WAN card if left in control
of the firmware. Does not affect
the WLAN card.
+ Should be used to turn on/off all
+ radios (bluetooth+W-WAN+WLAN),
+ really.
0x1006 0x05 FN+F6 -
0x1007 0x06 FN+F7 Video output cycle.
Do you feel lucky today?
-0x1008 0x07 FN+F8 -
+0x1008 0x07 FN+F8 IBM: toggle screen expand
+ Lenovo: configure ultranav
+
+0x1009 0x08 FN+F9 -
.. .. ..
0x100B 0x0A FN+F11 -
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.
+ always handled by the firmware
+ in IBM ThinkPads, even when
+ unmasked. Just leave it alone.
+ For Lenovo ThinkPads with a new
+ BIOS, it has to be handled either
+ by the ACPI OSI, or by userspace.
+0x1011 0x10 FN+END Brightness down. See brightness
+ up for details.
+
0x1012 0x11 FN+PGUP Thinklight toggle. This key is
always handled by the firmware,
even when unmasked.
0x1015 0x14 VOLUME UP Internal mixer volume up. This
key is always handled by the
firmware, even when unmasked.
+ NOTE: Lenovo seems to be changing
+ this.
0x1016 0x15 VOLUME DOWN Internal mixer volume up. This
key is always handled by the
firmware, even when unmasked.
+ NOTE: Lenovo seems to be changing
+ this.
0x1017 0x16 MUTE Mute internal mixer. This
key is always handled by the
firmware, even when unmasked.
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
procfs: /proc/acpi/ibm/thermal
sysfs device attributes: (hwmon) temp*_input
-Most ThinkPads include six or more separate temperature sensors but
-only expose the CPU temperature through the standard ACPI methods.
-This feature shows readings from up to eight different sensors on older
-ThinkPads, and it has experimental support for up to sixteen different
-sensors on newer ThinkPads.
-
-EXPERIMENTAL: The 16-sensors feature is marked EXPERIMENTAL because the
-implementation directly accesses hardware registers and may not work as
-expected. USE WITH CAUTION! To use this feature, you need to supply the
-experimental=1 parameter when loading the module. When EXPERIMENTAL
-mode is enabled, reading the first 8 sensors on newer ThinkPads will
-also use an new experimental thermal sensor access mode.
+Most ThinkPads include six or more separate temperature sensors but only
+expose the CPU temperature through the standard ACPI methods. This
+feature shows readings from up to eight different sensors on older
+ThinkPads, and up to sixteen different sensors on newer ThinkPads.
For example, on the X40, a typical output may be:
temperatures: 42 42 45 41 36 -128 33 -128
-EXPERIMENTAL: On the T43/p, a typical output may be:
+On the T43/p, a typical output may be:
temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
The mapping of thermal sensors to physical locations varies depending on
The backlight control has eight levels, ranging from 0 to 7. Some of the
levels may not be distinct.
+There are two interfaces to the firmware for brightness control, EC and 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 autodetect
+which interface to use.
+
Procfs notes:
The available commands are:
device.
0x000200: Hot key support for 32 hot keys, and radio slider switch
support.
+0x010000: Hot keys are now handled by default over the input
+ layer, the radio switch generates input event EV_RADIO,
+ and the driver enables hot key handling by default in
+ the firmware.