About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / acpi / acpi-lid.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:52 EST.

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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog