| Lv Zheng | f9151fc | 2016-08-17 16:23:14 +0800 | [diff] [blame] | 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. |