PCI: Establish document for PCI host bridge sysfs attributes

In preparation for adding more host bridge sysfs attributes, document the
existing naming format and 'firmware_node' attribute.

Reviewed-by: Jonathan Cameron <jonathan.cameron@huawei.com>
Link: https://patch.msgid.link/20251031212902.2256310-7-dan.j.williams@intel.com
Signed-off-by: Dan Williams <dan.j.williams@intel.com>

diff --git a/Documentation/ABI/testing/sysfs-devices-pci-host-bridge b/Documentation/ABI/testing/sysfs-devices-pci-host-bridge
new file mode 100644 (file)
index 0000000..8c3a652
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-pci-host-bridge
@@ -0,0 +1,19 @@
+What:          /sys/devices/pciDDDD:BB
+               /sys/devices/.../pciDDDD:BB
+Contact:       linux-pci@vger.kernel.org
+Description:
+               A PCI host bridge device parents a PCI bus device topology. PCI
+               controllers may also parent host bridges. The DDDD:BB format
+               conveys the PCI domain (ACPI segment) number and root bus number
+               (in hexadecimal) of the host bridge. Note that the domain number
+               may be larger than the 16-bits that the "DDDD" format implies
+               for emulated host-bridges.
+
+What:          pciDDDD:BB/firmware_node
+Contact:       linux-pci@vger.kernel.org
+Description:
+               (RO) Symlink to the platform firmware device object "companion"
+               of the host bridge. For example, an ACPI device with an _HID of
+               PNP0A08 (/sys/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0A08:00). See
+               /sys/devices/pciDDDD:BB entry for details about the DDDD:BB
+               format.

diff --git a/MAINTAINERS b/MAINTAINERS
index f1c8793bf03ec0983c319c62725c0a0d449797f3..3555bf83c9164612eacdd10b065e7ede5bed5505 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -19910,6 +19910,7 @@ Q:      https://patchwork.kernel.org/project/linux-pci/list/
 B:     https://bugzilla.kernel.org
 C:     irc://irc.oftc.net/linux-pci
 T:     git git://git.kernel.org/pub/scm/linux/kernel/git/pci/pci.git
+F:     Documentation/ABI/testing/sysfs-devices-pci-host-bridge
 F:     Documentation/PCI/
 F:     Documentation/devicetree/bindings/pci/
 F:     arch/x86/kernel/early-quirks.c