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 [1]
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

Rafael J. Wysocki 5 months ago b8c8a8ea 02c057dd

+81

2 changed files

expand all

Documentation

driver-api

acpi

acpi-drivers.rst

index.rst

+80

Documentation/driver-api/acpi/acpi-drivers.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + .. include:: <isonum.txt> 3 + 4 + ========================================= 5 + Why using ACPI drivers is not a good idea 6 + ========================================= 7 + 8 + :Copyright: |copy| 2026, Intel Corporation 9 + 10 + :Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> 11 + 12 + Even though binding drivers directly to struct acpi_device objects, also 13 + referred to as "ACPI device nodes", allows basic functionality to be provided 14 + at least in some cases, there are problems with it, related to general 15 + consistency, sysfs layout, power management operation ordering, and code 16 + cleanliness. 17 + 18 + First of all, ACPI device nodes represent firmware entities rather than 19 + hardware and in many cases they provide auxiliary information on devices 20 + enumerated independently (like PCI devices or CPUs). It is therefore generally 21 + questionable to assign resources to them because the entities represented by 22 + them do not decode addresses in the memory or I/O address spaces and do not 23 + generate interrupts or similar (all of that is done by hardware). 24 + 25 + Second, as a general rule, a struct acpi_device can only be a parent of another 26 + struct acpi_device. If that is not the case, the location of the child device 27 + in the device hierarchy is at least confusing and it may not be straightforward 28 + to identify the piece of hardware providing functionality represented by it. 29 + However, binding a driver directly to an ACPI device node may cause that to 30 + happen if the given driver registers input devices or wakeup sources under it, 31 + for example. 32 + 33 + Next, using system suspend and resume callbacks directly on ACPI device nodes 34 + is also questionable because it may cause ordering problems to appear. Namely, 35 + ACPI device nodes are registered before enumerating hardware corresponding to 36 + them and they land on the PM list in front of the majority of other device 37 + objects. Consequently, the execution ordering of their PM callbacks may be 38 + different from what is generally expected. Also, in general, dependencies 39 + returned by _DEP objects do not affect ACPI device nodes themselves, but the 40 + "physical" devices associated with them, which potentially is one more source 41 + of inconsistency related to treating ACPI device nodes as "real" device 42 + representation. 43 + 44 + All of the above means that binding drivers to ACPI device nodes should 45 + generally be avoided and so struct acpi_driver objects should not be used. 46 + 47 + Moreover, a device ID is necessary to bind a driver directly to an ACPI device 48 + node, but device IDs are not generally associated with all of them. Some of 49 + them contain alternative information allowing the corresponding pieces of 50 + hardware to be identified, for example represeted by an _ADR object return 51 + value, and device IDs are not used in those cases. In consequence, confusingly 52 + enough, binding an ACPI driver to an ACPI device node may even be impossible. 53 + 54 + When that happens, the piece of hardware corresponding to the given ACPI device 55 + node is represented by another device object, like a struct pci_dev, and the 56 + ACPI device node is the "ACPI companion" of that device, accessible through its 57 + fwnode pointer used by the ACPI_COMPANION() macro. The ACPI companion holds 58 + additional information on the device configuration and possibly some "recipes" 59 + on device manipulation in the form of AML (ACPI Machine Language) bytecode 60 + provided by the platform firmware. Thus the role of the ACPI device node is 61 + similar to the role of a struct device_node on a system where Device Tree is 62 + used for platform description. 63 + 64 + For consistency, this approach has been extended to the cases in which ACPI 65 + device IDs are used. Namely, in those cases, an additional device object is 66 + created to represent the piece of hardware corresponding to a given ACPI device 67 + node. By default, it is a platform device, but it may also be a PNP device, a 68 + CPU device, or another type of device, depending on what the given piece of 69 + hardware actually is. There are even cases in which multiple devices are 70 + "backed" or "accompanied" by one ACPI device node (e.g. ACPI device nodes 71 + corresponding to GPUs that may provide firmware interfaces for backlight 72 + brightness control in addition to GPU configuration information). 73 + 74 + This means that it really should never be necessary to bind a driver directly to 75 + an ACPI device node because there is a "proper" device object representing the 76 + corresponding piece of hardware that can be bound to by a "proper" driver using 77 + the given ACPI device node as the device's ACPI companion. Thus, in principle, 78 + there is no reason to use ACPI drivers and if they all were replaced with other 79 + driver types (for example, platform drivers), some code could be dropped and 80 + some complexity would go away.

Documentation/driver-api/acpi/index.rst

··· 7 7 8 8 linuxized-acpica 9 9 scan_handlers 10 + acpi-drivers

Configure Feed

Configure Feed