0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 =========================================================
0005 Special Usage Model of the ACPI Control Method Lid Device
0006 =========================================================
0007
0008 :Copyright: |copy| 2016, Intel Corporation
0009
0010 :Author: Lv Zheng <lv.zheng@intel.com>
0011
0012 Abstract
0013 ========
0014 Platforms containing lids convey lid state (open/close) to OSPMs
0015 using a control method lid device. To implement this, the AML tables issue
0016 Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has
0017 changed. The _LID control method for the lid device must be implemented to
0018 report the "current" state of the lid as either "opened" or "closed".
0019
0020 For most platforms, both the _LID method and the lid notifications are
0021 reliable. However, there are exceptions. In order to work with these
0022 exceptional buggy platforms, special restrictions and exceptions should be
0023 taken into account. This document describes the restrictions and the
0024 exceptions of the Linux ACPI lid device driver.
0025
0026
0027 Restrictions of the returning value of the _LID control method
0028 ==============================================================
0029
0030 The _LID control method is described to return the "current" lid state.
0031 However the word of "current" has ambiguity, some buggy AML tables return
0032 the lid state upon the last lid notification instead of returning the lid
0033 state upon the last _LID evaluation. There won't be difference when the
0034 _LID control method is evaluated during the runtime, the problem is its
0035 initial returning value. When the AML tables implement this control method
0036 with cached value, the initial returning value is likely not reliable.
0037 There are platforms always retun "closed" as initial lid state.
0038
0039 Restrictions of the lid state change notifications
0040 ==================================================
0041
0042 There are buggy AML tables never notifying when the lid device state is
0043 changed to "opened". Thus the "opened" notification is not guaranteed. But
0044 it is guaranteed that the AML tables always notify "closed" when the lid
0045 state is changed to "closed". The "closed" notification is normally used to
0046 trigger some system power saving operations on Windows. Since it is fully
0047 tested, it is reliable from all AML tables.
0048
0049 Exceptions for the userspace users of the ACPI lid device driver
0050 ================================================================
0051
0052 The ACPI button driver exports the lid state to the userspace via the
0053 following file::
0054
0055 /proc/acpi/button/lid/LID0/state
0056
0057 This file actually calls the _LID control method described above. And given
0058 the previous explanation, it is not reliable enough on some platforms. So
0059 it is advised for the userspace program to not to solely rely on this file
0060 to determine the actual lid state.
0061
0062 The ACPI button driver emits the following input event to the userspace:
0063 * SW_LID
0064
0065 The ACPI lid device driver is implemented to try to deliver the platform
0066 triggered events to the userspace. However, given the fact that the buggy
0067 firmware cannot make sure "opened"/"closed" events are paired, the ACPI
0068 button driver uses the following 3 modes in order not to trigger issues.
0069
0070 If the userspace hasn't been prepared to ignore the unreliable "opened"
0071 events and the unreliable initial state notification, Linux users can use
0072 the following kernel parameters to handle the possible issues:
0073
0074 A. button.lid_init_state=method:
0075 When this option is specified, the ACPI button driver reports the
0076 initial lid state using the returning value of the _LID control method
0077 and whether the "opened"/"closed" events are paired fully relies on the
0078 firmware implementation.
0079
0080 This option can be used to fix some platforms where the returning value
0081 of the _LID control method is reliable but the initial lid state
0082 notification is missing.
0083
0084 This option is the default behavior during the period the userspace
0085 isn't ready to handle the buggy AML tables.
0086
0087 B. button.lid_init_state=open:
0088 When this option is specified, the ACPI button driver always reports the
0089 initial lid state as "opened" and whether the "opened"/"closed" events
0090 are paired fully relies on the firmware implementation.
0091
0092 This may fix some platforms where the returning value of the _LID
0093 control method is not reliable and the initial lid state notification is
0094 missing.
0095
0096 If the userspace has been prepared to ignore the unreliable "opened" events
0097 and the unreliable initial state notification, Linux users should always
0098 use the following kernel parameter:
0099
0100 C. button.lid_init_state=ignore:
0101 When this option is specified, the ACPI button driver never reports the
0102 initial lid state and there is a compensation mechanism implemented to
0103 ensure that the reliable "closed" notifications can always be delivered
0104 to the userspace by always pairing "closed" input events with complement
0105 "opened" input events. But there is still no guarantee that the "opened"
0106 notifications can be delivered to the userspace when the lid is actually
0107 opens given that some AML tables do not send "opened" notifications
0108 reliably.
0109
0110 In this mode, if everything is correctly implemented by the platform
0111 firmware, the old userspace programs should still work. Otherwise, the
0112 new userspace programs are required to work with the ACPI button driver.
0113 This option will be the default behavior after the userspace is ready to
0114 handle the buggy AML tables.
