Merge branch 'acpi-driver'

Merge updates of drivers handling devices defined in the ACPI
specification and other generic devices with ACPI interfaces for
6.20-rc1/7.0-rc1:

 - Add a piece of documentation explaining why binding drivers directly
   to ACPI device objects is not a good idea in general and why it is
   desirable to convert drivers doing so into proper platform drivers
   that use struct platform_driver for device binding (Rafael Wysocki)

 - Convert multiple "core ACPI" drivers, including the NFIT ACPI device
   driver, the generic ACPI button drivers, the generic ACPI thermal
   zone driver, the ACPI hardware event device (HED) driver, the ACPI EC
   driver, the ACPI SMBUS HC driver, the ACPI Smart Battery Subsystem
   (SBS) driver, and the ACPI backlight (video) driver to proper platform
   drivers that use struct platform_driver for device binding (Rafael
   Wysocki)

 - Use acpi_get_local_u64_address() in the ACPI backlight (video) driver
   to evaluate _ADR instead of evaluating that object directly (Andy
   Shevchenko)

* acpi-driver: (25 commits)
  ACPI: video: simplify code with acpi_get_local_u64_address()
  ACPI: scan: Clean up after recent changes
  ACPI: scan: Use acpi_setup_gpe_for_wake() for buttons
  ACPI: PM: Let acpi_dev_pm_attach() skip devices without ACPI PM
  ACPI: Documentation: driver-api: Disapprove of using ACPI drivers
  ACPI: video: Convert the driver to a platform one
  ACPI: video: Adjust event notification routine
  ACPI: scan: Register platform devices for backlight device objects
  ACPI: SBS: Convert the driver to a platform one
  ACPI: SMBUS HC: Convert the driver to a platform one
  ACPI: EC: Convert the driver to a platform one
  ACPI: EC: Register a platform device for ECDT EC
  ACPI: HED: Convert the driver to a platform one
  ACPI: thermal: Rework system suspend and resume handling
  ACPI: thermal: Convert the driver to a platform one
  ACPI: thermal: Adjust event notification routine
  ACPI: scan: Register platform devices for thermal zones
  ACPI: scan: Do not mark button ACPI devices as wakeup-capable
  ACPI: scan: Do not bind ACPI drivers to fixed event buttons
  ACPI: tiny-power-button: Convert the driver to a platform one
  ...

2 files changed, 81 insertions, 0 deletions

diff --git a/Documentation/driver-api/acpi/acpi-drivers.rst b/Documentation/driver-api/acpi/acpi-drivers.rst
new file mode 100644
index 000000000000..b1fbbddb8b4f
--- /dev/null
+++ b/Documentation/driver-api/acpi/acpi-drivers.rst
@@ -0,0 +1,80 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+=========================================
+Why using ACPI drivers is not a good idea
+=========================================
+
+:Copyright: |copy| 2026, Intel Corporation
+
+:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+
+Even though binding drivers directly to struct acpi_device objects, also
+referred to as "ACPI device nodes", allows basic functionality to be provided
+at least in some cases, there are problems with it, related to general
+consistency, sysfs layout, power management operation ordering, and code
+cleanliness.
+
+First of all, ACPI device nodes represent firmware entities rather than
+hardware and in many cases they provide auxiliary information on devices
+enumerated independently (like PCI devices or CPUs).  It is therefore generally
+questionable to assign resources to them because the entities represented by
+them do not decode addresses in the memory or I/O address spaces and do not
+generate interrupts or similar (all of that is done by hardware).
+
+Second, as a general rule, a struct acpi_device can only be a parent of another
+struct acpi_device.  If that is not the case, the location of the child device
+in the device hierarchy is at least confusing and it may not be straightforward
+to identify the piece of hardware providing functionality represented by it.
+However, binding a driver directly to an ACPI device node may cause that to
+happen if the given driver registers input devices or wakeup sources under it,
+for example.
+
+Next, using system suspend and resume callbacks directly on ACPI device nodes
+is also questionable because it may cause ordering problems to appear.  Namely,
+ACPI device nodes are registered before enumerating hardware corresponding to
+them and they land on the PM list in front of the majority of other device
+objects.  Consequently, the execution ordering of their PM callbacks may be
+different from what is generally expected.  Also, in general, dependencies
+returned by _DEP objects do not affect ACPI device nodes themselves, but the
+"physical" devices associated with them, which potentially is one more source
+of inconsistency related to treating ACPI device nodes as "real" device
+representation.
+
+All of the above means that binding drivers to ACPI device nodes should
+generally be avoided and so struct acpi_driver objects should not be used.
+
+Moreover, a device ID is necessary to bind a driver directly to an ACPI device
+node, but device IDs are not generally associated with all of them.  Some of
+them contain alternative information allowing the corresponding pieces of
+hardware to be identified, for example represeted by an _ADR object return
+value, and device IDs are not used in those cases.  In consequence, confusingly
+enough, binding an ACPI driver to an ACPI device node may even be impossible.
+
+When that happens, the piece of hardware corresponding to the given ACPI device
+node is represented by another device object, like a struct pci_dev, and the
+ACPI device node is the "ACPI companion" of that device, accessible through its
+fwnode pointer used by the ACPI_COMPANION() macro.  The ACPI companion holds
+additional information on the device configuration and possibly some "recipes"
+on device manipulation in the form of AML (ACPI Machine Language) bytecode
+provided by the platform firmware.  Thus the role of the ACPI device node is
+similar to the role of a struct device_node on a system where Device Tree is
+used for platform description.
+
+For consistency, this approach has been extended to the cases in which ACPI
+device IDs are used.  Namely, in those cases, an additional device object is
+created to represent the piece of hardware corresponding to a given ACPI device
+node.  By default, it is a platform device, but it may also be a PNP device, a
+CPU device, or another type of device, depending on what the given piece of
+hardware actually is.  There are even cases in which multiple devices are
+"backed" or "accompanied" by one ACPI device node (e.g. ACPI device nodes
+corresponding to GPUs that may provide firmware interfaces for backlight
+brightness control in addition to GPU configuration information).
+
+This means that it really should never be necessary to bind a driver directly to
+an ACPI device node because there is a "proper" device object representing the
+corresponding piece of hardware that can be bound to by a "proper" driver using
+the given ACPI device node as the device's ACPI companion.  Thus, in principle,
+there is no reason to use ACPI drivers and if they all were replaced with other
+driver types (for example, platform drivers), some code could be dropped and
+some complexity would go away.
diff --git a/Documentation/driver-api/acpi/index.rst b/Documentation/driver-api/acpi/index.rst
index ace0008e54c2..2b10d83f9994 100644
--- a/Documentation/driver-api/acpi/index.rst
+++ b/Documentation/driver-api/acpi/index.rst
@@ -7,3 +7,4 @@ ACPI Support
 
    linuxized-acpica
    scan_handlers
+   acpi-drivers