1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt> 2 .. include:: <isonum.txt>
3 3
4 ============================================== 4 =========================================================
5 Special Usage Model of the ACPI Control Method 5 Special Usage Model of the ACPI Control Method Lid Device
6 ============================================== 6 =========================================================
7 7
8 :Copyright: |copy| 2016, Intel Corporation 8 :Copyright: |copy| 2016, Intel Corporation
9 9
10 :Author: Lv Zheng <lv.zheng@intel.com> 10 :Author: Lv Zheng <lv.zheng@intel.com>
11 11
12 Abstract 12 Abstract
13 ======== 13 ========
14 Platforms containing lids convey lid state (op 14 Platforms containing lids convey lid state (open/close) to OSPMs
15 using a control method lid device. To implemen 15 using a control method lid device. To implement this, the AML tables issue
16 Notify(lid_device, 0x80) to notify the OSPMs w 16 Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has
17 changed. The _LID control method for the lid d 17 changed. The _LID control method for the lid device must be implemented to
18 report the "current" state of the lid as eithe 18 report the "current" state of the lid as either "opened" or "closed".
19 19
20 For most platforms, both the _LID method and t 20 For most platforms, both the _LID method and the lid notifications are
21 reliable. However, there are exceptions. In or 21 reliable. However, there are exceptions. In order to work with these
22 exceptional buggy platforms, special restricti 22 exceptional buggy platforms, special restrictions and exceptions should be
23 taken into account. This document describes th 23 taken into account. This document describes the restrictions and the
24 exceptions of the Linux ACPI lid device driver 24 exceptions of the Linux ACPI lid device driver.
25 25
26 26
27 Restrictions of the returning value of the _LI 27 Restrictions of the returning value of the _LID control method
28 ============================================== 28 ==============================================================
29 29
30 The _LID control method is described to return 30 The _LID control method is described to return the "current" lid state.
31 However the word of "current" has ambiguity, s 31 However the word of "current" has ambiguity, some buggy AML tables return
32 the lid state upon the last lid notification i 32 the lid state upon the last lid notification instead of returning the lid
33 state upon the last _LID evaluation. There won 33 state upon the last _LID evaluation. There won't be difference when the
34 _LID control method is evaluated during the ru 34 _LID control method is evaluated during the runtime, the problem is its
35 initial returning value. When the AML tables i 35 initial returning value. When the AML tables implement this control method
36 with cached value, the initial returning value 36 with cached value, the initial returning value is likely not reliable.
37 There are platforms always return "closed" as 37 There are platforms always return "closed" as initial lid state.
38 38
39 Restrictions of the lid state change notificat 39 Restrictions of the lid state change notifications
40 ============================================== 40 ==================================================
41 41
42 There are buggy AML tables never notifying whe 42 There are buggy AML tables never notifying when the lid device state is
43 changed to "opened". Thus the "opened" notific 43 changed to "opened". Thus the "opened" notification is not guaranteed. But
44 it is guaranteed that the AML tables always no 44 it is guaranteed that the AML tables always notify "closed" when the lid
45 state is changed to "closed". The "closed" not 45 state is changed to "closed". The "closed" notification is normally used to
46 trigger some system power saving operations on 46 trigger some system power saving operations on Windows. Since it is fully
47 tested, it is reliable from all AML tables. 47 tested, it is reliable from all AML tables.
48 48
49 Exceptions for the userspace users of the ACPI 49 Exceptions for the userspace users of the ACPI lid device driver
50 ============================================== 50 ================================================================
51 51
52 The ACPI button driver exports the lid state t 52 The ACPI button driver exports the lid state to the userspace via the
53 following file:: 53 following file::
54 54
55 /proc/acpi/button/lid/LID0/state 55 /proc/acpi/button/lid/LID0/state
56 56
57 This file actually calls the _LID control meth 57 This file actually calls the _LID control method described above. And given
58 the previous explanation, it is not reliable e 58 the previous explanation, it is not reliable enough on some platforms. So
59 it is advised for the userspace program to not 59 it is advised for the userspace program to not to solely rely on this file
60 to determine the actual lid state. 60 to determine the actual lid state.
61 61
62 The ACPI button driver emits the following inp 62 The ACPI button driver emits the following input event to the userspace:
63 * SW_LID 63 * SW_LID
64 64
65 The ACPI lid device driver is implemented to t 65 The ACPI lid device driver is implemented to try to deliver the platform
66 triggered events to the userspace. However, gi 66 triggered events to the userspace. However, given the fact that the buggy
67 firmware cannot make sure "opened"/"closed" ev 67 firmware cannot make sure "opened"/"closed" events are paired, the ACPI
68 button driver uses the following 3 modes in or 68 button driver uses the following 3 modes in order not to trigger issues.
69 69
70 If the userspace hasn't been prepared to ignor 70 If the userspace hasn't been prepared to ignore the unreliable "opened"
71 events and the unreliable initial state notifi 71 events and the unreliable initial state notification, Linux users can use
72 the following kernel parameters to handle the 72 the following kernel parameters to handle the possible issues:
73 73
74 A. button.lid_init_state=method: 74 A. button.lid_init_state=method:
75 When this option is specified, the ACPI but 75 When this option is specified, the ACPI button driver reports the
76 initial lid state using the returning value 76 initial lid state using the returning value of the _LID control method
77 and whether the "opened"/"closed" events ar 77 and whether the "opened"/"closed" events are paired fully relies on the
78 firmware implementation. 78 firmware implementation.
79 79
80 This option can be used to fix some platfor 80 This option can be used to fix some platforms where the returning value
81 of the _LID control method is reliable but 81 of the _LID control method is reliable but the initial lid state
82 notification is missing. 82 notification is missing.
83 83
84 This option is the default behavior during 84 This option is the default behavior during the period the userspace
85 isn't ready to handle the buggy AML tables. 85 isn't ready to handle the buggy AML tables.
86 86
87 B. button.lid_init_state=open: 87 B. button.lid_init_state=open:
88 When this option is specified, the ACPI but 88 When this option is specified, the ACPI button driver always reports the
89 initial lid state as "opened" and whether t 89 initial lid state as "opened" and whether the "opened"/"closed" events
90 are paired fully relies on the firmware imp 90 are paired fully relies on the firmware implementation.
91 91
92 This may fix some platforms where the retur 92 This may fix some platforms where the returning value of the _LID
93 control method is not reliable and the init 93 control method is not reliable and the initial lid state notification is
94 missing. 94 missing.
95 95
96 If the userspace has been prepared to ignore t 96 If the userspace has been prepared to ignore the unreliable "opened" events
97 and the unreliable initial state notification, 97 and the unreliable initial state notification, Linux users should always
98 use the following kernel parameter: 98 use the following kernel parameter:
99 99
100 C. button.lid_init_state=ignore: 100 C. button.lid_init_state=ignore:
101 When this option is specified, the ACPI but 101 When this option is specified, the ACPI button driver never reports the
102 initial lid state and there is a compensati 102 initial lid state and there is a compensation mechanism implemented to
103 ensure that the reliable "closed" notificat 103 ensure that the reliable "closed" notifications can always be delivered
104 to the userspace by always pairing "closed" 104 to the userspace by always pairing "closed" input events with complement
105 "opened" input events. But there is still n 105 "opened" input events. But there is still no guarantee that the "opened"
106 notifications can be delivered to the users 106 notifications can be delivered to the userspace when the lid is actually
107 opens given that some AML tables do not sen 107 opens given that some AML tables do not send "opened" notifications
108 reliably. 108 reliably.
109 109
110 In this mode, if everything is correctly im 110 In this mode, if everything is correctly implemented by the platform
111 firmware, the old userspace programs should 111 firmware, the old userspace programs should still work. Otherwise, the
112 new userspace programs are required to work 112 new userspace programs are required to work with the ACPI button driver.
113 This option will be the default behavior af 113 This option will be the default behavior after the userspace is ready to
114 handle the buggy AML tables. 114 handle the buggy AML tables.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.