projects / linux.git / blame
| Commit | Line | Data |
|---|---|---|
| f9151fcf LZ |
1 | Special Usage Model of the ACPI Control Method Lid Device |
| 2 | ||
| 3 | Copyright (C) 2016, Intel Corporation | |
| 4 | Author: Lv Zheng <[email protected]> | |
| 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: | |
| f369fdf4 LZ |
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: | |
| f9151fcf LZ |
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: | |
| f369fdf4 | 83 | C. button.lid_init_state=ignore: |
| f9151fcf LZ |
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. |