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