tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
ACPI: docs: enumeration: Clarify ACPI bus concepts
In some cases, ACPI drivers are implemented as a way to manage devices
enumerated with the help of the platform firmware through ACPI.
This might be confusing, since the preferred way to implement a driver
for a device that cannot be enumerated natively, is a platform
driver, as stated in the documentation.
Clarify relationships between ACPI device objects, platform devices and
ACPI Namespace entries.
Suggested-by: Elena Reshetova <elena.reshetova@intel.com>
Co-developed-by: Michal Wilczynski <michal.wilczynski@intel.com>
Signed-off-by: Michal Wilczynski <michal.wilczynski@intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+43
+43
Documentation/firmware-guide/acpi/enumeration.rst
+43
Documentation/firmware-guide/acpi/enumeration.rst
···
64
64
configuring GPIOs it can get its ACPI handle and extract this information
65
65
from ACPI tables.
66
66
67
+
ACPI device objects
68
+
===================
69
+
70
+
Generally speaking, there are two categories of devices in a system in which
71
+
ACPI is used as an interface between the platform firmware and the OS: Devices
72
+
that can be discovered and enumerated natively, through a protocol defined for
73
+
the specific bus that they are on (for example, configuration space in PCI),
74
+
without the platform firmware assistance, and devices that need to be described
75
+
by the platform firmware so that they can be discovered. Still, for any device
76
+
known to the platform firmware, regardless of which category it falls into,
77
+
there can be a corresponding ACPI device object in the ACPI Namespace in which
78
+
case the Linux kernel will create a struct acpi_device object based on it for
79
+
that device.
80
+
81
+
Those struct acpi_device objects are never used for binding drivers to natively
82
+
discoverable devices, because they are represented by other types of device
83
+
objects (for example, struct pci_dev for PCI devices) that are bound to by
84
+
device drivers (the corresponding struct acpi_device object is then used as
85
+
an additional source of information on the configuration of the given device).
86
+
Moreover, the core ACPI device enumeration code creates struct platform_device
87
+
objects for the majority of devices that are discovered and enumerated with the
88
+
help of the platform firmware and those platform device objects can be bound to
89
+
by platform drivers in direct analogy with the natively enumerable devices
90
+
case. Therefore it is logically inconsistent and so generally invalid to bind
91
+
drivers to struct acpi_device objects, including drivers for devices that are
92
+
discovered with the help of the platform firmware.
93
+
94
+
Historically, ACPI drivers that bound directly to struct acpi_device objects
95
+
were implemented for some devices enumerated with the help of the platform
96
+
firmware, but this is not recommended for any new drivers. As explained above,
97
+
platform device objects are created for those devices as a rule (with a few
98
+
exceptions that are not relevant here) and so platform drivers should be used
99
+
for handling them, even though the corresponding ACPI device objects are the
100
+
only source of device configuration information in that case.
101
+
102
+
For every device having a corresponding struct acpi_device object, the pointer
103
+
to it is returned by the ACPI_COMPANION() macro, so it is always possible to
104
+
get to the device configuration information stored in the ACPI device object
105
+
this way. Accordingly, struct acpi_device can be regarded as a part of the
106
+
interface between the kernel and the ACPI Namespace, whereas device objects of
107
+
other types (for example, struct pci_dev or struct platform_device) are used
108
+
for interacting with the rest of the system.
109
+
67
110
DMA support
68
111
===========
69
112