ACPI: Documentation: driver-api: Disapprove of using ACPI drivers

ACPI: Documentation: driver-api: Disapprove of using ACPI drivers

Sadly, there is quite a bit of technical debt related to the
kernel's ACPI support subsystem and one of the most significant
pieces of it is the existence and use of ACPI drivers represented
by struct acpi_driver objects.

Those drivers are bound directly to struct acpi_device objects, also
referred to as "ACPI device nodes", representing device objects in the
ACPI namespace defined as:

 A hierarchical tree structure in OS-controlled memory that contains
 named objects. These objects may be data objects, control method
 objects, bus/device package objects, and so on.

according to the ACPI specification [1].

The above definition implies, although rather indirectly, that the
objects in question don't really represent hardware.  They are just
"device package objects" containing some information on the devices
present in the given platform that is known to the platform firmware.

Although the platform firmware can be the only source of information on
some devices, the information provided by it alone may be insufficient
for device enumeration in general.  If that is the case, binding a
driver directly to a given ACPI device node clearly doesn't make sense.
If the device in question is enumerated through a hardware interface, it
will be represented by a device object matching that interface, like
a struct pci_dev, and the ACPI device node corresponding to it will be
treated as its "ACPI companions" whose role is to amend the "native"
enumeratiom mechanism.

For the sake of consistency and confusion avoidance, it is better to
treat ACPI device nodes in general as ACPI companions of other device
objects representing hardware.  In some cases though it appeared easier
to take a shortcut and use an ACPI driver binding directly to an ACPI
device node.  Moreover, there were corner cases in which that was the
only choice, but they all have been addressed now.

In all cases in which an ACPI driver might be used, the ACPI device
node it might bind to is an ACPI companion of another device object
representing a piece of hardware.  It is thus better to use a driver
binding to the latter than to use an ACPI driver and leave the other
device object alone, not just because doing so is more consistent and
less confusing, but also because using ACPI drivers may lead to
potential functional deficiencies, like possible ordering issues
related to power management.

Unfortunately, there are quite a few ACPI drivers in use and, as a rule,
they bind to ACPI device nodes that are ACPI companions of platform
devices, so in fact they play the role of platform drivers although in
a kind of convoluted way.  An effort has been under way to replace them
with platform drivers, which is relatively straightforward in the vast
majority of cases, but it has not been pursued very aggressively so far,
mostly due to the existence of the corner cases mentioned above.
However, since those corner cases are gone now, it makes sense to spend
more time on driver conversions with the ultimate goal to get rid of
struct acpi_driver and the related code from the kernel.

To that end, add a document explaining why using ACPI drivers is not
a good idea, so it need not be explained from scratch on every attempt
to convert an ACPI driver to a platform one.

Link: https://uefi.org/specs/ACPI/6.6/02_Definition_of_Terms.html#term-ACPI-Namespace
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Armin Wolf <W_Armin@gmx.de>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Danilo Krummrich <dakr@kernel.org>
Reviewed-by: Mario Limonciello (AMD) <superm1@kernel.org>
Link: https://patch.msgid.link/2396510.ElGaqSPkdT@rafael.j.wysocki