From patchwork Thu Jul 7 07:11:00 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Lv Zheng X-Patchwork-Id: 9217893 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 0FA536048B for ; Thu, 7 Jul 2016 07:12:46 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id F37EC28756 for ; Thu, 7 Jul 2016 07:12:45 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id E68E72875B; Thu, 7 Jul 2016 07:12:45 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=unavailable version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 450CB28757 for ; Thu, 7 Jul 2016 07:12:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756430AbcGGHMU (ORCPT ); Thu, 7 Jul 2016 03:12:20 -0400 Received: from mga14.intel.com ([192.55.52.115]:48408 "EHLO mga14.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1756356AbcGGHLr (ORCPT ); Thu, 7 Jul 2016 03:11:47 -0400 Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by fmsmga103.fm.intel.com with ESMTP; 07 Jul 2016 00:11:08 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.28,323,1464678000"; d="scan'208";a="1017134940" Received: from lvzheng-z530.sh.intel.com ([10.239.159.135]) by fmsmga002.fm.intel.com with ESMTP; 07 Jul 2016 00:11:05 -0700 From: Lv Zheng To: "Rafael J. Wysocki" , "Rafael J. Wysocki" , Len Brown Cc: Lv Zheng , Lv Zheng , , linux-acpi@vger.kernel.org, "Bastien Nocera:" , Benjamin Tissoires , linux-input@vger.kernel.org Subject: [PATCH v2 4/4] ACPI / button: Add document for ACPI control method lid device restrictions Date: Thu, 7 Jul 2016 15:11:00 +0800 Message-Id: <3f24a00df89f06661a64af6b4679a99bfff09aa7.1467875143.git.lv.zheng@intel.com> X-Mailer: git-send-email 1.7.10 In-Reply-To: References: Sender: linux-input-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP There are many AML tables reporting wrong initial lid state, and some of them never reports lid state. As a proxy layer acting between, ACPI button driver is not able to handle all such cases, but need to re-define the usage model of the ACPI lid. That is: 1. It's initial state is not reliable; 2. There may not be open event; 3. Userspace should only take action against the close event which is reliable, always sent after a real lid close. This patch adds documentation of the usage model. Link: https://lkml.org/2016/3/7/460 Link: https://github.com/systemd/systemd/issues/2087 Signed-off-by: Lv Zheng Cc: Bastien Nocera: Cc: Benjamin Tissoires Cc: linux-input@vger.kernel.org --- Documentation/acpi/acpi-lid.txt | 62 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 Documentation/acpi/acpi-lid.txt diff --git a/Documentation/acpi/acpi-lid.txt b/Documentation/acpi/acpi-lid.txt new file mode 100644 index 0000000..7e4f7ed --- /dev/null +++ b/Documentation/acpi/acpi-lid.txt @@ -0,0 +1,62 @@ +Usage Model of the ACPI Control Method Lid Device + +Copyright (C) 2016, Intel Corporation +Author: Lv Zheng + + +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". + +This document describes the restrictions and the expections of the Linux +ACPI lid device driver. + + +1. 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, many 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 +simply so many examples always retuning "closed" as initial lid state. + +2. Restrictions of the lid state change notifications + +There are many AML tables never notifying when the lid device state is +changed to "opened". But it is ensured that the AML tables always notify +"closed" when the lid state is changed to "closed". This is normally used +to trigger some system power saving operations on Windows. Since it is +fully tested, this notification is reliable for all AML tables. + +3. Expections for the userspace users of the ACPI lid device driver + +The userspace programs should stop relying on +/proc/acpi/button/lid/LID0/state to obtain the lid state. This file is only +used for the validation purpose. + +New userspace programs should rely on the lid "closed" notification to +trigger some power saving operations and may stop taking actions according +to the lid "opened" notification. A new input switch event - SW_ACPI_LID is +prepared for the new userspace to implement this ACPI control method lid +device specific logics. + +During the period the userspace hasn't been switched to use the new +SW_ACPI_LID event, Linux users can use the following boot parameter to +handle possible issues: + button.lid_init_state=method: + This is the default behavior of the Linux ACPI lid driver, Linux kernel + reports the initial lid state using the returning value of the _LID + control method. + This can be used to fix some platforms if the _LID control method's + returning value is reliable. + button.lid_init_state=open: + Linux kernel always reports the initial lid state as "opened". + This may fix some platforms if the returning value of the _LID control + method is not reliable.