[PATCH v3 2/2] ACPI / button: Add document for ACPI control method lid device restrictions

[Lv Zheng]

There are many AML tables reporting wrong initial lid state, and some of
them never reports lid open state. As a proxy layer acting between, ACPI
button driver is not able to handle all such cases, but need to re-define
the usage model of the ACPI lid. That is:
1. It's initial state is not reliable;
2. There may not be an open event;
3. Userspace should only take action against the close event which is
   reliable, always sent after a real lid close.
This patch adds documentation of the usage model.

Signed-off-by: Lv Zheng <lv.zheng@xxxxxxxxx>
Cc: Dmitry Torokhov <dmitry.torokhov@xxxxxxxxx>
Cc: Benjamin Tissoires <benjamin.tissoires@xxxxxxxxx>
Cc: Bastien Nocera: <hadess@xxxxxxxxxx>
Cc: linux-input@xxxxxxxxxxxxxxx
---
 Documentation/acpi/acpi-lid.txt |   89 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 Documentation/acpi/acpi-lid.txt

diff --git a/Documentation/acpi/acpi-lid.txt b/Documentation/acpi/acpi-lid.txt
new file mode 100644
index 0000000..5cf587c
--- /dev/null
+++ b/Documentation/acpi/acpi-lid.txt
@@ -0,0 +1,89 @@
+Usage Model of the ACPI Control Method Lid Device
+
+Copyright (C) 2016, Intel Corporation
+Author: Lv Zheng <lv.zheng@xxxxxxxxx>
+
+
+Abstract:
+
+Platforms containing lids convey lid state (open/close) to OSPMs using a
+control method lid device. To implement this, the AML tables issue
+Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has
+changed. The _LID control method for the lid device must be implemented to
+report the "current" state of the lid as either "opened" or "closed".
+
+This document describes the restrictions and the expections of the Linux
+ACPI lid device driver.
+
+
+1. Restrictions of the returning value of the _LID control method
+
+The _LID control method is described to return the "current" lid state.
+However the word of "current" has ambiguity, many AML tables return the lid
+state upon the last lid notification instead of returning the lid state
+upon the last _LID evaluation. There won't be difference when the _LID
+control method is evaluated during the runtime, the problem is its initial
+returning value. When the AML tables implement this control method with
+cached value, the initial returning value is likely not reliable. There are
+simply so many examples always retuning "closed" as initial lid state.
+
+2. Restrictions of the lid state change notifications
+
+There are many AML tables never notifying when the lid device state is
+changed to "opened". Thus the "opened" notification is not guaranteed.
+
+But it is guaranteed that the AML tables always notify "closed" when the
+lid state is changed to "closed". The "closed" notification is normally
+used to trigger some system power saving operations on Windows. Since it is
+fully tested, the "closed" notification is reliable for all AML tables.
+
+3. Expections for the userspace users of the ACPI lid device driver
+
+The ACPI button driver exports the lid state to the userspace via the
+following file:
+  /proc/acpi/button/lid/LID0/state
+This file actually calls the _LID control method described above. And given
+the previous explanation, it is not reliable enough on some platforms. So
+it is advised for the userspace program to not to solely rely on this file
+to determine the actual lid state.
+
+Linux users can switch the ACPI button driver behavior via the following
+kernel parameters:
+A. button.lid_event_type=switch:
+   When the lid state/event is reliable, the users can specify this option
+   (or nothing as this is the default option) to load the ACPI button
+   driver. The ACPI button driver will send the traditional "SW_LID" event
+   to the userspace.
+B. button.lid_event_type=key:
+   When the lid state/event is not reliable, the users can specify this
+   option to load the ACPI button driver. The ACPI button driver will send
+   the "KEY_LID_CLOSE" event instead of the "SW_LID" to the userspace.
+
+If the userspace hasn't been prepared to handle the new KEY_LID_CLOSE
+event, Linux users can use the following kernel parameters to handle the
+possible issues triggered because of the unreliable lid state/event:
+C. button.lid_init_state=method:
+   This option is only effective when the event type is "switch". When this
+   option is specified, the ACPI button driver reports the initial lid
+   state using the returning value of the _LID control method.
+   This option can be used to fix some platforms where the _LID control
+   method's returning value is reliable but the initial lid state
+   notification is missing.
+D. button.lid_init_state=open:
+   This option is only effective when the event type is "switch". When this
+   option is specified, the ACPI button driver always reports the initial
+   lid state as "opened".
+   This may fix some platforms where the returning value of the _LID
+   control method is not reliable and the initial lid state notification is
+   missing.
+
+If the userspace has been prepared to handle the new KEY_LID_CLOSE event,
+Linux users should always use the following kernel parameter:
+E. button.lid_init_state=ignore:
+   This option allows the users to switch the "event type" between the
+   "switch" and the "key". When this option is specified, the ACPI button
+   driver never reports the initial lid state. However, the platform may
+   automatically report a correct initial lid state and there is no "open"
+   event missing. When this is the case (everything is correctly
+   implemented by the platform firmware), the "event type" should be
+   "switch", otherwise, the "event type" should be "key".
-- 
1.7.10