Special Usage Model of the ACPI Control Method Lid Device

ACPI control method lid model

Lid가 있는 platform은 ACPI control method lid device를 통해 open·close 상태를 OSPM(Operating System-directed configuration and Power Management)에 전달한다. AML table은 상태가 바뀔 때마다 `Notify(lid_device, 0x80)`를 발행하고, lid device의 `_LID` control method는 현재 상태를 opened 또는 closed로 보고해야 한다.

대부분의 platform에서는 `_LID`와 lid notification이 모두 신뢰할 수 있다. 그러나 일부 firmware의 buggy AML table은 초기 상태나 event pair를 올바르게 제공하지 않으므로 Linux ACPI lid driver와 userspace가 특별한 제한과 예외를 고려해야 한다.

핵심은 method evaluation 결과와 asynchronous notification을 서로 독립적인 신호로 보는 것이다. 어느 한쪽만으로 실제 lid 상태를 확정하면 초기 boot 또는 open event 누락 시 잘못된 판단을 할 수 있다.

.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

=========================================================
Special Usage Model of the ACPI Control Method Lid Device
=========================================================

:Copyright: |copy| 2016, Intel Corporation

:Author: Lv Zheng <lv.zheng@intel.com>

Abstract
========
Platforms containing lids convey lid state (open/close) to OSPMs
using a control method lid device. To implement this, the AML tables issue
Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has
changed. The _LID control method for the lid device must be implemented to
report the "current" state of the lid as either "opened" or "closed".

For most platforms, both the _LID method and the lid notifications are
reliable. However, there are exceptions. In order to work with these
exceptional buggy platforms, special restrictions and exceptions should be
taken into account. This document describes the restrictions and the
exceptions of the Linux ACPI lid device driver.

_LID 반환값의 current 의미

ACPI 설명에서 `_LID`는 current lid state를 반환한다고 하지만 일부 AML은 current를 마지막 `_LID` evaluation 시점이 아니라 마지막 lid notification 시점의 상태로 구현한다. Runtime에 notification 뒤 즉시 평가하면 두 의미가 같아 보일 수 있으나 boot 초기값에서는 차이가 드러난다.

AML table이 cached value로 `_LID`를 구현하면 notification이 한 번도 오기 전의 cache가 초기화되지 않았거나 고정값일 수 있다. 실제 lid가 열려 있어도 최초 evaluation에서 항상 closed를 반환하는 platform이 존재한다.

따라서 초기 `_LID` result는 반드시 물리 상태의 fresh read라고 가정할 수 없다. Driver mode를 고를 때 method의 runtime 신뢰성과 initial state 신뢰성을 분리해 평가해야 한다.

Restrictions of the returning value of the _LID control method
==============================================================

The _LID control method is described to return the "current" lid state.
However the word of "current" has ambiguity, some buggy AML tables return
the lid state upon the last lid notification instead of returning the lid
state upon the last _LID evaluation. There won't be difference when the
_LID control method is evaluated during the runtime, the problem is its
initial returning value. When the AML tables implement this control method
with cached value, the initial returning value is likely not reliable.
There are platforms always return "closed" as initial lid state.

Restrictions of the lid state change notifications
==================================================

Open notification 누락과 close 신뢰성

일부 buggy AML table은 lid가 opened로 바뀔 때 notification을 전혀 보내지 않는다. 그러므로 opened notification은 보장되지 않고, open·close event가 항상 pair로 도착한다고 가정할 수 없다.

반면 closed 전이는 항상 notification한다고 본다. Windows에서 closed event가 system power-saving operation을 trigger하는 데 널리 쓰이고 충분히 test되었기 때문에 AML table 전반에서 신뢰할 수 있다는 것이 이 문서의 전제다.

Userspace state machine은 close 뒤 반드시 실제 open event가 올 것이라 기다리면 안 된다. Linux의 보상 mode는 신뢰 가능한 closed event를 전달하기 위해 synthetic complement opened event를 사용할 수 있지만, 물리적으로 lid가 열리는 순간의 notification 자체를 복원할 수는 없다.

There are buggy AML tables never notifying when the lid device state is
changed to "opened". Thus the "opened" notification is not guaranteed. But
it is guaranteed that the AML tables always notify "closed" when the lid
state is changed to "closed". The "closed" notification is normally used to
trigger some system power saving operations on Windows. Since it is fully
tested, it is reliable from all AML tables.

Exceptions for the userspace users of the ACPI lid device driver
================================================================

Proc state와 SW_LID event

ACPI button driver는 `/proc/acpi/button/lid/LID0/state`를 통해 lid state를 userspace에 노출한다. 이 file을 읽으면 앞서 설명한 `_LID` control method를 실제로 호출하므로 buggy platform에서는 초기값이나 cached state 문제를 그대로 가진다.

