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