ACPI: thinkpad-acpi: add CMOS NVRAM polling for hot keys (v9)

[linux-2.6-omap-h63xx.git] / Documentation / thinkpad-acpi.txt

diff --git a/Documentation/thinkpad-acpi.txt b/Documentation/thinkpad-acpi.txt
index 10c041ca13c70c8f0e8d9c44a1e3118f34e9d793..70d91a52e0ffc04c15fb3e70d260759e44f976b0 100644 (file)
--- a/Documentation/thinkpad-acpi.txt
+++ b/Documentation/thinkpad-acpi.txt
@@ -215,6 +215,11 @@ The following commands can be written to the /proc/acpi/ibm/hotkey file:
        ... any other 8-hex-digit mask ...
        echo reset > /proc/acpi/ibm/hotkey -- restore the original mask
 
+The procfs interface does not support NVRAM polling control.  So as to
+maintain maximum bug-to-bug compatibility, it does not report any masks,
+nor does it allow one to manipulate the hot key mask when the firmware
+does not support masks at all, even if NVRAM polling is in use.
+
 sysfs notes:
 
        hotkey_bios_enabled:
@@ -231,17 +236,26 @@ sysfs notes:
                to this value.
 
        hotkey_enable:
-               Enables/disables the hot keys feature, and reports
-               current status of the hot keys feature.
+               Enables/disables the hot keys feature in the ACPI
+               firmware, and reports current status of the hot keys
+               feature.  Has no effect on the NVRAM hot key polling
+               functionality.
 
                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.
+               bit mask to enable driver-handling (and depending on
+               the firmware, ACPI event generation) for each hot key
+               (see above).  Returns the current status of the hot keys
+               mask, and allows one to modify it.
+
+               Note: when NVRAM polling is active, the firmware mask
+               will be different from the value returned by
+               hotkey_mask.  The driver will retain enabled bits for
+               hotkeys that are under NVRAM polling even if the
+               firmware refuses them, and will not set these bits on
+               the firmware hot key mask.
 
        hotkey_all_mask:
                bit mask that should enable event reporting for all
@@ -257,6 +271,40 @@ sysfs notes:
                handled by the firmware anyway.  Echo it to
                hotkey_mask above, to use.
 
+       hotkey_source_mask:
+               bit mask that selects which hot keys will the driver
+               poll the NVRAM for.  This is auto-detected by the driver
+               based on the capabilities reported by the ACPI firmware,
+               but it can be overridden at runtime.
+
+               Hot keys whose bits are set in both hotkey_source_mask
+               and also on hotkey_mask are polled for in NVRAM.  Only a
+               few hot keys are available through CMOS NVRAM polling.
+
+               Warning: when in NVRAM mode, the volume up/down/mute
+               keys are synthesized according to changes in the mixer,
+               so you have to use volume up or volume down to unmute,
+               as per the ThinkPad volume mixer user interface.  When
+               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
+               enforced.
+
+       hotkey_poll_freq:
+               frequency in Hz for hot key polling. It must be between
+               0 and 25 Hz.  Polling is only carried out when strictly
+               needed.
+
+               Setting hotkey_poll_freq to zero disables polling, and
+               will cause hot key presses that require NVRAM polling
+               to never be reported.
+
+               Setting hotkey_poll_freq too low will cause repeated
+               pressings of the same hot key to be misreported as a
+               single key press, or to not even be detected at all.
+               The recommended polling frequency is 10Hz.
+
        hotkey_radio_sw:
                if the ThinkPad has a hardware radio switch, this
                attribute will read 0 if the switch is in the "radios
@@ -1263,3 +1311,14 @@ Sysfs interface changelog:
                and the hwmon class for libsensors4 (lm-sensors 3)
                compatibility.  Moved all hwmon attributes to this
                new platform device.
+
+0x020100:      Marker for thinkpad-acpi with hot key NVRAM polling
+               support.  If you must, use it to know you should not
+               start an userspace NVRAM poller (allows to detect when
+               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
+               NVRAM polling patch).  Some development snapshots of
+               0.18 had an earlier version that did strange things
+               to hotkey_mask.