summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2016-10-03 10:11:58 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2016-10-03 10:11:58 -0700
commit72d39926f098b0c4ad95e1461595a8d6d403c14d (patch)
treeb540b63f61ed04752528c3ca4bce42b4a7d7a28a /Documentation
parent72ec94560d7ee1d3a61d5904fd9a5bf68bf3b11a (diff)
parent8c4b172123c08a7138ee01675c130c83f9c1117c (diff)
Merge tag 'acpi-4.9-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm
Pull ACPI updates from Rafael Wysocki: "First off, the ACPICA code in the kernel is updated to upstream revision 20160831 that brings in a few bug fixes and cleanups. In particular, it is possible to mask GPEs now (and the sysfs interface for GPE control is fixed on top of that), problems related to the table loading mechanism are fixed and all code related to FADT version 2 (which has never been part of the ACPI specification) is dropped. On the new features front, there is a new watchdog driver based on the ACPI WDAT (ACPI Watchdog Action Table), needed on some platforms to replace the iTCO watchdog that doesn't work there, and some UART devices get new definitions of built-in properties (to be accessed via the generic device properties API). Also, included is a fix for an ACPI-related PCI resorces allocation issue and a few problems in the EC driver and in the button and battery drivers are fixed. In addition to that, the ACPI CPPC library is updated to make batching of requests sent over the PCC channel possible (which reduces the PCC usage overhead substantially in some cases) and to support functional fixed hardware (FFH) type of CPPC registers access (which will allow CPPC to be used on x86 too in the future). As usual, there are some assorted fixes and cleanups too. Specifics: - Update of the ACPICA code in the kernel to upstream revision 20160831 with the following major changes: * New mechanism for GPE masking. * Fixes for issues related to the LoadTable operator and table loading. * Fixes for issues related to so-called module-level code (MLC), that is AML that doesn't belong to any methods. * Change of the return value of the _OSI method to reflect the Windows behavior. * GAS (Generic Address Structure) support fix related to 32-bit FADT addresses. * Elimination of unnecessary FADT version 2 support. * ACPI tools fixes and cleanups. From Bob Moore, Lv Zheng, and Jung-uk Kim. - ACPI sysfs interface updates to fix GPE handling (on top of the new GPE masking mechanism in ACPICA) and issues related to table loading (Lv Zheng). - New watchdog driver based on the ACPI WDAT (ACPI Watchdog Action Table), needed on some platforms to replace the iTCO watchdog that doesn't work there and related updates of the intel_pmc_ipc, i2c/i801 and MFD/lcp_ich drivers (Mika Westerberg). - Driver core fix to prevent it from leaking secondary fwnode objects during device removal (Lukas Wunner). - New definitions of built-in properties for UART in ACPI-based x86 SoC drivers and a 8250_dw driver quirk for the APM X-Gene SoC (Heikki Krogerus). - New device ID for the Vulcan SPI controller and constification of local strucures in the AMD SoC (APD) ACPI driver (Kamlakant Patel, Julia Lawall). - Fix for a bug causing the allocation of PCI resorces to fail if ACPI-enumerated child platform devices are registered below the PCI devices in question (Mika Westerberg). - Change of the default polarity for PCI legacy IRQs to high on systems booting wth ACPI on platforms with a GIC interrupt controller model fixing the discrepancy between the specification and HW behavior (Lorenzo Pieralisi). - Fixes for the handling of system suspend/resume in the ACPI EC driver and update of that driver to make it cope with the cases when the EC device defined in the ECDT has to be used throughout the entire system life cycle (Lv Zheng). - Update of the ACPI CPPC library to allow it to batch requests sent over the PCC channel (to reduce overhead), to support the fixed functional hardware (FFH) CPPC registers access type, to notify the mailbox framework about TX completions when the interrupt flag is set for the PCC mailbox, and to support HW-Reduced Communication Subspace type 2 (Ashwin Chaugule, Prashanth Prakash, Srinivas Pandruvada, Hoan Tran). - ACPI button driver fix and documentation update related to the handling of laptop lids (Lv Zheng). - ACPI battery driver initialization fix (Carlos Garnacho). - ACPI GPIO enumeration documentation update (Mika Westerberg). - Assorted updates of the core ACPI bus type code (Lukas Wunner, Lv Zheng). - Assorted cleanups of the ACPI table parsing code and the x86-specific ACPI code (Al Stone). - Fixes for assorted ACPI-related issues found in linux-next (Wei Yongjun)" * tag 'acpi-4.9-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm: (98 commits) ACPI / documentation: Use recommended name in GPIO property names watchdog: wdat_wdt: Fix warning for using 0 as NULL watchdog: wdat_wdt: fix return value check in wdat_wdt_probe() platform/x86: intel_pmc_ipc: Do not create iTCO watchdog when WDAT table exists i2c: i801: Do not create iTCO watchdog when WDAT table exists mfd: lpc_ich: Do not create iTCO watchdog when WDAT table exists ACPI / bus: Adjust ACPI subsystem initialization for new table loading mode ACPICA: Parser: Fix a regression in LoadTable support ACPICA: Tables: Fix "UNLOAD" code path lock issues ACPI / watchdog: Add support for WDAT hardware watchdog ACPI / platform: Pay attention to parent device's resources PCI: Add pci_find_resource() ACPI / CPPC: Support PCC with interrupt flag ACPI / sysfs: Update sysfs signature handling code ACPI / sysfs: Fix an issue for LoadTable opcode ACPICA: Tables: Fix a regression in acpi_tb_find_table() ACPI / tables: Remove duplicated include from tables.c ACPI / APD: constify local structures x86: ACPI: make variable names clearer in acpi_parse_madt_lapic_entries() x86: ACPI: remove extraneous white space after semicolon ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/acpi/acpi-lid.txt96
-rw-r--r--Documentation/acpi/gpio-properties.txt10
2 files changed, 101 insertions, 5 deletions
diff --git a/Documentation/acpi/acpi-lid.txt b/Documentation/acpi/acpi-lid.txt
new file mode 100644
index 000000000000..effe7af3a5af
--- /dev/null
+++ b/Documentation/acpi/acpi-lid.txt
@@ -0,0 +1,96 @@
+Special Usage Model of the ACPI Control Method Lid Device
+
+Copyright (C) 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 expections should be
+taken into account. 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, 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 retun "closed" as initial lid state.
+
+2. Restrictions of the lid state change notifications
+
+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.
+
+3. Expections for the userspace users of the ACPI lid device driver
+
+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"
+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.
+ 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 delievered
+ 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.
diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt
index f35dad11f0de..5aafe0b351a1 100644
--- a/Documentation/acpi/gpio-properties.txt
+++ b/Documentation/acpi/gpio-properties.txt
@@ -28,8 +28,8 @@ index, like the ASL example below shows:
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package ()
{
- Package () {"reset-gpio", Package() {^BTH, 1, 1, 0 }},
- Package () {"shutdown-gpio", Package() {^BTH, 0, 0, 0 }},
+ Package () {"reset-gpios", Package() {^BTH, 1, 1, 0 }},
+ Package () {"shutdown-gpios", Package() {^BTH, 0, 0, 0 }},
}
})
}
@@ -48,7 +48,7 @@ Since ACPI GpioIo() resource does not have a field saying whether it is
active low or high, the "active_low" argument can be used here. Setting
it to 1 marks the GPIO as active low.
-In our Bluetooth example the "reset-gpio" refers to the second GpioIo()
+In our Bluetooth example the "reset-gpios" refers to the second GpioIo()
resource, second pin in that resource with the GPIO number of 31.
ACPI GPIO Mappings Provided by Drivers
@@ -83,8 +83,8 @@ static const struct acpi_gpio_params reset_gpio = { 1, 1, false };
static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false };
static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = {
- { "reset-gpio", &reset_gpio, 1 },
- { "shutdown-gpio", &shutdown_gpio, 1 },
+ { "reset-gpios", &reset_gpio, 1 },
+ { "shutdown-gpios", &shutdown_gpio, 1 },
{ },
};