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, 100 insertions, 0 deletions

diff --git a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst
new file mode 100644
index 000000000000..4306f29b6103
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst
@@ -0,0 +1,100 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================
+_DSD Device Properties Usage Rules
+==================================
+
+Properties, Property Sets and Property Subsets
+==============================================
+
+The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1,
+allows any type of device configuration data to be provided via the ACPI
+namespace.  In principle, the format of the data may be arbitrary, but it has to
+be identified by a UUID which must be recognized by the driver processing the
+_DSD output.  However, there are generic UUIDs defined for _DSD recognized by
+the ACPI subsystem in the Linux kernel which automatically processes the data
+packages associated with them and makes those data available to device drivers
+as "device properties".
+
+A device property is a data item consisting of a string key and a value (of a
+specific type) associated with it.
+
+In the ACPI _DSD context it is an element of the sub-package following the
+generic Device Properties UUID in the _DSD return package as specified in the
+Device Properties UUID definition document [1]_.
+
+It also may be regarded as the definition of a key and the associated data type
+that can be returned by _DSD in the Device Properties UUID sub-package for a
+given device.
+
+A property set is a collection of properties applicable to a hardware entity
+like a device.  In the ACPI _DSD context it is the set of all properties that
+can be returned in the Device Properties UUID sub-package for the device in
+question.
+
+Property subsets are nested collections of properties.  Each of them is
+associated with an additional key (name) allowing the subset to be referred
+to as a whole (and to be treated as a separate entity).  The canonical
+representation of property subsets is via the mechanism specified in the
+Hierarchical Properties Extension UUID definition document [2]_.
+
+Property sets may be hierarchical.  That is, a property set may contain
+multiple property subsets that each may contain property subsets of its
+own and so on.
+
+General Validity Rule for Property Sets
+=======================================
+
+Valid property sets must follow the guidance given by the Device Properties UUID
+definition document [1].
+
+_DSD properties are intended to be used in addition to, and not instead of, the
+existing mechanisms defined by the ACPI specification.  Therefore, as a rule,
+they should only be used if the ACPI specification does not make direct
+provisions for handling the underlying use case.  It generally is invalid to
+return property sets which do not follow that rule from _DSD in data packages
+associated with the Device Properties UUID.
+
+Additional Considerations
+-------------------------
+
+There are cases in which, even if the general rule given above is followed in
+principle, the property set may still not be regarded as a valid one.
+
+For example, that applies to device properties which may cause kernel code
+(either a device driver or a library/subsystem) to access hardware in a way
+possibly leading to a conflict with AML methods in the ACPI namespace.  In
+particular, that may happen if the kernel code uses device properties to
+manipulate hardware normally controlled by ACPI methods related to power
+management, like _PSx and _DSW (for device objects) or _ON and _OFF (for power
+resource objects), or by ACPI device disabling/enabling methods, like _DIS and
+_SRS.
+
+In all cases in which kernel code may do something that will confuse AML as a
+result of using device properties, the device properties in question are not
+suitable for the ACPI environment and consequently they cannot belong to a valid
+property set.
+
+Property Sets and Device Tree Bindings
+======================================
+
+It often is useful to make _DSD return property sets that follow Device Tree
+bindings.
+
+In those cases, however, the above validity considerations must be taken into
+account in the first place and returning invalid property sets from _DSD must be
+avoided.  For this reason, it may not be possible to make _DSD return a property
+set following the given DT binding literally and completely.  Still, for the
+sake of code re-use, it may make sense to provide as much of the configuration
+data as possible in the form of device properties and complement that with an
+ACPI-specific mechanism suitable for the use case at hand.
+
+In any case, property sets following DT bindings literally should not be
+expected to automatically work in the ACPI environment regardless of their
+contents.
+
+References
+==========
+
+.. [1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+.. [2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf