- Experimental: embedded controller register dump
- LCD brightness control
- Volume control
- - Experimental: fan speed, fan enable/disable
+ - Fan control and monitoring: fan speed, fan enable/disable
- Experimental: WAN enable and disable
A compatibility table by model and feature is maintained on the web
subsystems are not documented here, nor are they tracked by this
attribute.
-Hot keys -- /proc/acpi/ibm/hotkey
----------------------------------
+Changes to the thinkpad-acpi sysfs interface are only considered
+non-experimental when they are submitted to Linux mainline, at which
+point the changes in this interface are documented and interface_version
+may be updated. If you are using any thinkpad-acpi features not yet
+sent to mainline for merging, you do so on your own risk: these features
+may disappear, or be implemented in a different and incompatible way by
+the time they are merged in Linux mainline.
+
+Changes that are backwards-compatible by nature (e.g. the addition of
+attributes that do not change the way the other attributes work) do not
+always warrant an update of interface_version. Therefore, one must
+expect that an attribute might not be there, and deal with it properly
+(an attribute not being there *is* a valid way to make it clear that a
+feature is not available in sysfs).
+
+Hot keys
+--------
+
+procfs: /proc/acpi/ibm/hotkey
+sysfs device attribute: hotkey_*
+
+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.
-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
+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.
+or events over the input layer. The input layer support accepts the
+standard IOCTLs to remap the keycodes assigned to each hotkey.
-The following commands can be written to this file:
+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.
- echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature
- echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature
- echo 0xffff > /proc/acpi/ibm/hotkey -- enable all possible hot keys
- echo 0x0000 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
- ... any other 4-hex-digit mask ...
- echo reset > /proc/acpi/ibm/hotkey -- restore the original mask
+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!).
-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. Most recent ThinkPad models honor the
-following bits (assuming the hot keys feature has been enabled):
+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.
- key bit behavior when set behavior when unset
+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.
- Fn-F3 always generates ACPI event
- Fn-F4 always generates ACPI event
- Fn-F5 0010 generate ACPI event enable/disable Bluetooth
- Fn-F7 0040 generate ACPI event switch LCD and external display
- Fn-F8 0080 generate ACPI event expand screen or none
- Fn-F9 0100 generate ACPI event none
- Fn-F12 always generates ACPI event
+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/
-Some models do not support all of the above. For example, the T30 does
-not support Fn-F5 and Fn-F9. Other models do not support the mask at
-all. On those models, hot keys cannot be controlled individually.
+procfs notes:
-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.
+The following commands can be written to the /proc/acpi/ibm/hotkey file:
-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/
+ echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature
+ echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature
+ 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
-Bluetooth -- /proc/acpi/ibm/bluetooth
--------------------------------------
+sysfs notes:
+
+ hotkey_bios_enabled:
+ Returns the status of the hot keys feature when
+ thinkpad-acpi was loaded. Upon module unload, the hot
+ key feature status will be restored to this value.
+
+ 0: hot keys were disabled
+ 1: hot keys were enabled (unusual)
+
+ hotkey_bios_mask:
+ Returns the hot keys mask when thinkpad-acpi was loaded.
+ Upon module unload, the hot keys mask will be restored
+ to this value.
+
+ hotkey_enable:
+ Enables/disables the hot keys feature, and reports
+ current status of the hot keys feature.
+
+ 0: disables the hot keys feature / feature disabled
+ 1: enables the hot keys feature / feature enabled
+
+ hotkey_mask:
+ 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
+ supported hot keys, when echoed to hotkey_mask above.
+ Unless you know which events need to be handled
+ passively (because the firmware *will* handle them
+ anyway), do *not* use hotkey_all_mask. Use
+ hotkey_recommended_mask, instead. You have been warned.
+
+ hotkey_recommended_mask:
+ 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_radio_sw:
+ if the ThinkPad has a hardware radio switch, this
+ attribute will read 0 if the switch is in the "radios
+ 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/bluetooth
+sysfs device attribute: bluetooth_enable
+
+This feature shows the presence and current state of a ThinkPad
+Bluetooth device in the internal ThinkPad CDC slot.
-This feature shows the presence and current state of a Bluetooth
-device. If Bluetooth is installed, the following commands can be used:
+Procfs notes:
+
+If Bluetooth is installed, the following commands can be used:
echo enable > /proc/acpi/ibm/bluetooth
echo disable > /proc/acpi/ibm/bluetooth
+Sysfs notes:
+
+ If the Bluetooth CDC card is installed, it can be enabled /
+ disabled through the "bluetooth_enable" thinkpad-acpi device
+ attribute, and its current status can also be queried.
+
+ enable:
+ 0: disables Bluetooth / Bluetooth is disabled
+ 1: enables Bluetooth / Bluetooth is enabled.
+
+ Note: this interface will be probably be superseeded by the
+ generic rfkill class, so it is NOT to be considered stable yet.
+
Video output control -- /proc/acpi/ibm/video
--------------------------------------------
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
---------------------------------
2: System board, left side (near PCMCIA slot), reported as HDAPS temp
3: PCMCIA slot
9: MCH (northbridge) to DRAM Bus
-10: ICH (southbridge), under Mini-PCI card, under touchpad
+10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
+ card, under touchpad
11: Power regulator, underside of system board, below F2 key
The A31 has a very atypical layout for the thermal sensors
with this, do send me your results (including some complete dumps with
a description of the conditions when they were taken.)
-LCD brightness control -- /proc/acpi/ibm/brightness
----------------------------------------------------
+LCD brightness control
+----------------------
+
+procfs: /proc/acpi/ibm/brightness
+sysfs backlight device "thinkpad_screen"
This feature allows software control of the LCD brightness on ThinkPad
-models which don't have a hardware brightness slider. The available
-commands are:
+models which don't have a hardware brightness slider.
+
+It has some limitations: the LCD backlight cannot be actually turned on or off
+by this interface, and in many ThinkPad models, the "dim while on battery"
+functionality will be enabled by the BIOS when this interface is used, and
+cannot be controlled.
+
+The backlight control has eight levels, ranging from 0 to 7. Some of the
+levels may not be distinct.
+
+Procfs notes:
+
+ The available commands are:
echo up >/proc/acpi/ibm/brightness
echo down >/proc/acpi/ibm/brightness
echo 'level <level>' >/proc/acpi/ibm/brightness
-The <level> number range is 0 to 7, although not all of them may be
-distinct. The current brightness level is shown in the file.
+Sysfs notes:
+
+The interface is implemented through the backlight sysfs class, which is poorly
+documented at this time.
+
+Locate the thinkpad_screen device under /sys/class/backlight, and inside it
+there will be the following attributes:
+
+ max_brightness:
+ Reads the maximum brightness the hardware can be set to.
+ The minimum is always zero.
+
+ actual_brightness:
+ Reads what brightness the screen is set to at this instant.
+
+ brightness:
+ Writes request the driver to change brightness to the given
+ value. Reads will tell you what brightness the driver is trying
+ to set the display to when "power" is set to zero and the display
+ has not been dimmed by a kernel power management event.
+
+ power:
+ power management mode, where 0 is "display on", and 1 to 3 will
+ dim the display backlight to brightness level 0 because
+ thinkpad-acpi cannot really turn the backlight off. Kernel
+ power management events can temporarily increase the current
+ power management level, i.e. they can dim the display.
+
Volume control -- /proc/acpi/ibm/volume
---------------------------------------
up or down command (the level command will not unmute the volume).
The current volume level and mute state is shown in the file.
-EXPERIMENTAL: fan speed, fan enable/disable
--------------------------------------------
+Fan control and monitoring: fan speed, fan enable/disable
+---------------------------------------------------------
procfs: /proc/acpi/ibm/fan
sysfs device attributes: (hwmon) fan_input, pwm1, pwm1_enable
-This 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.
+NOTE NOTE NOTE: fan control operations are disabled by default for
+safety reasons. To enable them, the module parameter "fan_control=1"
+must be given to thinkpad-acpi.
This feature attempts to show the current fan speed, control mode and
other fan data that might be available. The speed is read directly
from the hardware registers of the embedded controller. This is known
-to work on later R, T and X series ThinkPads but may show a bogus
+to work on later R, T, X and Z series ThinkPads but may show a bogus
value on other models.
Fan levels:
The sysfs interface follows the hwmon subsystem guidelines for the most
part, and the exception is the fan safety watchdog.
+Writes to any of the sysfs attributes may return the EINVAL error if
+that operation is not supported in a given ThinkPad or if the parameter
+is out-of-bounds, and EPERM if it is forbidden. They may also return
+EINTR (interrupted system call), and EIO (I/O error while trying to talk
+to the firmware).
+
+Features not yet implemented by the driver return ENOSYS.
+
hwmon device attribute pwm1_enable:
0: PWM offline (fan is set to full-speed mode)
1: Manual PWM control (use pwm1 to set fan level)
2: Hardware PWM control (EC "auto" mode)
3: reserved (Software PWM control, not implemented yet)
- Modes 0 and 2 are not supported by all ThinkPads, and the driver
- is not always able to detect this. If it does know a mode is
- unsupported, it will return -EINVAL.
+ Modes 0 and 2 are not supported by all ThinkPads, and the
+ driver is not always able to detect this. If it does know a
+ mode is unsupported, it will return -EINVAL.
hwmon device attribute pwm1:
Fan level, scaled from the firmware values of 0-7 to the hwmon
To stop the fan: set pwm1 to zero, and pwm1_enable to 1.
To start the fan in a safe mode: set pwm1_enable to 2. If that fails
-with ENOTSUP, set it to 1 and set pwm1 to at least 128 (255 would be the
-safest choice, though).
+with EINVAL, try to set pwm1_enable to 1 and pwm1 to at least 128 (255
+would be the safest choice, though).
-EXPERIMENTAL: WAN -- /proc/acpi/ibm/wan
----------------------------------------
+EXPERIMENTAL: WAN
+-----------------
+
+procfs: /proc/acpi/ibm/wan
+sysfs device attribute: wwan_enable
This 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.
-This feature shows the presence and current state of a WAN (Sierra
-Wireless EV-DO) device. If WAN is installed, the following commands can
-be used:
+This feature shows the presence and current state of a W-WAN (Sierra
+Wireless EV-DO) device.
+
+It was tested on a Lenovo Thinkpad X60. It should probably work on other
+Thinkpad models which come with this module installed.
+
+Procfs notes:
+
+If the W-WAN card is installed, the following commands can be used:
echo enable > /proc/acpi/ibm/wan
echo disable > /proc/acpi/ibm/wan
-It was tested on a Lenovo Thinkpad X60. It should probably work on other
-Thinkpad models which come with this module installed.
+Sysfs notes:
+
+ If the W-WAN card is installed, it can be enabled /
+ disabled through the "wwan_enable" thinkpad-acpi device
+ attribute, and its current status can also be queried.
+
+ enable:
+ 0: disables WWAN card / WWAN card is disabled
+ 1: enables WWAN card / WWAN card is enabled.
+
+ Note: this interface will be probably be superseeded by the
+ generic rfkill class, so it is NOT to be considered stable yet.
Multiple Commands, Module Parameters
------------------------------------
0x000100: Initial sysfs support, as a single platform driver and
device.
+0x000200: Hot key support for 32 hot keys, and radio slider switch
+ support.