mirrors
/
linux-stable
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
1
0
Fork 0
Code Issues Releases Wiki Activity

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>
This commit is contained in:
Rafael J. Wysocki 2023-10-06 17:29:53 +02:00
parent 8a749fd1a8
commit 5f3c10ac34
1 changed files with 43 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
Documentation/firmware-guide/acpi/enumeration.rst
View File

@ -64,6 +64,49 @@ If the driver needs to perform more complex initialization like getting and
configuring GPIOs it can get its ACPI handle and extract this information
from ACPI tables.
ACPI device objects
===================
Generally speaking, there are two categories of devices in a system in which
ACPI is used as an interface between the platform firmware and the OS: Devices
that can be discovered and enumerated natively, through a protocol defined for
the specific bus that they are on (for example, configuration space in PCI),
without the platform firmware assistance, and devices that need to be described
by the platform firmware so that they can be discovered. Still, for any device
known to the platform firmware, regardless of which category it falls into,
there can be a corresponding ACPI device object in the ACPI Namespace in which
case the Linux kernel will create a struct acpi_device object based on it for
that device.
Those struct acpi_device objects are never used for binding drivers to natively
discoverable devices, because they are represented by other types of device
objects (for example, struct pci_dev for PCI devices) that are bound to by
device drivers (the corresponding struct acpi_device object is then used as
an additional source of information on the configuration of the given device).
Moreover, the core ACPI device enumeration code creates struct platform_device
objects for the majority of devices that are discovered and enumerated with the
help of the platform firmware and those platform device objects can be bound to
by platform drivers in direct analogy with the natively enumerable devices
case. Therefore it is logically inconsistent and so generally invalid to bind
drivers to struct acpi_device objects, including drivers for devices that are
discovered with the help of the platform firmware.
Historically, ACPI drivers that bound directly to struct acpi_device objects
were implemented for some devices enumerated with the help of the platform
firmware, but this is not recommended for any new drivers. As explained above,
platform device objects are created for those devices as a rule (with a few
exceptions that are not relevant here) and so platform drivers should be used
for handling them, even though the corresponding ACPI device objects are the
only source of device configuration information in that case.
For every device having a corresponding struct acpi_device object, the pointer
to it is returned by the ACPI_COMPANION() macro, so it is always possible to
get to the device configuration information stored in the ACPI device object
this way. Accordingly, struct acpi_device can be regarded as a part of the
interface between the kernel and the ACPI Namespace, whereas device objects of
other types (for example, struct pci_dev or struct platform_device) are used
for interacting with the rest of the system.
DMA support
===========