Linux Kernel Markers: document format string
[pandora-kernel.git] / Documentation / thinkpad-acpi.txt
index c670363..ec49926 100644 (file)
@@ -1,11 +1,11 @@
                     ThinkPad ACPI Extras Driver
 
-                            Version 0.14
-                          April 21st, 2007
+                            Version 0.16
+                          August 2nd, 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
@@ -105,10 +105,15 @@ The version of thinkpad-acpi's sysfs interface is exported by the driver
 as a driver attribute (see below).
 
 Sysfs driver attributes are on the driver's sysfs attribute space,
-for 2.6.20 this is /sys/bus/platform/drivers/thinkpad-acpi/.
+for 2.6.23 this is /sys/bus/platform/drivers/thinkpad_acpi/ and
+/sys/bus/platform/drivers/thinkpad_hwmon/
 
-Sysfs device attributes are on the driver's sysfs attribute space,
-for 2.6.20 this is /sys/devices/platform/thinkpad-acpi/.
+Sysfs device attributes are on the thinkpad_acpi device sysfs attribute
+space, for 2.6.23 this is /sys/devices/platform/thinkpad_acpi/.
+
+Sysfs device attributes for the sensors and fan are on the
+thinkpad_hwmon device's sysfs attribute space, but you should locate it
+looking for a hwmon device with the name attribute of "thinkpad".
 
 Driver version
 --------------
@@ -161,20 +166,22 @@ 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.
 
+The driver enables the hot key feature automatically when loaded.  The
+feature can later be disabled and enabled back at runtime.  The driver
+will also restore the hot key feature to its previous state and mask
+when it is unloaded.
+
 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:
+below), the driver will report HKEY events in the following format:
 
        ibm/hotkey HKEY 00000080 0000xxxx
 
-or events over the input layer.  The input layer support accepts the
-standard IOCTLs to remap the keycodes assigned to each hotkey.
+Some of these events refer to hot key presses, but not all.
 
-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 driver will generate events over the input layer for hot keys and
+radio switches, and over the ACPI netlink layer for other events.  The
+input layer support accepts the standard IOCTLs to remap the keycodes
+assigned to each hot key.
 
 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
@@ -256,6 +263,20 @@ sysfs notes:
                disabled" postition, and 1 if the switch is in the
                "radios enabled" position.
 
+       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),
+               all hot key presses are reported both through the input
+               layer and also as ACPI events through procfs (but not
+               through netlink).  If it is set to 2, hot key presses
+               are reported only through the input layer.
+
+               This attribute is read-only in kernels 2.6.23 or later,
+               and read-write on earlier kernels.
+
+               May return -EPERM (write access locked out by module
+               parameter) or -EACCES (read-only).
+
 input layer notes:
 
 A Hot key is mapped to a single input layer EV_KEY event, possibly
@@ -270,7 +291,8 @@ 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)
+       vendor:         0x1014 (PCI_VENDOR_ID_IBM)  or
+                       0x17aa (PCI_VENDOR_ID_LENOVO)
        product:        0x5054 ("TP")
        version:        0x4101
 
@@ -290,12 +312,15 @@ ACPI      Scan
 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).
@@ -313,13 +338,19 @@ event     code    Key             Notes
                                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          -
 
@@ -338,13 +369,15 @@ event     code    Key             Notes
 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.
@@ -356,9 +389,13 @@ event      code    Key             Notes
 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.
@@ -377,21 +414,63 @@ 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_RESERVED, it generates no input events at all.
 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.
+includes an scan code.  If a key is mapped to anything else, it will
+generate input device EV_KEY events.
 
 Non hot-key ACPI HKEY event map:
 0x5001         Lid closed
 0x5002         Lid opened
 0x7000         Radio Switch may have changed state
 
