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>, Benjamin Tissoires <benjamin.tissoires@gmail.com>, "Bastien Nocera:" <hadess@hadess.net>, linux-input@vger.kernel.org Subject: [PATCH v3 2/2] ACPI / button: Add document for ACPI control method lid device restrictions Date: Tue, 12 Jul 2016 18:17:15 +0800 [thread overview] Message-ID: <627cd0bcb5ff7fcf384089003b98be825965e7f1.1468318558.git.lv.zheng@intel.com> (raw) In-Reply-To: <cover.1467717304.git.lv.zheng@intel.com> 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@intel.com> Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com> Cc: Benjamin Tissoires <benjamin.tissoires@gmail.com> Cc: Bastien Nocera: <hadess@hadess.net> Cc: linux-input@vger.kernel.org --- 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@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". + +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
WARNING: multiple messages have this Message-ID (diff)
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>, Benjamin Tissoires <benjamin.tissoires@gmail.com>, "Bastien Nocera:" <hadess@hadess.net>, linux-input@vger.kernel.org Subject: [PATCH v3 2/2] ACPI / button: Add document for ACPI control method lid device restrictions Date: Tue, 12 Jul 2016 18:17:15 +0800 [thread overview] Message-ID: <627cd0bcb5ff7fcf384089003b98be825965e7f1.1468318558.git.lv.zheng@intel.com> (raw) In-Reply-To: <cover.1467717304.git.lv.zheng@intel.com> 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@intel.com> Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com> Cc: Benjamin Tissoires <benjamin.tissoires@gmail.com> Cc: Bastien Nocera: <hadess@hadess.net> Cc: linux-input@vger.kernel.org --- 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@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". + +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
next prev parent reply other threads:[~2016-07-12 10:17 UTC|newest] Thread overview: 52+ messages / expand[flat|nested] mbox.gz Atom feed top 2016-07-05 11:17 [PATCH 0/5] ACPI: ACPI documentations and trivial fixes Lv Zheng 2016-07-05 11:17 ` Lv Zheng 2016-07-05 11:17 ` [PATCH 1/5] ACPI: Add documentation describing ACPICA release automation Lv Zheng 2016-07-05 11:17 ` Lv Zheng 2016-07-05 11:18 ` [PATCH 2/5] ACPI / debugger: Fix regressions that AML debugger stops working Lv Zheng 2016-07-05 11:18 ` Lv Zheng 2016-07-05 23:41 ` Rafael J. Wysocki 2016-07-06 2:08 ` Zheng, Lv 2016-07-05 11:18 ` [PATCH 3/5] ACPI / debugger: Add AML debugger documentation Lv Zheng 2016-07-05 11:18 ` Lv Zheng 2016-07-05 11:18 ` [PATCH 4/5] ACPI / button: Add SW_ACPI_LID for new usage model Lv Zheng 2016-07-05 11:18 ` Lv Zheng 2016-07-05 11:18 ` [PATCH 5/5] ACPI: Add configuration item to configure ACPICA error logs out Lv Zheng 2016-07-05 11:18 ` Lv Zheng 2016-07-05 23:43 ` Rafael J. Wysocki 2016-07-06 1:46 ` Zheng, Lv 2016-07-07 7:10 ` [PATCH v2 0/4] ACPI: ACPI documentation Lv Zheng 2016-07-07 7:10 ` Lv Zheng 2016-07-07 7:10 ` [PATCH v2 1/4] ACPI: Add documentation describing ACPICA release automation Lv Zheng 2016-07-07 7:10 ` Lv Zheng 2016-07-07 7:10 ` [PATCH v2 2/4] ACPI / debugger: Add AML debugger documentation Lv Zheng 2016-07-07 7:10 ` Lv Zheng 2016-07-07 7:10 ` [PATCH v2 3/4] ACPI / button: Add SW_ACPI_LID for new usage model Lv Zheng 2016-07-07 7:10 ` Lv Zheng 2016-07-08 9:27 ` Benjamin Tissoires 2016-07-08 17:55 ` Dmitry Torokhov 2016-07-07 7:11 ` [PATCH v2 4/4] ACPI / button: Add document for ACPI control method lid device restrictions Lv Zheng 2016-07-07 7:11 ` Lv Zheng 2016-07-08 9:17 ` Benjamin Tissoires 2016-07-08 17:51 ` Dmitry Torokhov 2016-07-11 11:34 ` Benjamin Tissoires 2016-07-12 0:41 ` Dmitry Torokhov 2016-07-12 7:43 ` Zheng, Lv 2016-07-20 3:21 ` Zheng, Lv 2016-07-12 7:13 ` Zheng, Lv 2016-07-19 7:17 ` Zheng, Lv 2016-07-19 8:40 ` Benjamin Tissoires 2016-07-19 8:57 ` Zheng, Lv 2016-07-19 9:07 ` Benjamin Tissoires 2016-07-11 3:20 ` Zheng, Lv 2016-07-11 10:58 ` Bastien Nocera 2016-07-12 7:06 ` Zheng, Lv 2016-07-11 11:42 ` Benjamin Tissoires 2016-07-11 11:47 ` Benjamin Tissoires 2016-07-12 7:34 ` Zheng, Lv 2016-07-12 10:17 ` [PATCH v3 1/2] ACPI / button: Add KEY_LID_CLOSE for new usage model Lv Zheng 2016-07-12 10:17 ` Lv Zheng 2016-07-18 7:53 ` Benjamin Tissoires 2016-07-18 15:51 ` Bastien Nocera 2016-07-19 4:48 ` Zheng, Lv 2016-07-12 10:17 ` Lv Zheng [this message] 2016-07-12 10:17 ` [PATCH v3 2/2] ACPI / button: Add document for ACPI control method lid device restrictions Lv Zheng
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=627cd0bcb5ff7fcf384089003b98be825965e7f1.1468318558.git.lv.zheng@intel.com \ --to=lv.zheng@intel.com \ --cc=benjamin.tissoires@gmail.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: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.