Debian Codegraph @

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

raw
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 <[email protected]>
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.