Re: [PATCH v1 2/9] docs: firmware-guide: ACPI: Clarify ACPI bus concepts
On 10/6/2023 5:36 PM, Rafael J. Wysocki wrote: > On Thu, Oct 5, 2023 at 10:39 PM Wilczynski, Michal > wrote: >> >> >> On 10/5/2023 8:28 PM, Wilczynski, Michal wrote: >>> 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 > Signed-off-by: Michal Wilczynski > --- > 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 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 Co-developed-by: Michal Wilczynski Signed-off-by: Michal Wilczynski Signed-off-by: Rafael J. Wysocki --- 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
Re: [PATCH v1 2/9] docs: firmware-guide: ACPI: Clarify ACPI bus concepts
On Thu, Oct 5, 2023 at 10:39 PM Wilczynski, Michal wrote: > > > > On 10/5/2023 8:28 PM, Wilczynski, Michal wrote: > > > > 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 > >>> Signed-off-by: Michal Wilczynski > >>> --- > >>> 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 > >> 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 > >> Co-developed-by: Michal Wilczynski > >> Signed-off-by: Michal Wilczynski > >> Signed-off-by: Rafael J. Wysocki > >> --- > >> 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
Re: [PATCH v1 2/9] docs: firmware-guide: ACPI: Clarify ACPI bus concepts
On 10/5/2023 8:28 PM, Wilczynski, Michal wrote: > > 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 >>> Signed-off-by: Michal Wilczynski >>> --- >>> 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 >> 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 >> Co-developed-by: Michal Wilczynski >> Signed-off-by: Michal Wilczynski >> Signed-off-by: Rafael J. Wysocki >> --- >> 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
Re: [PATCH v1 2/9] docs: firmware-guide: ACPI: Clarify ACPI bus concepts
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 >> Signed-off-by: Michal Wilczynski >> --- >> 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 > 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 > Co-developed-by: Michal Wilczynski > Signed-off-by: Michal Wilczynski > Signed-off-by: Rafael J. Wysocki > --- > 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
Re: [PATCH v1 2/9] docs: firmware-guide: ACPI: Clarify ACPI bus concepts
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 > Signed-off-by: Michal Wilczynski > --- > 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 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 Co-developed-by: Michal Wilczynski Signed-off-by: Michal Wilczynski Signed-off-by: Rafael J. Wysocki --- 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
[PATCH v1 2/9] docs: firmware-guide: ACPI: Clarify ACPI bus concepts
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 Signed-off-by: Michal Wilczynski --- 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 === -- 2.41.0
