From: Lv Zheng <lv.zheng@intel.com>
To: "Rafael J. Wysocki" <rafael.j.wysocki@intel.com>,
"Rafael J. Wysocki" <rjw@rjwysocki.net>,
Len Brown <len.brown@intel.com>
Cc: Lv Zheng <lv.zheng@intel.com>, Lv Zheng <zetalog@gmail.com>,
<linux-kernel@vger.kernel.org>,
linux-acpi@vger.kernel.org,
Dmitry Torokhov <dmitry.torokhov@gmail.com>,
"Bastien Nocera:" <hadess@hadess.net>,
linux-input@vger.kernel.org
Subject: [PATCH v8 2/2] ACPI / button: Add document for ACPI control method lid device restrictions
Date: Wed, 17 Aug 2016 16:23:14 +0800 [thread overview]
Message-ID: <5b3ad68bd0806671fcf96efbc36681827f312f02.1471422130.git.lv.zheng@intel.com> (raw)
In-Reply-To: <cbdaec17aba78c61f466efff8883d49067f2dad5.1463472125.git.lv.zheng@intel.com>
This patch adds documentation for the usage model of the control method lid
device on some buggy platforms.
Signed-off-by: Lv Zheng <lv.zheng@intel.com>
Acked-by: Benjamin Tissoires <benjamin.tissoires@gmail.com>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: Bastien Nocera: <hadess@hadess.net>
Cc: linux-input@vger.kernel.org
---
Documentation/acpi/acpi-lid.txt | 96 +++++++++++++++++++++++++++++++++++++++
1 file changed, 96 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..effe7af
--- /dev/null
+++ b/Documentation/acpi/acpi-lid.txt
@@ -0,0 +1,96 @@
+Special Usage Model of the ACPI Control Method Lid Device
+
+Copyright (C) 2016, Intel Corporation
+Author: Lv Zheng <lv.zheng@intel.com>
+
+
+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".
+
+For most platforms, both the _LID method and the lid notifications are
+reliable. However, there are exceptions. In order to work with these
+exceptional buggy platforms, special restrictions and expections should be
+taken into account. 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, some buggy 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 platforms always retun "closed" as initial lid state.
+
+2. Restrictions of the lid state change notifications
+
+There are buggy 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, it is reliable from 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.
+
+The ACPI button driver emits the following input event to the userspace:
+ SW_LID
+The ACPI lid device driver is implemented to try to deliver the platform
+triggered events to the userspace. However, given the fact that the buggy
+firmware cannot make sure "opened"/"closed" events are paired, the ACPI
+button driver uses the following 3 modes in order not to trigger issues.
+
+If the userspace hasn't been prepared to ignore the unreliable "opened"
+events and the unreliable initial state notification, Linux users can use
+the following kernel parameters to handle the possible issues:
+A. button.lid_init_state=method:
+ When this option is specified, the ACPI button driver reports the
+ initial lid state using the returning value of the _LID control method
+ and whether the "opened"/"closed" events are paired fully relies on the
+ firmware implementation.
+ This option can be used to fix some platforms where the returning value
+ of the _LID control method is reliable but the initial lid state
+ notification is missing.
+ This option is the default behavior during the period the userspace
+ isn't ready to handle the buggy AML tables.
+B. button.lid_init_state=open:
+ When this option is specified, the ACPI button driver always reports the
+ initial lid state as "opened" and whether the "opened"/"closed" events
+ are paired fully relies on the firmware implementation.
+ 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 ignore the unreliable "opened" events
+and the unreliable initial state notification, Linux users should always
+use the following kernel parameter:
+C. button.lid_init_state=ignore:
+ When this option is specified, the ACPI button driver never reports the
+ initial lid state and there is a compensation mechanism implemented to
+ ensure that the reliable "closed" notifications can always be delievered
+ to the userspace by always pairing "closed" input events with complement
+ "opened" input events. But there is still no guarantee that the "opened"
+ notifications can be delivered to the userspace when the lid is actually
+ opens given that some AML tables do not send "opened" notifications
+ reliably.
+ In this mode, if everything is correctly implemented by the platform
+ firmware, the old userspace programs should still work. Otherwise, the
+ new userspace programs are required to work with the ACPI button driver.
+ This option will be the default behavior after the userspace is ready to
+ handle the buggy AML tables.
--
1.7.10
prev parent reply other threads:[~2016-08-17 8:26 UTC|newest]
Thread overview: 66+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-05-17 8:27 [RFC PATCH 1/2] ACPI / button: Send "open" state after boot/resume Lv Zheng
2016-05-17 23:36 ` Rafael J. Wysocki
2016-05-18 1:25 ` Zheng, Lv
2016-05-18 22:56 ` Rafael J. Wysocki
2016-05-19 1:50 ` Zheng, Lv
2016-05-19 13:21 ` Rafael J. Wysocki
2016-05-26 13:31 ` Benjamin Tissoires
2016-05-30 1:39 ` Zheng, Lv
2016-05-18 12:57 ` Bastien Nocera
2016-05-18 21:41 ` Rafael J. Wysocki
2016-05-19 1:59 ` Zheng, Lv
2016-05-27 7:15 ` [PATCH v2 0/3] ACPI / button: Clarify initial lid state Lv Zheng
2016-05-27 7:15 ` [PATCH v2 1/3] ACPI / button: Remove initial lid state notification Lv Zheng
2016-05-27 7:15 ` [PATCH v2 2/3] ACPI / button: Refactor functions to eliminate redundant code Lv Zheng
2016-05-27 7:16 ` [PATCH v2 3/3] ACPI / button: Send "open" state after boot/resume Lv Zheng
2016-05-30 8:10 ` Benjamin Tissoires
2016-05-31 2:55 ` Zheng, Lv
2016-05-31 14:47 ` Benjamin Tissoires
2016-06-01 1:17 ` Zheng, Lv
2016-06-01 7:51 ` Zheng, Lv
2016-06-01 8:07 ` Benjamin Tissoires
2016-05-27 22:10 ` [PATCH v2 0/3] ACPI / button: Clarify initial lid state Valdis.Kletnieks
2016-06-01 10:10 ` [PATCH v3 1/3] ACPI / button: Remove initial lid state notification Lv Zheng
2016-06-23 0:36 ` Rafael J. Wysocki
2016-06-23 0:57 ` Zheng, Lv
2016-06-01 10:10 ` [PATCH v3 2/3] ACPI / button: Refactor functions to eliminate redundant code Lv Zheng
2016-06-01 10:10 ` [PATCH v3 3/3] ACPI / button: Add quirks for initial lid state notification Lv Zheng
2016-06-01 11:01 ` Bastien Nocera
2016-06-02 1:08 ` Zheng, Lv
2016-06-02 14:01 ` Bastien Nocera
2016-06-02 15:25 ` Benjamin Tissoires
2016-06-03 0:41 ` Zheng, Lv
2016-07-19 8:11 ` [PATCH v4 1/2] ACPI / button: Add KEY_LID_OPEN/KEY_LID_CLOSE for new usage model Lv Zheng
2016-07-19 8:46 ` Benjamin Tissoires
2016-07-21 13:35 ` Rafael J. Wysocki
2016-07-21 20:33 ` Dmitry Torokhov
2016-07-19 8:11 ` [PATCH v4 2/2] ACPI / button: Add document for ACPI control method lid device restrictions Lv Zheng
2016-07-19 8:44 ` Benjamin Tissoires
2016-07-21 20:32 ` Dmitry Torokhov
2016-07-22 0:24 ` Zheng, Lv
2016-07-22 4:37 ` Dmitry Torokhov
2016-07-22 6:55 ` Benjamin Tissoires
2016-07-22 8:47 ` Zheng, Lv
2016-07-22 9:08 ` Benjamin Tissoires
2016-07-22 9:38 ` Zheng, Lv
2016-07-24 11:28 ` Bastien Nocera
2016-07-25 0:38 ` Zheng, Lv
2016-07-22 17:02 ` Dmitry Torokhov
2016-07-23 12:17 ` Zheng, Lv
2016-07-22 8:37 ` Zheng, Lv
2016-07-22 17:22 ` Dmitry Torokhov
2016-07-23 11:57 ` Zheng, Lv
2016-07-22 6:24 ` [PATCH v5 1/3] ACPI / button: Add missing event to keep SW_LID running without additional event loss Lv Zheng
2016-07-22 10:26 ` Zheng, Lv
2016-07-23 12:37 ` Rafael J. Wysocki
2016-07-25 0:24 ` Zheng, Lv
2016-07-22 6:24 ` [PATCH v5 2/3] ACPI / button: Add KEY_LID_OPEN/KEY_LID_CLOSE for new usage model Lv Zheng
2016-07-22 6:24 ` [PATCH v5 3/3] ACPI / button: Add document for ACPI control method lid device restrictions Lv Zheng
2016-07-25 1:14 ` [PATCH v6] ACPI / button: Fix an issue that the platform triggered "close" event may not be delivered to the userspace Lv Zheng
2016-07-26 9:52 ` [PATCH v7 1/2] ACPI / button: Fix an issue that the platform triggered reliable events " Lv Zheng
2016-08-17 0:19 ` Rafael J. Wysocki
2016-08-17 4:45 ` Zheng, Lv
2016-07-26 9:52 ` [PATCH v7 2/2] ACPI / button: Add document for ACPI control method lid device restrictions Lv Zheng
2016-08-17 8:22 ` [PATCH v8 1/2] ACPI / button: Fix an issue in button.lid_init_state=ignore mode Lv Zheng
2016-09-12 22:10 ` Rafael J. Wysocki
2016-08-17 8:23 ` Lv Zheng [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5b3ad68bd0806671fcf96efbc36681827f312f02.1471422130.git.lv.zheng@intel.com \
--to=lv.zheng@intel.com \
--cc=dmitry.torokhov@gmail.com \
--cc=hadess@hadess.net \
--cc=len.brown@intel.com \
--cc=linux-acpi@vger.kernel.org \
--cc=linux-input@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=rafael.j.wysocki@intel.com \
--cc=rjw@rjwysocki.net \
--cc=zetalog@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®