+The above events are not propagated by the driver, except for legacy
+compatibility purposes when hotkey_report_mode is set to 1.
+
+Compatibility notes:
+
+ibm-acpi and thinkpad-acpi 0.15 (mainline kernels before 2.6.23) never
+supported the input layer, and sent events over the procfs ACPI event
+interface.
+
+To avoid sending duplicate events over the input layer and the ACPI
+event interface, thinkpad-acpi 0.16 implements a module parameter
+(hotkey_report_mode), and also a sysfs device attribute with the same
+name.
+
+Make no mistake here: userspace is expected to switch to using the input
+layer interface of thinkpad-acpi, together with the ACPI netlink event
+interface in kernels 2.6.23 and later, or with the ACPI procfs event
+interface in kernels 2.6.22 and earlier.
+
+If no hotkey_report_mode module parameter is specified (or it is set to
+zero), the driver defaults to mode 1 (see below), and on kernels 2.6.22
+and earlier, also allows one to change the hotkey_report_mode through
+sysfs.  In kernels 2.6.23 and later, where the netlink ACPI event
+interface is available, hotkey_report_mode cannot be changed through
+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 set to 1 makes the driver export through the procfs
+ACPI event interface all hot key presses (which are *also* sent to the
+input layer).  This is a legacy compatibility behaviour, and it is also
+the default mode of operation for the driver.
+
+hotkey_report_mode set to 2 makes the driver filter out the hot key
+presses from the procfs ACPI event interface, so these events will only
+be sent through the input layer.  Userspace that has been updated to use
+the thinkpad-acpi input layer interface should set hotkey_report_mode to
+2.
+
+Hot key press events are never sent to the ACPI netlink event interface.
+Really up-to-date userspace under kernel 2.6.23 and later is to use the
+netlink interface and the input layer interface, and don't bother at all
+with hotkey_report_mode.
+
 
 Bluetooth
 ---------
@@ -692,25 +771,17 @@ Temperature sensors
 -------------------
 
 procfs: /proc/acpi/ibm/thermal
-sysfs device attributes: (hwmon) temp*_input
+sysfs device attributes: (hwmon "thinkpad") 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
@@ -860,6 +931,12 @@ cannot be controlled.
 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:
@@ -917,7 +994,9 @@ Fan control and monitoring: fan speed, fan enable/disable
 ---------------------------------------------------------
 
 procfs: /proc/acpi/ibm/fan
-sysfs device attributes: (hwmon) fan_input, pwm1, pwm1_enable
+sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1,
+                         pwm1_enable
+sysfs hwmon driver attributes: fan_watchdog
 
 NOTE NOTE NOTE: fan control operations are disabled by default for
 safety reasons.  To enable them, the module parameter "fan_control=1"
@@ -956,7 +1035,7 @@ enable it if necessary to avoid overheating.
 
 An enabled fan in level "auto" may stop spinning if the EC decides the
 ThinkPad is cool enough and doesn't need the extra airflow.  This is
-normal, and the EC will spin the fan up if the varios thermal readings
+normal, and the EC will spin the fan up if the various thermal readings
 rise too much.
 
 On the X40, this seems to depend on the CPU and HDD temperatures.
@@ -1059,7 +1138,7 @@ hwmon device attribute fan1_input:
        which can take up to two minutes.  May return rubbish on older
        ThinkPads.
 
-driver attribute fan_watchdog:
+hwmon driver attribute fan_watchdog:
        Fan safety watchdog timer interval, in seconds.  Minimum is
        1 second, maximum is 120 seconds.  0 disables the watchdog.
 
@@ -1124,7 +1203,7 @@ for example:
 Enabling debugging output
 -------------------------
 
-The module takes a debug paramater which can be used to selectively
+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
@@ -1161,3 +1240,9 @@ Sysfs interface changelog:
                layer, the radio switch generates input event EV_RADIO,
                and the driver enables hot key handling by default in
                the firmware.
+
+0x020000:      ABI fix: added a separate hwmon platform device and
+               driver, which must be located by name (thinkpad)
+               and the hwmon class for libsensors4 (lm-sensors 3)
+               compatibility.  Moved all hwmon attributes to this
+               new platform device.