| Message ID | 20201119101233.701918-1-f.suligoi@asem.it |
|---|---|
| State | New |
| Headers | show |
| Series | [v1] docs: ACPI: enumeration: add PCI hierarchy representation | expand |
On Thu, Nov 19, 2020 at 11:12:33AM +0100, Flavio Suligoi wrote: Thank you very much for nice piece of documentation! My comments below. > For "fixed" PCI devices, such as chips directly soldered > on the main board (ethernet, wi-fi, serial ports, etc.), Wi-Fi > 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 No space before comma. > 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 Wi-Fi > +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:~# At least here, I would rather drop unrelated lines (except bridges, serial controller). Like: 00:00.0 Host bridge: Intel Corp... Host Bridge (rev 0d) ... 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) ... 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 ... > +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 And possible here cut unneeded branches. > + root@debian:~# This is not needed. > +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/ acpidump followed by acpixtract from ACPI tools is better to advertise. > + find . -type f -exec mv {} {}.aml \; Unnecessary step. But I think you wanted to have it to distinguish sources and binaries in the text below. > + 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
Hi Andy! > On Thu, Nov 19, 2020 at 11:12:33AM +0100, Flavio Suligoi wrote: > > Thank you very much for nice piece of documentation! > My comments below. Thanks for your suggestions! I'll use them in the next version of the patch! > > +particular the DSDT (see also [2]):: > > > + cd /sys/firmware/acpi > > + cp -a tables/ ~ > > + cd ~/tables/ > > acpidump followed by acpixtract from ACPI tools is better to advertise. Ok, I'll use acpixtract > > > + find . -type f -exec mv {} {}.aml \; > > Unnecessary step. But I think you wanted to have it to distinguish sources > and > binaries in the text below. Right, I think that is important include the SSDT tables for external symbol resolution. For this reason I renamed the binary tables, to use the following command: > > + iasl -e SSDT?.* -d DSDT.aml > -- > With Best Regards, > Andy Shevchenko > Best regards, Flavio
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
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(+)