Merge tag 'acpi-5.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm

Pull ACPI updates from Rafael Wysocki:
 "These rearrange the ACPI documentation by converting it to the .rst
  format and splitting it into clear categories (admin guide, driver
  API, firmware guide), switch over multiple users of a problematic
  library function to a new better one, update the ACPICA code in the
  kernel to a new upstream release, fix a few issues, improve power
  device management diagnostics and do some cleanups.

  Specifics:

   - Convert the ACPI documentation in the kernel source tree to the
     .rst format and split it into the admin guide, driver API and
     firmware guide parts (Changbin Du).

   - Add a PRP0001 usage example to the ACPI documentation (Thomas
     Preston).

   - Switch over the users of the acpi_dev_get_first_match_name()
     library function which turned out to be problematic to a new,
     better one called acpi_dev_get_first_match_dev() (Andy Shevchenko,
     YueHaibing).

   - Update the ACPICA code in the kernel to upstream release 20190405
     including:
       * Null pointer dereference check in acpi_ns_delete_node() (Erik
         Schmauss).
       * Multiple macro and function name changes (Bob Moore).
       * Predefined operation region name fix (Erik Schmauss).

   - Fix hibernation issue on systems using the Baytrail and Cherrytrail
     Intel SoCs introduced during the 4.20 development cycle (Hans de
     Goede).

   - Add Sony VPCEH3U1E to the backlight quirk list (Zhang Rui).

   - Fix button handling during system resume (Zhang Rui).

   - Add a device PM diagnostic message (Rafael Wysocki).

   - Clean up the code, comments and white space in multiple places
     (Bjorn Helgaas, Gustavo Silva, Kefeng Wang)"

* tag 'acpi-5.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm: (53 commits)
  Documentation: ACPI: move video_extension.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move ssdt-overlays.txt to admin-guide/acpi and convert to reST
  Documentation: ACPI: move lpit.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move cppc_sysfs.txt to admin-guide/acpi and convert to reST
  Documentation: ACPI: move apei/einj.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move apei/output_format.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move aml-debugger.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move method-tracing.txt to firmware-guide/acpi and convert to rsST
  Documentation: ACPI: move debug.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move dsd/data-node-references.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move dsd/graph.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move acpi-lid.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move i2c-muxes.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move dsdt-override.txt to admin-guide/acpi and convert to reST
  Documentation: ACPI: move initrd_table_override.txt to admin-guide/acpi and convert to reST
  Documentation: ACPI: move method-customizing.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move gpio-properties.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move DSD-properties-rules.txt to firmware-guide/acpi and covert to reST
  Documentation: ACPI: move scan_handlers.txt to driver-api/acpi and convert to reST
  Documentation: ACPI: move linuxized-acpica.txt to driver-api/acpi and convert to reST
  ...

1 files changed, 115 insertions, 0 deletions

diff --git a/Documentation/admin-guide/acpi/initrd_table_override.rst b/Documentation/admin-guide/acpi/initrd_table_override.rst
new file mode 100644
index 000000000000..cbd768207631
--- /dev/null
+++ b/Documentation/admin-guide/acpi/initrd_table_override.rst
@@ -0,0 +1,115 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
+Upgrading ACPI tables via initrd
+================================
+
+What is this about
+==================
+
+If the ACPI_TABLE_UPGRADE compile option is true, it is possible to
+upgrade the ACPI execution environment that is defined by the ACPI tables
+via upgrading the ACPI tables provided by the BIOS with an instrumented,
+modified, more recent version one, or installing brand new ACPI tables.
+
+When building initrd with kernel in a single image, option
+ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this
+feature to work.
+
+For a full list of ACPI tables that can be upgraded/installed, take a look
+at the char `*table_sigs[MAX_ACPI_SIGNATURE];` definition in
+drivers/acpi/tables.c.
+
+All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
+be overridable, except:
+
+  - ACPI_SIG_RSDP (has a signature of 6 bytes)
+  - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
+
+Both could get implemented as well.
+
+
+What is this for
+================
+
+Complain to your platform/BIOS vendor if you find a bug which is so severe
+that a workaround is not accepted in the Linux kernel. And this facility
+allows you to upgrade the buggy tables before your platform/BIOS vendor
+releases an upgraded BIOS binary.
+
+This facility can be used by platform/BIOS vendors to provide a Linux
+compatible environment without modifying the underlying platform firmware.
+
+This facility also provides a powerful feature to easily debug and test
+ACPI BIOS table compatibility with the Linux kernel by modifying old
+platform provided ACPI tables or inserting new ACPI tables.
+
+It can and should be enabled in any kernel because there is no functional
+change with not instrumented initrds.
+
+
+How does it work
+================
+::
+
+  # Extract the machine's ACPI tables:
+  cd /tmp
+  acpidump >acpidump
+  acpixtract -a acpidump
+  # Disassemble, modify and recompile them:
+  iasl -d *.dat
+  # For example add this statement into a _PRT (PCI Routing Table) function
+  # of the DSDT:
+  Store("HELLO WORLD", debug)
+  # And increase the OEM Revision. For example, before modification:
+  DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
+  # After modification:
+  DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
+  iasl -sa dsdt.dsl
+  # Add the raw ACPI tables to an uncompressed cpio archive.
+  # They must be put into a /kernel/firmware/acpi directory inside the cpio
+  # archive. Note that if the table put here matches a platform table
+  # (similar Table Signature, and similar OEMID, and similar OEM Table ID)
+  # with a more recent OEM Revision, the platform table will be upgraded by
+  # this table. If the table put here doesn't match a platform table
+  # (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
+  # ID), this table will be appended.
+  mkdir -p kernel/firmware/acpi
+  cp dsdt.aml kernel/firmware/acpi
+  # A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
+  # (see osl.c):
+  iasl -sa facp.dsl
+  iasl -sa ssdt1.dsl
+  cp facp.aml kernel/firmware/acpi
+  cp ssdt1.aml kernel/firmware/acpi
+  # The uncompressed cpio archive must be the first. Other, typically
+  # compressed cpio archives, must be concatenated on top of the uncompressed
+  # one. Following command creates the uncompressed cpio archive and
+  # concatenates the original initrd on top:
+  find kernel | cpio -H newc --create > /boot/instrumented_initrd
+  cat /boot/initrd >>/boot/instrumented_initrd
+  # reboot with increased acpi debug level, e.g. boot params:
+  acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
+  # and check your syslog:
+  [    1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
+  [    1.272091] [ACPI Debug]  String [0x0B] "HELLO WORLD"
+
+iasl is able to disassemble and recompile quite a lot different,
+also static ACPI tables.
+
+
+Where to retrieve userspace tools
+=================================
+
+iasl and acpixtract are part of Intel's ACPICA project:
+http://acpica.org/
+
+and should be packaged by distributions (for example in the acpica package
+on SUSE).
+
+acpidump can be found in Len Browns pmtools:
+ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
+
+This tool is also part of the acpica package on SUSE.
+Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
+/sys/firmware/acpi/tables