X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=Documentation%2Flaptops%2Fthinkpad-acpi.txt;h=64b3f146e4b09aa4d2cd312e97689f9eba503347;hb=77a189c28b44035ff1b6841df32c43af8a9e8399;hp=6c2477754a2a35025e8c837740693275d2df8f21;hpb=0eccf60bfa9190d1588b2bf07d23d7b9b3a19d9e;p=linux-2.6 diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt index 6c2477754a..64b3f146e4 100644 --- a/Documentation/laptops/thinkpad-acpi.txt +++ b/Documentation/laptops/thinkpad-acpi.txt @@ -1,7 +1,7 @@ ThinkPad ACPI Extras Driver - Version 0.19 - January 06th, 2008 + Version 0.20 + April 09th, 2008 Borislav Deianov Henrique de Moraes Holschuh @@ -18,6 +18,11 @@ This driver used to be named ibm-acpi until kernel 2.6.21 and release moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel 2.6.22, and release 0.14. +The driver is named "thinkpad-acpi". In some places, like module +names, "thinkpad_acpi" is used because of userspace issues. + +"tpacpi" is used as a shorthand where "thinkpad-acpi" would be too +long due to length limitations on some Linux kernel versions. Status ------ @@ -160,7 +165,7 @@ Hot keys procfs: /proc/acpi/ibm/hotkey sysfs device attribute: hotkey_* -In a ThinkPad, the ACPI HKEY handler is responsible for comunicating +In a ThinkPad, the ACPI HKEY handler is responsible for communicating 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 @@ -193,7 +198,7 @@ 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. +the mask is, therefore, highly 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 @@ -288,7 +293,7 @@ sysfs notes: in ACPI event mode, volume up/down/mute are reported as separate events, but this behaviour may be corrected in future releases of this driver, in which case the - ThinkPad volume mixer user interface semanthics will be + ThinkPad volume mixer user interface semantics will be enforced. hotkey_poll_freq: @@ -306,13 +311,20 @@ sysfs notes: The recommended polling frequency is 10Hz. hotkey_radio_sw: - if the ThinkPad has a hardware radio switch, this + 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 + disabled" position, and 1 if the switch is in the "radios enabled" position. This attribute has poll()/select() support. + hotkey_tablet_mode: + If the ThinkPad has tablet capabilities, this attribute + will read 0 if the ThinkPad is in normal mode, and + 1 if the ThinkPad is in tablet mode. + + This attribute has poll()/select() support. + hotkey_report_mode: Returns the state of the procfs ACPI event report mode filter for hot keys. If it is set to 1 (the default), @@ -339,7 +351,7 @@ sysfs notes: wakeup_hotunplug_complete: Set to 1 if the system was waken up because of an undock or bay ejection request, and that request - was sucessfully completed. At this point, it might + was successfully completed. At this point, it might be useful to send the system back to sleep, at the user's choice. Refer to HKEY events 0x4003 and 0x3003, below. @@ -392,7 +404,7 @@ event code Key Notes Lenovo: battery 0x1004 0x03 FN+F4 Sleep button (ACPI sleep button - semanthics, i.e. sleep-to-RAM). + semantics, i.e. sleep-to-RAM). It is always generate some kind of event, either the hot key event or a ACPI sleep button @@ -403,12 +415,12 @@ event code Key Notes time passes. 0x1005 0x04 FN+F5 Radio. Enables/disables - the internal BlueTooth hardware + the internal Bluetooth hardware 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), + radios (Bluetooth+W-WAN+WLAN), really. 0x1006 0x05 FN+F6 - @@ -417,7 +429,7 @@ event code Key Notes Do you feel lucky today? 0x1008 0x07 FN+F8 IBM: toggle screen expand - Lenovo: configure ultranav + Lenovo: configure UltraNav 0x1009 0x08 FN+F9 - .. .. .. @@ -447,7 +459,7 @@ event code Key Notes 0x1011 0x10 FN+END Brightness down. See brightness up for details. -0x1012 0x11 FN+PGUP Thinklight toggle. This key is +0x1012 0x11 FN+PGUP ThinkLight toggle. This key is always handled by the firmware, even when unmasked. @@ -469,7 +481,7 @@ event code Key Notes key is always handled by the firmware, even when unmasked. -0x1018 0x17 THINKPAD Thinkpad/Access IBM/Lenovo key +0x1018 0x17 THINKPAD ThinkPad/Access IBM/Lenovo key 0x1019 0x18 unknown .. .. .. @@ -488,9 +500,17 @@ If a key is mapped to KEY_UNKNOWN, it generates an input event that includes an scan code. If a key is mapped to anything else, it will generate input device EV_KEY events. +In addition to the EV_KEY events, thinkpad-acpi may also issue EV_SW +events for switches: + +SW_RFKILL_ALL T60 and later hardare rfkill rocker switch +SW_TABLET_MODE Tablet ThinkPads HKEY events 0x5009 and 0x500A + Non hot-key ACPI HKEY event map: 0x5001 Lid closed 0x5002 Lid opened +0x5009 Tablet swivel: switched to tablet mode +0x500A Tablet swivel: switched to normal mode 0x7000 Radio Switch may have changed state The above events are not propagated by the driver, except for legacy @@ -505,9 +525,7 @@ The above events are never propagated by the driver. 0x3003 Bay ejection (see 0x2x05) complete, can sleep again 0x4003 Undocked (see 0x2x04), can sleep again -0x5009 Tablet swivel: switched to tablet mode -0x500A Tablet swivel: switched to normal mode -0x500B Tablet pen insterted into its storage bay +0x500B Tablet pen inserted into its storage bay 0x500C Tablet pen removed from its storage bay 0x5010 Brightness level changed (newer Lenovo BIOSes) @@ -539,7 +557,7 @@ sysfs (it is read-only). If the hotkey_report_mode module parameter is set to 1 or 2, it cannot be changed later through sysfs (any writes will return -EPERM to signal that hotkey_report_mode was locked. On 2.6.23 and later, where -hotkey_report_mode cannot be changed at all, writes will return -EACES). +hotkey_report_mode cannot be changed at all, writes will return -EACCES). hotkey_report_mode set to 1 makes the driver export through the procfs ACPI event interface all hot key presses (which are *also* sent to the @@ -558,6 +576,47 @@ netlink interface and the input layer interface, and don't bother at all with hotkey_report_mode. +Brightness hotkey notes: + +These are the current sane choices for brightness key mapping in +thinkpad-acpi: + +For IBM and Lenovo models *without* ACPI backlight control (the ones on +which thinkpad-acpi will autoload its backlight interface by default, +and on which ACPI video does not export a backlight interface): + +1. Don't enable or map the brightness hotkeys in thinkpad-acpi, as + these older firmware versions unfortunately won't respect the hotkey + mask for brightness keys anyway, and always reacts to them. This + usually work fine, unless X.org drivers are doing something to block + the BIOS. In that case, use (3) below. This is the default mode of + operation. + +2. Enable the hotkeys, but map them to something else that is NOT + KEY_BRIGHTNESS_UP/DOWN or any other keycode that would cause + userspace to try to change the backlight level, and use that as an + on-screen-display hint. + +3. IF AND ONLY IF X.org drivers find a way to block the firmware from + automatically changing the brightness, enable the hotkeys and map + them to KEY_BRIGHTNESS_UP and KEY_BRIGHTNESS_DOWN, and feed that to + something that calls xbacklight. thinkpad-acpi will not be able to + change brightness in that case either, so you should disable its + backlight interface. + +For Lenovo models *with* ACPI backlight control: + +1. Load up ACPI video and use that. ACPI video will report ACPI + events for brightness change keys. Do not mess with thinkpad-acpi + defaults in this case. thinkpad-acpi should not have anything to do + with backlight events in a scenario where ACPI video is loaded: + brightness hotkeys must be disabled, and the backlight interface is + to be kept disabled as well. This is the default mode of operation. + +2. Do *NOT* load up ACPI video, enable the hotkeys in thinkpad-acpi, + and map them to KEY_BRIGHTNESS_UP and KEY_BRIGHTNESS_DOWN. Process + these keys on userspace somehow (e.g. by calling xbacklight). + Bluetooth --------- @@ -584,7 +643,7 @@ Sysfs notes: 0: disables Bluetooth / Bluetooth is disabled 1: enables Bluetooth / Bluetooth is enabled. - Note: this interface will be probably be superseeded by the + Note: this interface will be probably be superseded by the generic rfkill class, so it is NOT to be considered stable yet. Video output control -- /proc/acpi/ibm/video @@ -634,16 +693,31 @@ while others are still having problems. For more information: https://bugs.freedesktop.org/show_bug.cgi?id=2000 -ThinkLight control -- /proc/acpi/ibm/light ------------------------------------------- +ThinkLight control +------------------ -The current status of the ThinkLight can be found in this file. A few -models which do not make the status available will show it as -"unknown". The available commands are: +procfs: /proc/acpi/ibm/light +sysfs attributes: as per LED class, for the "tpacpi::thinklight" LED + +procfs notes: + +The ThinkLight status can be read and set through the procfs interface. A +few models which do not make the status available will show the ThinkLight +status as "unknown". The available commands are: echo on > /proc/acpi/ibm/light echo off > /proc/acpi/ibm/light +sysfs notes: + +The ThinkLight sysfs interface is documented by the LED class +documentation, in Documentation/leds-class.txt. The ThinkLight LED name +is "tpacpi::thinklight". + +Due to limitations in the sysfs LED class, if the status of the thinklight +cannot be read or if it is unknown, thinkpad-acpi will report it as "off". +It is impossible to know if the status returned through sysfs is valid. + Docking / undocking -- /proc/acpi/ibm/dock ------------------------------------------ @@ -791,39 +865,74 @@ on the X40 (tpb is the ThinkPad Buttons utility): 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 + 4 - Related to "LCD brightness up" key press 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) + 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. Do not use it, it is exported just as a debug tool. -LED control -- /proc/acpi/ibm/led ---------------------------------- +LED control +----------- + +procfs: /proc/acpi/ibm/led +sysfs attributes: as per LED class, see below for names + +Some of the LED indicators can be controlled through this feature. On +some older ThinkPad models, it is possible to query the status of the +LED indicators as well. Newer ThinkPads cannot query the real status +of the LED indicators. + +procfs notes: -Some of the LED indicators can be controlled through this feature. The -available commands are: +The available commands are: - echo ' on' >/proc/acpi/ibm/led - echo ' off' >/proc/acpi/ibm/led - echo ' blink' >/proc/acpi/ibm/led + echo ' on' >/proc/acpi/ibm/led + echo ' off' >/proc/acpi/ibm/led + echo ' blink' >/proc/acpi/ibm/led -The range is 0 to 7. The set of LEDs that can be -controlled varies from model to model. Here is the mapping on the X40: +The range is 0 to 7. The set of LEDs that can be +controlled varies from model to model. Here is the common ThinkPad +mapping: 0 - power 1 - battery (orange) 2 - battery (green) - 3 - UltraBase + 3 - UltraBase/dock 4 - UltraBay + 5 - UltraBase battery slot + 6 - (unknown) 7 - standby All of the above can be turned on and off and can be made to blink. +sysfs notes: + +The ThinkPad LED sysfs interface is described in detail by the LED class +documentation, in Documentation/leds-class.txt. + +The leds are named (in LED ID order, from 0 to 7): +"tpacpi::power", "tpacpi:orange:batt", "tpacpi:green:batt", +"tpacpi::dock_active", "tpacpi::bay_active", "tpacpi::dock_batt", +"tpacpi::unknown_led", "tpacpi::standby". + +Due to limitations in the sysfs LED class, if the status of the LED +indicators cannot be read due to an error, thinkpad-acpi will report it as +a brightness of zero (same as LED off). + +If the thinkpad firmware doesn't support reading the current status, +trying to read the current LED brightness will just return whatever +brightness was last written to that attribute. + +These LEDs can blink using hardware acceleration. To request that a +ThinkPad indicator LED should blink in hardware accelerated mode, use the +"timer" trigger, and leave the delay_on and delay_off parameters set to +zero (to request hardware acceleration autodetection). + ACPI sounds -- /proc/acpi/ibm/beep ---------------------------------- @@ -1024,7 +1133,7 @@ There are two interfaces to the firmware for direct 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. +and CMOS. The driver tries to auto-detect which interface to use. When display backlight brightness controls are available through the standard ACPI interface, it is best to use it instead of this direct @@ -1077,6 +1186,15 @@ it there will be the following attributes: dim the display. +WARNING: + + Whatever you do, do NOT ever call thinkpad-acpi backlight-level change + interface and the ACPI-based backlight level change interface + (available on newer BIOSes, and driven by the Linux ACPI video driver) + at the same time. The two will interact in bad ways, do funny things, + and maybe reduce the life of the backlight lamps by needlessly kicking + its level up and down at every change. + Volume control -- /proc/acpi/ibm/volume --------------------------------------- @@ -1266,8 +1384,8 @@ experimental=1 parameter when loading the module. 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. +It was tested on a Lenovo ThinkPad X60. It should probably work on other +ThinkPad models which come with this module installed. Procfs notes: @@ -1286,7 +1404,7 @@ Sysfs notes: 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 + Note: this interface will be probably be superseded by the generic rfkill class, so it is NOT to be considered stable yet. Multiple Commands, Module Parameters @@ -1309,7 +1427,7 @@ Enabling debugging output The module takes a debug parameter which can be used to selectively enable various classes of debugging output, for example: - modprobe ibm_acpi debug=0xffff + modprobe thinkpad_acpi debug=0xffff will enable all debugging output classes. It takes a bitmask, so to enable more than one output class, just add their values. @@ -1356,7 +1474,7 @@ Sysfs interface changelog: NVRAM is compiled out by the user because it is unneeded/undesired in the first place). 0x020101: Marker for thinkpad-acpi with hot key NVRAM polling - and proper hotkey_mask semanthics (version 8 of the + and proper hotkey_mask semantics (version 8 of the NVRAM polling patch). Some development snapshots of 0.18 had an earlier version that did strange things to hotkey_mask.