Commit 011eed59ba6df428a1380fd1419a2a422f0d807a
Committed by
Rafael J. Wysocki
Rafael J. Wysocki
1 parent
572c9fa516
Documentation: ACPI: move acpi-lid.txt to firmware-guide/acpi and convert to reST
This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du <changbin.du@gmail.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Showing 3 changed files with 115 additions and 96 deletions Side-by-side Diff
Documentation/acpi/acpi-lid.txt
| 1 | -Special Usage Model of the ACPI Control Method Lid Device | |
| 2 | - | |
| 3 | -Copyright (C) 2016, Intel Corporation | |
| 4 | -Author: Lv Zheng <lv.zheng@intel.com> | |
| 5 | - | |
| 6 | - | |
| 7 | -Abstract: | |
| 8 | - | |
| 9 | -Platforms containing lids convey lid state (open/close) to OSPMs using a | |
| 10 | -control method lid device. To implement this, the AML tables issue | |
| 11 | -Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has | |
| 12 | -changed. The _LID control method for the lid device must be implemented to | |
| 13 | -report the "current" state of the lid as either "opened" or "closed". | |
| 14 | - | |
| 15 | -For most platforms, both the _LID method and the lid notifications are | |
| 16 | -reliable. However, there are exceptions. In order to work with these | |
| 17 | -exceptional buggy platforms, special restrictions and expections should be | |
| 18 | -taken into account. This document describes the restrictions and the | |
| 19 | -expections of the Linux ACPI lid device driver. | |
| 20 | - | |
| 21 | - | |
| 22 | -1. Restrictions of the returning value of the _LID control method | |
| 23 | - | |
| 24 | -The _LID control method is described to return the "current" lid state. | |
| 25 | -However the word of "current" has ambiguity, some buggy AML tables return | |
| 26 | -the lid state upon the last lid notification instead of returning the lid | |
| 27 | -state upon the last _LID evaluation. There won't be difference when the | |
| 28 | -_LID control method is evaluated during the runtime, the problem is its | |
| 29 | -initial returning value. When the AML tables implement this control method | |
| 30 | -with cached value, the initial returning value is likely not reliable. | |
| 31 | -There are platforms always retun "closed" as initial lid state. | |
| 32 | - | |
| 33 | -2. Restrictions of the lid state change notifications | |
| 34 | - | |
| 35 | -There are buggy AML tables never notifying when the lid device state is | |
| 36 | -changed to "opened". Thus the "opened" notification is not guaranteed. But | |
| 37 | -it is guaranteed that the AML tables always notify "closed" when the lid | |
| 38 | -state is changed to "closed". The "closed" notification is normally used to | |
| 39 | -trigger some system power saving operations on Windows. Since it is fully | |
| 40 | -tested, it is reliable from all AML tables. | |
| 41 | - | |
| 42 | -3. Expections for the userspace users of the ACPI lid device driver | |
| 43 | - | |
| 44 | -The ACPI button driver exports the lid state to the userspace via the | |
| 45 | -following file: | |
| 46 | - /proc/acpi/button/lid/LID0/state | |
| 47 | -This file actually calls the _LID control method described above. And given | |
| 48 | -the previous explanation, it is not reliable enough on some platforms. So | |
| 49 | -it is advised for the userspace program to not to solely rely on this file | |
| 50 | -to determine the actual lid state. | |
| 51 | - | |
| 52 | -The ACPI button driver emits the following input event to the userspace: | |
| 53 | - SW_LID | |
| 54 | -The ACPI lid device driver is implemented to try to deliver the platform | |
| 55 | -triggered events to the userspace. However, given the fact that the buggy | |
| 56 | -firmware cannot make sure "opened"/"closed" events are paired, the ACPI | |
| 57 | -button driver uses the following 3 modes in order not to trigger issues. | |
| 58 | - | |
| 59 | -If the userspace hasn't been prepared to ignore the unreliable "opened" | |
| 60 | -events and the unreliable initial state notification, Linux users can use | |
| 61 | -the following kernel parameters to handle the possible issues: | |
| 62 | -A. button.lid_init_state=method: | |
| 63 | - When this option is specified, the ACPI button driver reports the | |
| 64 | - initial lid state using the returning value of the _LID control method | |
| 65 | - and whether the "opened"/"closed" events are paired fully relies on the | |
| 66 | - firmware implementation. | |
| 67 | - This option can be used to fix some platforms where the returning value | |
| 68 | - of the _LID control method is reliable but the initial lid state | |
| 69 | - notification is missing. | |
| 70 | - This option is the default behavior during the period the userspace | |
| 71 | - isn't ready to handle the buggy AML tables. | |
| 72 | -B. button.lid_init_state=open: | |
| 73 | - When this option is specified, the ACPI button driver always reports the | |
| 74 | - initial lid state as "opened" and whether the "opened"/"closed" events | |
| 75 | - are paired fully relies on the firmware implementation. | |
| 76 | - This may fix some platforms where the returning value of the _LID | |
| 77 | - control method is not reliable and the initial lid state notification is | |
| 78 | - missing. | |
| 79 | - | |
| 80 | -If the userspace has been prepared to ignore the unreliable "opened" events | |
| 81 | -and the unreliable initial state notification, Linux users should always | |
| 82 | -use the following kernel parameter: | |
| 83 | -C. button.lid_init_state=ignore: | |
| 84 | - When this option is specified, the ACPI button driver never reports the | |
| 85 | - initial lid state and there is a compensation mechanism implemented to | |
| 86 | - ensure that the reliable "closed" notifications can always be delievered | |
| 87 | - to the userspace by always pairing "closed" input events with complement | |
| 88 | - "opened" input events. But there is still no guarantee that the "opened" | |
| 89 | - notifications can be delivered to the userspace when the lid is actually | |
| 90 | - opens given that some AML tables do not send "opened" notifications | |
| 91 | - reliably. | |
| 92 | - In this mode, if everything is correctly implemented by the platform | |
| 93 | - firmware, the old userspace programs should still work. Otherwise, the | |
| 94 | - new userspace programs are required to work with the ACPI button driver. | |
| 95 | - This option will be the default behavior after the userspace is ready to | |
| 96 | - handle the buggy AML tables. |
Documentation/firmware-guide/acpi/acpi-lid.rst
| 1 | +.. SPDX-License-Identifier: GPL-2.0 | |
| 2 | +.. include:: <isonum.txt> | |
| 3 | + | |
| 4 | +========================================================= | |
| 5 | +Special Usage Model of the ACPI Control Method Lid Device | |
| 6 | +========================================================= | |
| 7 | + | |
| 8 | +:Copyright: |copy| 2016, Intel Corporation | |
| 9 | + | |
| 10 | +:Author: Lv Zheng <lv.zheng@intel.com> | |
| 11 | + | |
| 12 | +Abstract | |
| 13 | +======== | |
| 14 | +Platforms containing lids convey lid state (open/close) to OSPMs | |
| 15 | +using a control method lid device. To implement this, the AML tables issue | |
| 16 | +Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has | |
| 17 | +changed. The _LID control method for the lid device must be implemented to | |
| 18 | +report the "current" state of the lid as either "opened" or "closed". | |
| 19 | + | |
| 20 | +For most platforms, both the _LID method and the lid notifications are | |
| 21 | +reliable. However, there are exceptions. In order to work with these | |
| 22 | +exceptional buggy platforms, special restrictions and expections should be | |
| 23 | +taken into account. This document describes the restrictions and the | |
| 24 | +expections of the Linux ACPI lid device driver. | |
| 25 | + | |
| 26 | + | |
| 27 | +Restrictions of the returning value of the _LID control method | |
| 28 | +============================================================== | |
| 29 | + | |
| 30 | +The _LID control method is described to return the "current" lid state. | |
| 31 | +However the word of "current" has ambiguity, some buggy AML tables return | |
| 32 | +the lid state upon the last lid notification instead of returning the lid | |
| 33 | +state upon the last _LID evaluation. There won't be difference when the | |
| 34 | +_LID control method is evaluated during the runtime, the problem is its | |
| 35 | +initial returning value. When the AML tables implement this control method | |
| 36 | +with cached value, the initial returning value is likely not reliable. | |
| 37 | +There are platforms always retun "closed" as initial lid state. | |
| 38 | + | |
| 39 | +Restrictions of the lid state change notifications | |
| 40 | +================================================== | |
| 41 | + | |
| 42 | +There are buggy AML tables never notifying when the lid device state is | |
| 43 | +changed to "opened". Thus the "opened" notification is not guaranteed. But | |
| 44 | +it is guaranteed that the AML tables always notify "closed" when the lid | |
| 45 | +state is changed to "closed". The "closed" notification is normally used to | |
| 46 | +trigger some system power saving operations on Windows. Since it is fully | |
| 47 | +tested, it is reliable from all AML tables. | |
| 48 | + | |
| 49 | +Expections for the userspace users of the ACPI lid device driver | |
| 50 | +================================================================ | |
| 51 | + | |
| 52 | +The ACPI button driver exports the lid state to the userspace via the | |
| 53 | +following file:: | |
| 54 | + | |
| 55 | + /proc/acpi/button/lid/LID0/state | |
| 56 | + | |
| 57 | +This file actually calls the _LID control method described above. And given | |
| 58 | +the previous explanation, it is not reliable enough on some platforms. So | |
| 59 | +it is advised for the userspace program to not to solely rely on this file | |
| 60 | +to determine the actual lid state. | |
| 61 | + | |
| 62 | +The ACPI button driver emits the following input event to the userspace: | |
| 63 | + * SW_LID | |
| 64 | + | |
| 65 | +The ACPI lid device driver is implemented to try to deliver the platform | |
| 66 | +triggered events to the userspace. However, given the fact that the buggy | |
| 67 | +firmware cannot make sure "opened"/"closed" events are paired, the ACPI | |
| 68 | +button driver uses the following 3 modes in order not to trigger issues. | |
| 69 | + | |
| 70 | +If the userspace hasn't been prepared to ignore the unreliable "opened" | |
| 71 | +events and the unreliable initial state notification, Linux users can use | |
| 72 | +the following kernel parameters to handle the possible issues: | |
| 73 | + | |
| 74 | +A. button.lid_init_state=method: | |
| 75 | + When this option is specified, the ACPI button driver reports the | |
| 76 | + initial lid state using the returning value of the _LID control method | |
| 77 | + and whether the "opened"/"closed" events are paired fully relies on the | |
| 78 | + firmware implementation. | |
| 79 | + | |
| 80 | + This option can be used to fix some platforms where the returning value | |
| 81 | + of the _LID control method is reliable but the initial lid state | |
| 82 | + notification is missing. | |
| 83 | + | |
| 84 | + This option is the default behavior during the period the userspace | |
| 85 | + isn't ready to handle the buggy AML tables. | |
| 86 | + | |
| 87 | +B. button.lid_init_state=open: | |
| 88 | + When this option is specified, the ACPI button driver always reports the | |
| 89 | + initial lid state as "opened" and whether the "opened"/"closed" events | |
| 90 | + are paired fully relies on the firmware implementation. | |
| 91 | + | |
| 92 | + This may fix some platforms where the returning value of the _LID | |
| 93 | + control method is not reliable and the initial lid state notification is | |
| 94 | + missing. | |
| 95 | + | |
| 96 | +If the userspace has been prepared to ignore the unreliable "opened" events | |
| 97 | +and the unreliable initial state notification, Linux users should always | |
| 98 | +use the following kernel parameter: | |
| 99 | + | |
| 100 | +C. button.lid_init_state=ignore: | |
| 101 | + When this option is specified, the ACPI button driver never reports the | |
| 102 | + initial lid state and there is a compensation mechanism implemented to | |
| 103 | + ensure that the reliable "closed" notifications can always be delievered | |
| 104 | + to the userspace by always pairing "closed" input events with complement | |
| 105 | + "opened" input events. But there is still no guarantee that the "opened" | |
| 106 | + notifications can be delivered to the userspace when the lid is actually | |
| 107 | + opens given that some AML tables do not send "opened" notifications | |
| 108 | + reliably. | |
| 109 | + | |
| 110 | + In this mode, if everything is correctly implemented by the platform | |
| 111 | + firmware, the old userspace programs should still work. Otherwise, the | |
| 112 | + new userspace programs are required to work with the ACPI button driver. | |
| 113 | + This option will be the default behavior after the userspace is ready to | |
| 114 | + handle the buggy AML tables. |
Documentation/firmware-guide/acpi/index.rst