Documentation/firmware-guide/acpi/acpi-lid.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: <isonum.txt>
   3
   4 =========================================================
   5 Special 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
  12 Abstract
  13 ========
  14 Platforms containing lids convey lid state (open/close) to OSPMs
  15 using a control method lid device. To implement this, the AML tables issue
  16 Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has
  17 changed. The _LID control method for the lid device must be implemented to
  18 report the "current" state of the lid as either "opened" or "closed".
  19
  20 For most platforms, both the _LID method and the lid notifications are
  21 reliable. However, there are exceptions. In order to work with these
  22 exceptional buggy platforms, special restrictions and expections should be
  23 taken into account. This document describes the restrictions and the
  24 expections of the Linux ACPI lid device driver.
  25
  26
  27 Restrictions of the returning value of the _LID control method
  28 ==============================================================
  29
  30 The _LID control method is described to return the "current" lid state.
  31 However the word of "current" has ambiguity, some buggy AML tables return
  32 the lid state upon the last lid notification instead of returning the lid
  33 state 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
  35 initial returning value. When the AML tables implement this control method
  36 with cached value, the initial returning value is likely not reliable.
  37 There are platforms always retun "closed" as initial lid state.
  38
  39 Restrictions of the lid state change notifications
  40 ==================================================
  41
  42 There are buggy AML tables never notifying when the lid device state is
  43 changed to "opened". Thus the "opened" notification is not guaranteed. But
  44 it is guaranteed that the AML tables always notify "closed" when the lid
  45 state is changed to "closed". The "closed" notification is normally used to
  46 trigger some system power saving operations on Windows. Since it is fully
  47 tested, it is reliable from all AML tables.
  48
  49 Expections for the userspace users of the ACPI lid device driver
  50 ================================================================
  51
  52 The ACPI button driver exports the lid state to the userspace via the
  53 following file::
  54
  55   /proc/acpi/button/lid/LID0/state
  56
  57 This file actually calls the _LID control method described above. And given
  58 the previous explanation, it is not reliable enough on some platforms. So
  59 it is advised for the userspace program to not to solely rely on this file
  60 to determine the actual lid state.
  61
  62 The ACPI button driver emits the following input event to the userspace:
  63   * SW_LID
  64
  65 The ACPI lid device driver is implemented to try to deliver the platform
  66 triggered events to the userspace. However, given the fact that the buggy
  67 firmware cannot make sure "opened"/"closed" events are paired, the ACPI
  68 button driver uses the following 3 modes in order not to trigger issues.
  69
  70 If the userspace hasn't been prepared to ignore the unreliable "opened"
  71 events and the unreliable initial state notification, Linux users can use
  72 the following kernel parameters to handle the possible issues:
  73
  74 A. 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
  87 B. 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
  96 If the userspace has been prepared to ignore the unreliable "opened" events
  97 and the unreliable initial state notification, Linux users should always
  98 use the following kernel parameter:
  99
 100 C. 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 delievered
 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.