Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Flavio Suligoi <f.suligoi@asem.it>
To:     "Rafael J . Wysocki" <rjw@rjwysocki.net>,
        Len Brown <lenb@kernel.org>,
        Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
        Mika Westerberg <mika.westerberg@linux.intel.com>
CC:     <linux-acpi@vger.kernel.org>, <linux-gpio@vger.kernel.org>,
        <linux-kernel@vger.kernel.org>, Flavio Suligoi <f.suligoi@asem.it>
Subject: [PATCH v1] docs: ACPI: enumeration: add PCI hierarchy representation
Date:   Thu, 19 Nov 2020 11:12:33 +0100
Message-ID: <20201119101233.701918-1-f.suligoi@asem.it>
MIME-Version: 1.0
Content-Transfer-Encoding: 7BIT
Content-Type:   text/plain; charset=US-ASCII
Precedence: bulk

For "fixed" PCI devices, such as chips directly soldered
on the main board (ethernet, wi-fi, serial ports, etc.),
it is possible to find an ACPI enumeration.

This allows to add useful properties to these devices.
Just for an example: the property "gpio-line-names" can be
added to the pins of a GPIO expander on the PCI bus.

In order to find the ACPI name of a PCI device , it's necessary
to disassemble the BIOS ACPI tables (in particular the DSDT)
and also to analyze the PCI bus topology of the board.

This patch, with a practical example, show how to do this.

Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
---
 .../firmware-guide/acpi/enumeration.rst       | 180 ++++++++++++++++++
 1 file changed, 180 insertions(+)

diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
index c13fee8b02ba..b08431a93cf5 100644
--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -461,3 +461,183 @@ Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
 property returned by it is meaningless.
 
 Refer to :doc:`DSD-properties-rules` for more information.