따라서 userspace program은 이 proc file 하나만으로 실제 lid 상태를 판단하지 않는 것이 좋다. Driver는 input subsystem으로 `SW_LID` event도 내보내며 platform이 trigger한 event를 가능한 한 userspace에 전달하려 한다.

하지만 firmware가 opened·closed event pair를 보장하지 않으므로 driver는 문제를 줄이기 위해 세 가지 `button.lid_init_state` mode를 제공한다. Userspace가 unreliable opened event와 initial notification을 무시할 준비가 되었는지에 따라 mode를 선택한다.

The ACPI button driver exports the lid state to the userspace via the
following file::

  /proc/acpi/button/lid/LID0/state

This file actually calls the _LID control method described above. And given
the previous explanation, it is not reliable enough on some platforms. So
it is advised for the userspace program to not to solely rely on this file
to determine the actual lid state.

The ACPI button driver emits the following input event to the userspace:
  * SW_LID

The ACPI lid device driver is implemented to try to deliver the platform
triggered events to the userspace. However, given the fact that the buggy
firmware cannot make sure "opened"/"closed" events are paired, the ACPI
button driver uses the following 3 modes in order not to trigger issues.

If the userspace hasn't been prepared to ignore the unreliable "opened"

method·open 초기화 mode

기존 userspace가 unreliable opened event와 initial notification을 무시할 준비가 되지 않았다면 `button.lid_init_state=method` 또는 `button.lid_init_state=open`을 사용할 수 있다. 두 mode 모두 이후 opened·closed event pairing은 firmware 구현에 의존한다.

`method`는 `_LID` 반환값으로 initial lid state를 보고한다. `_LID` result는 신뢰할 수 있지만 initial notification만 누락되는 platform을 보완할 수 있으며, buggy AML을 userspace가 아직 처리하지 못하던 기간의 기본 동작이다.

`open`은 initial state를 항상 opened로 보고한다. `_LID` initial result가 신뢰할 수 없고 initial notification도 없는 platform에서 잘못된 closed 초기값 때문에 suspend 같은 동작이 발생하는 문제를 피할 수 있다.

events and the unreliable initial state notification, Linux users can use
the following kernel parameters to handle the possible issues:

A. button.lid_init_state=method:
   When this option is specified, the ACPI button driver reports the
   initial lid state using the returning value of the _LID control method
   and whether the "opened"/"closed" events are paired fully relies on the
   firmware implementation.

   This option can be used to fix some platforms where the returning value
   of the _LID control method is reliable but the initial lid state
   notification is missing.

   This option is the default behavior during the period the userspace
   isn't ready to handle the buggy AML tables.

B. button.lid_init_state=open:
   When this option is specified, the ACPI button driver always reports the
   initial lid state as "opened" and whether the "opened"/"closed" events
   are paired fully relies on the firmware implementation.

ignore mode와 complement event

Userspace가 unreliable opened event와 initial state notification을 무시할 수 있다면 `button.lid_init_state=ignore`를 사용해야 한다. 이 mode에서는 driver가 initial lid state를 전혀 보고하지 않는다.

신뢰 가능한 closed notification이 항상 userspace에 전달되도록 driver는 closed input event 앞에 보완용 complement opened input event를 짝지어 보낸다. 이는 input state가 이미 closed라서 같은 closed event가 억제되는 문제를 피하기 위한 pairing이다.

그러나 firmware가 물리 open 전이를 알리지 않으면 실제로 lid가 열린 시점의 opened notification을 보장할 수는 없다. Synthetic event는 closed 전달을 위한 protocol 보상이지 physical state observation을 새로 만드는 것이 아니다.

Platform firmware가 올바르면 기존 userspace도 이 mode에서 계속 동작할 수 있다. 그렇지 않으면 새로운 userspace가 driver의 불완전한 event model을 처리해야 하며, 문서는 userspace가 준비된 뒤 `ignore`가 기본 동작이 될 예정이라고 설명한다.

   This may fix some platforms where the returning value of the _LID
   control method is not reliable and the initial lid state notification is
   missing.

If the userspace has been prepared to ignore the unreliable "opened" events
and the unreliable initial state notification, Linux users should always
use the following kernel parameter:

C. button.lid_init_state=ignore:
   When this option is specified, the ACPI button driver never reports the
   initial lid state and there is a compensation mechanism implemented to
   ensure that the reliable "closed" notifications can always be delivered
   to the userspace by always pairing "closed" input events with complement
   "opened" input events. But there is still no guarantee that the "opened"
   notifications can be delivered to the userspace when the lid is actually
   opens given that some AML tables do not send "opened" notifications
   reliably.

   In this mode, if everything is correctly implemented by the platform
   firmware, the old userspace programs should still work. Otherwise, the
   new userspace programs are required to work with the ACPI button driver.
   This option will be the default behavior after the userspace is ready to
   handle the buggy AML tables.