On 10/5/2023 7:57 PM, Rafael J. Wysocki wrote: > On Monday, September 25, 2023 4:48:35 PM CEST Michal Wilczynski wrote: >> Some devices implement ACPI driver as a way to manage devices >> enumerated by the ACPI. This might be confusing as a preferred way to >> implement a driver for devices not connected to any bus is a platform >> driver, as stated in the documentation. Clarify relationships between >> ACPI device, platform device and ACPI entries. >> >> Suggested-by: Elena Reshetova <elena.reshetova@xxxxxxxxx> >> Signed-off-by: Michal Wilczynski <michal.wilczynski@xxxxxxxxx> >> --- >> Documentation/firmware-guide/acpi/enumeration.rst | 13 +++++++++++++ >> 1 file changed, 13 insertions(+) >> >> diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst >> index 56d9913a3370..f56cc79a9e83 100644 >> --- a/Documentation/firmware-guide/acpi/enumeration.rst >> +++ b/Documentation/firmware-guide/acpi/enumeration.rst >> @@ -64,6 +64,19 @@ 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 bus >> +==================== >> + >> +Historically some devices not connected to any bus were represented as ACPI >> +devices, and had to implement ACPI driver. This is not a preferred way for new >> +drivers. As explained above devices not connected to any bus should implement >> +platform driver. ACPI device would be created during enumeration nonetheless, >> +and would be accessible through ACPI_COMPANION() macro, and the ACPI handle would >> +be accessible through ACPI_HANDLE() macro. ACPI device is meant to describe >> +information related to ACPI entry e.g. handle of the ACPI entry. Think - >> +ACPI device interfaces with the FW, and the platform device with the rest of >> +the system. >> + >> DMA support >> =========== > I rewrote the above entirely, so here's a new patch to replace this one: > > --- > From: Rafael J. Wysocki <rafael.j.wysocki@xxxxxxxxx> > Subject: [PATCH v2 2/9] 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@xxxxxxxxx> > Co-developed-by: Michal Wilczynski <michal.wilczynski@xxxxxxxxx> > Signed-off-by: Michal Wilczynski <michal.wilczynski@xxxxxxxxx> > Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@xxxxxxxxx> > --- > Documentation/firmware-guide/acpi/enumeration.rst | 43 ++++++++++++++++++++++ > 1 file changed, 43 insertions(+) > > Index: linux-pm/Documentation/firmware-guide/acpi/enumeration.rst > =================================================================== > --- linux-pm.orig/Documentation/firmware-guide/acpi/enumeration.rst > +++ linux-pm/Documentation/firmware-guide/acpi/enumeration.rst > @@ -64,6 +64,49 @@ If the driver needs to perform more comp > 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 > =========== Thanks a lot ! Looks very good, will include this in next revision. Michał > > > >