+
+PCI hierarchy representation
+============================
+
+Sometimes could be useful to enumerate a PCI device, knowing its position on the
+PCI bus.
+
+For example, some systems use PCI devices soldered directly on the mother board,
+in a fixed position (ethernet, wi-fi, serial ports, etc.). In this conditions it
+is possible to refer to these PCI devices knowing their position on the PCI bus
+topology.
+
+To identify a PCI device, a complete hierarchical description is required, from
+the chipset root port to the final device, through all the intermediate
+bridges/switches of the board.
+
+For example, let us assume to have a system with a PCIe serial port, an
+Exar XR17V3521, soldered on the main board. This UART chip also includes
+16 GPIOs and we want to add the property ``gpio-line-names`` [1] to these pins.
+In this case, the ``lspci`` output for this component is::
+
+	07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03)
+
+The complete ``lspci`` output (manually reduced in length) is::
+
+	root@debian:~# lspci
+	00:00.0 Host bridge: Intel Corp... Host Bridge (rev 0d)
+	00:02.0 VGA compatible controller: Intel Corporation Device 5a85 (rev 0d)
+	00:0e.0 Audio device: Intel Corp... Audio Cluster (rev 0d)
+	00:0f.0 Communication controller: Intel Corp... Trusted Execution Engine (rev 0d)
+	00:12.0 SATA controller: Intel Corp... SATA AHCI Controller (rev 0d)
+	00:13.0 PCI bridge: Intel Corp... PCI Express Port A #1 (rev fd)
+	00:13.1 PCI bridge: Intel Corp... PCI Express Port A #2 (rev fd)
+	00:13.2 PCI bridge: Intel Corp... PCI Express Port A #3 (rev fd)
+	00:14.0 PCI bridge: Intel Corp... PCI Express Port B #1 (rev fd)
+	00:14.1 PCI bridge: Intel Corp... PCI Express Port B #2 (rev fd)
+	00:15.0 USB controller: Intel Corp... USB xHCI (rev 0d)
+	00:16.0 Signal processing controller: Intel Corp... I2C Controller #1 (rev 0d)
+	00:16.1 Signal processing controller: Intel Corp... I2C Controller #2 (rev 0d)
+	00:19.0 Signal processing controller: Intel Corp... SPI Controller #1 (rev 0d)
+	00:19.1 Signal processing controller: Intel Corp... SPI Controller #2 (rev 0d)
+	00:19.2 Signal processing controller: Intel Corp... SPI Controller #3 (rev 0d)
+	00:1f.0 ISA bridge: Intel Corp... Low Pin Count Interface (rev 0d)
+	00:1f.1 SMBus: Intel Corp... SMBus Controller (rev 0d)
+	01:00.0 Ethernet controller: Intel Corp... I210 Gigabit Network Connection (rev 03)
+	02:00.0 Ethernet controller: Intel Corp... I210 Gigabit Network Connection (rev 03)
+	04:00.0 Ethernet controller: Intel Corp... I210 Gigabit Network Connection (rev 03)
+	05:00.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
+	06:01.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
+	06:02.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
+	06:03.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
+	07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03) <-- Exar
+	08:00.0 Ethernet controller: Intel Corp... I210 Gigabit Network Connection (rev 03)
+	root@debian:~#
+
+The bus topology is::
+
+	root@debian:~# lspci -t
+	-[0000:00]-+-00.0
+	           +-02.0
+	           +-0e.0
+	           +-0f.0
+	           +-12.0
+	           +-13.0-[01]----00.0
+	           +-13.1-[02]----00.0
+	           +-13.2-[03]--
+	           +-14.0-[04]----00.0
+	           +-14.1-[05-09]----00.0-[06-09]--+-01.0-[07]----00.0 <-- Exar
+	           |                               +-02.0-[08]----00.0
+	           |                               \-03.0-[09]--
+	           +-15.0
+	           +-16.0
+	           +-16.1
+	           +-19.0
+	           +-19.1
+	           +-19.2
+	           +-1f.0
+	           \-1f.1
+	root@debian:~#
+
+To describe this Exar device on the PCI bus, we must start from the ACPI name
+of the chipset bridge (also called "root port") with address::
+
+	Bus: 0 - Device: 14 - Function: 1
+
+To find this information is necessary disassemble the BIOS ACPI tables, in
+particular the DSDT (see also [2])::
+
+	cd /sys/firmware/acpi
+	cp -a tables/ ~
+	cd ~/tables/
+	find . -type f -exec mv {} {}.aml \;
+	iasl -e SSDT?.* -d DSDT.aml
+
+Now, in the DSDT.dsl, we have to search the device whose address is related to
+0x14 (device) and 0x01 (function). In this case we can find the following
+device::
+
+	Scope (_SB.PCI0)
+	{
+	... other definitions follow ...
+		Device (RP02)
+		{
+			Method (_ADR, 0, NotSerialized)  // _ADR: Address
+			{
+				If ((RPA2 != Zero))
+				{
+					Return (RPA2) /* \RPA2 */
+				}
+				Else
+				{
+					Return (0x00140001)
+				}
+			}
+	... other definitions follow ...
+
+and the _ADR method [3] returns exactly the device/function couple that
+we are looking for. With this information and analyzing the above ``lspci``
+output (both the devices list and the devices tree), we can write the following
+ACPI description for the Exar PCIe UART, also adding the list of its GPIO line
+names::
+
+	Scope (_SB.PCI0.RP02)
+	{
+		Device (BRG1) //Bridge
+		{
+			Name (_ADR, 0x0000)
+
+			Device (BRG2) //Bridge
+			{
+				Name (_ADR, 0x00010000)
+
+				Device (EXAR)
+				{
+					Name (_ADR, 0x0000)
+
+					Name (_DSD, Package ()
+					{
+						ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+						Package ()
+						{
+							Package ()
+							{
+								"gpio-line-names",
+								Package ()
+								{
+									"mode_232",
+									"mode_422",
+									"mode_485",
+									"misc_1",
+									"misc_2",
+									"misc_3",
+									"",
+									"",
+									"aux_1",
+									"aux_2",
+									"aux_3",
+								}
+							}
+						}
+					})
+				}
+			}
+		}
+	}
+
+The location "_SB.PCI0.RP02" is obtained by the above investigation in the
+DSDT.dsl table, whereas the device names "BRG1", "BRG2" and "EXAR" are
+created analyzing the position of the Exar UART in the PCI bus topology.
+
+References
+==========
+
+[1] Documentation/firmware-guide/acpi/gpio-properties.rst
+
+[2] Documentation/firmware-guide/acpi/method-customizing.rst
+
+[3] ACPI Specifications, Version 6.3 - Paragraph 6.1.1 _ADR Address)
+    https://uefi.org/sites/default/files/resources/ACPI_6_3_May16.pdf,
+    referenced 2020-11-18
-- 
2.25.1