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