[PATCH] dt-bindings: PCI: Remove obsolete .txt docs

[PATCH] dt-bindings: PCI: Remove obsolete .txt docs

[Rob Herring (Arm)]

The content in these files has been moved to the schemas in dtschema.
pci.txt is covered by pci-bus-common.yaml and pci-host-bridge.yaml.
pci-iommu.txt is covered by pci-iommu.yaml. pci-msi.txt is covered in
msi-map property in pci-host-bridge.yaml.

Cc: Frank Li <Frank.li@nxp.com>
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
---
 .../bindings/pci/nvidia,tegra194-pcie-ep.yaml |   2 +-
 .../devicetree/bindings/pci/pci-iommu.txt     | 171 --------------
 .../devicetree/bindings/pci/pci-msi.txt       | 220 ------------------
 Documentation/devicetree/bindings/pci/pci.txt |  84 -------
 4 files changed, 1 insertion(+), 476 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/pci/pci-iommu.txt
 delete mode 100644 Documentation/devicetree/bindings/pci/pci-msi.txt
 delete mode 100644 Documentation/devicetree/bindings/pci/pci.txt

diff --git a/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie-ep.yaml
index a24fb8307d29..6d6052a2748f 100644
--- a/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie-ep.yaml
+++ b/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie-ep.yaml
@@ -74,7 +74,7 @@ properties:
 
   reset-gpios:
     description: Must contain a phandle to a GPIO controller followed by GPIO
-      that is being used as PERST input signal. Please refer to pci.txt.
+      that is being used as PERST input signal.
 
   phys:
     minItems: 1
diff --git a/Documentation/devicetree/bindings/pci/pci-iommu.txt b/Documentation/devicetree/bindings/pci/pci-iommu.txt
deleted file mode 100644
index 0def586fdcdf..000000000000
--- a/Documentation/devicetree/bindings/pci/pci-iommu.txt
+++ /dev/null
@@ -1,171 +0,0 @@
-This document describes the generic device tree binding for describing the
-relationship between PCI(e) devices and IOMMU(s).
-
-Each PCI(e) device under a root complex is uniquely identified by its Requester
-ID (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
-Function number.
-
-For the purpose of this document, when treated as a numeric value, a RID is
-formatted such that:
-
-* Bits [15:8] are the Bus number.
-* Bits [7:3] are the Device number.
-* Bits [2:0] are the Function number.
-* Any other bits required for padding must be zero.
-
-IOMMUs may distinguish PCI devices through sideband data derived from the
-Requester ID. While a given PCI device can only master through one IOMMU, a
-root complex may split masters across a set of IOMMUs (e.g. with one IOMMU per
-bus).
-
-The generic 'iommus' property is insufficient to describe this relationship,
-and a mechanism is required to map from a PCI device to its IOMMU and sideband
-data.
-
-For generic IOMMU bindings, see
-Documentation/devicetree/bindings/iommu/iommu.txt.
-
-
-PCI root complex
-================
-
-Optional properties
--------------------
-
-- iommu-map: Maps a Requester ID to an IOMMU and associated IOMMU specifier
-  data.
-
-  The property is an arbitrary number of tuples of
-  (rid-base,iommu,iommu-base,length).
-
-  Any RID r in the interval [rid-base, rid-base + length) is associated with
-  the listed IOMMU, with the IOMMU specifier (r - rid-base + iommu-base).
-
-- iommu-map-mask: A mask to be applied to each Requester ID prior to being
-  mapped to an IOMMU specifier per the iommu-map property.
-
-
-Example (1)
-===========
-
-/ {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	iommu: iommu@a {
-		reg = <0xa 0x1>;
-		compatible = "vendor,some-iommu";
-		#iommu-cells = <1>;
-	};
-
-	pci: pci@f {
-		reg = <0xf 0x1>;
-		compatible = "vendor,pcie-root-complex";
-		device_type = "pci";
-
-		/*
-		 * The sideband data provided to the IOMMU is the RID,
-		 * identity-mapped.
-		 */
-		iommu-map = <0x0 &iommu 0x0 0x10000>;
-	};
-};
-
-
-Example (2)
-===========
-
-/ {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	iommu: iommu@a {
-		reg = <0xa 0x1>;
-		compatible = "vendor,some-iommu";
-		#iommu-cells = <1>;
-	};
-
-	pci: pci@f {
-		reg = <0xf 0x1>;
-		compatible = "vendor,pcie-root-complex";
-		device_type = "pci";
-
-		/*
-		 * The sideband data provided to the IOMMU is the RID with the
-		 * function bits masked out.
-		 */
-		iommu-map = <0x0 &iommu 0x0 0x10000>;
-		iommu-map-mask = <0xfff8>;
-	};
-};
-
-
-Example (3)
-===========
-
-/ {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	iommu: iommu@a {
-		reg = <0xa 0x1>;
-		compatible = "vendor,some-iommu";
-		#iommu-cells = <1>;
-	};
-
-	pci: pci@f {
-		reg = <0xf 0x1>;
-		compatible = "vendor,pcie-root-complex";
-		device_type = "pci";
-
-		/*
-		 * The sideband data provided to the IOMMU is the RID,
-		 * but the high bits of the bus number are flipped.
-		 */
-		iommu-map = <0x0000 &iommu 0x8000 0x8000>,
-			    <0x8000 &iommu 0x0000 0x8000>;
-	};
-};
-
-
-Example (4)
-===========
-
-/ {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	iommu_a: iommu@a {
-		reg = <0xa 0x1>;
-		compatible = "vendor,some-iommu";
-		#iommu-cells = <1>;
-	};
-
-	iommu_b: iommu@b {
-		reg = <0xb 0x1>;
-		compatible = "vendor,some-iommu";
-		#iommu-cells = <1>;
-	};
-
-	iommu_c: iommu@c {
-		reg = <0xc 0x1>;
-		compatible = "vendor,some-iommu";
-		#iommu-cells = <1>;
-	};
-
-	pci: pci@f {
-		reg = <0xf 0x1>;
-		compatible = "vendor,pcie-root-complex";
-		device_type = "pci";
-
-		/*
-		 * Devices with bus number 0-127 are mastered via IOMMU
-		 * a, with sideband data being RID[14:0].
-		 * Devices with bus number 128-255 are mastered via
-		 * IOMMU b, with sideband data being RID[14:0].
-		 * No devices master via IOMMU c.
-		 */
-		iommu-map = <0x0000 &iommu_a 0x0000 0x8000>,
-			    <0x8000 &iommu_b 0x0000 0x8000>;
-	};
-};
diff --git a/Documentation/devicetree/bindings/pci/pci-msi.txt b/Documentation/devicetree/bindings/pci/pci-msi.txt
deleted file mode 100644
index b73d839657b6..000000000000
--- a/Documentation/devicetree/bindings/pci/pci-msi.txt
+++ /dev/null
@@ -1,220 +0,0 @@
-This document describes the generic device tree binding for describing the
-relationship between PCI devices and MSI controllers.
-
-Each PCI device under a root complex is uniquely identified by its Requester ID
-(AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
-Function number.
-
-For the purpose of this document, when treated as a numeric value, a RID is
-formatted such that:
-
-* Bits [15:8] are the Bus number.
-* Bits [7:3] are the Device number.
-* Bits [2:0] are the Function number.
-* Any other bits required for padding must be zero.
-
-MSIs may be distinguished in part through the use of sideband data accompanying
-writes. In the case of PCI devices, this sideband data may be derived from the
-Requester ID. A mechanism is required to associate a device with both the MSI
-controllers it can address, and the sideband data that will be associated with
-its writes to those controllers.
-
-For generic MSI bindings, see
-Documentation/devicetree/bindings/interrupt-controller/msi.txt.
-
-
-PCI root complex
-================
-
-Optional properties
--------------------
-
-- msi-map: Maps a Requester ID to an MSI controller and associated
-  msi-specifier data. The property is an arbitrary number of tuples of
-  (rid-base,msi-controller,msi-base,length), where:
-
-  * rid-base is a single cell describing the first RID matched by the entry.
-
-  * msi-controller is a single phandle to an MSI controller
-
-  * msi-base is an msi-specifier describing the msi-specifier produced for the
-    first RID matched by the entry.
-
-  * length is a single cell describing how many consecutive RIDs are matched
-    following the rid-base.
-
-  Any RID r in the interval [rid-base, rid-base + length) is associated with
-  the listed msi-controller, with the msi-specifier (r - rid-base + msi-base).
-
-- msi-map-mask: A mask to be applied to each Requester ID prior to being mapped
-  to an msi-specifier per the msi-map property.
-
-- msi-parent: Describes the MSI parent of the root complex itself. Where
-  the root complex and MSI controller do not pass sideband data with MSI
-  writes, this property may be used to describe the MSI controller(s)
-  used by PCI devices under the root complex, if defined as such in the
-  binding for the root complex.
-
-
-Example (1)
-===========
-
-/ {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	msi: msi-controller@a {
-		reg = <0xa 0x1>;
-		compatible = "vendor,some-controller";
-		msi-controller;
-		#msi-cells = <1>;
-	};
-
-	pci: pci@f {
-		reg = <0xf 0x1>;
-		compatible = "vendor,pcie-root-complex";
-		device_type = "pci";
-
-		/*
-		 * The sideband data provided to the MSI controller is
-		 * the RID, identity-mapped.
-		 */
-		msi-map = <0x0 &msi_a 0x0 0x10000>,
-	};
-};
-
-
-Example (2)
-===========
-
-/ {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	msi: msi-controller@a {
-		reg = <0xa 0x1>;
-		compatible = "vendor,some-controller";
-		msi-controller;
-		#msi-cells = <1>;
-	};
-
-	pci: pci@f {
-		reg = <0xf 0x1>;
-		compatible = "vendor,pcie-root-complex";
-		device_type = "pci";
-
-		/*
-		 * The sideband data provided to the MSI controller is
-		 * the RID, masked to only the device and function bits.
-		 */
-		msi-map = <0x0 &msi_a 0x0 0x100>,
-		msi-map-mask = <0xff>
-	};
-};
-
-
-Example (3)
-===========
-
-/ {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	msi: msi-controller@a {
-		reg = <0xa 0x1>;
-		compatible = "vendor,some-controller";
-		msi-controller;
-		#msi-cells = <1>;
-	};
-
-	pci: pci@f {
-		reg = <0xf 0x1>;
-		compatible = "vendor,pcie-root-complex";
-		device_type = "pci";
-
-		/*
-		 * The sideband data provided to the MSI controller is
-		 * the RID, but the high bit of the bus number is
-		 * ignored.
-		 */
-		msi-map = <0x0000 &msi 0x0000 0x8000>,
-			  <0x8000 &msi 0x0000 0x8000>;
-	};
-};
-
-
-Example (4)
-===========
-
-/ {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	msi: msi-controller@a {
-		reg = <0xa 0x1>;
-		compatible = "vendor,some-controller";
-		msi-controller;
-		#msi-cells = <1>;
-	};
-
-	pci: pci@f {
-		reg = <0xf 0x1>;
-		compatible = "vendor,pcie-root-complex";
-		device_type = "pci";
-
-		/*
-		 * The sideband data provided to the MSI controller is
-		 * the RID, but the high bit of the bus number is
-		 * negated.
-		 */
-		msi-map = <0x0000 &msi 0x8000 0x8000>,
-			  <0x8000 &msi 0x0000 0x8000>;
-	};
-};
-
-
-Example (5)
-===========
-
-/ {
-	#address-cells = <1>;
-	#size-cells = <1>;
-
-	msi_a: msi-controller@a {
-		reg = <0xa 0x1>;
-		compatible = "vendor,some-controller";
-		msi-controller;
-		#msi-cells = <1>;
-	};
-
-	msi_b: msi-controller@b {
-		reg = <0xb 0x1>;
-		compatible = "vendor,some-controller";
-		msi-controller;
-		#msi-cells = <1>;
-	};
-
-	msi_c: msi-controller@c {
-		reg = <0xc 0x1>;
-		compatible = "vendor,some-controller";
-		msi-controller;
-		#msi-cells = <1>;
-	};
-
-	pci: pci@f {
-		reg = <0xf 0x1>;
-		compatible = "vendor,pcie-root-complex";
-		device_type = "pci";
-
-		/*
-		 * The sideband data provided to MSI controller a is the
-		 * RID, but the high bit of the bus number is negated.
-		 * The sideband data provided to MSI controller b is the
-		 * RID, identity-mapped.
-		 * MSI controller c is not addressable.
-		 */
-		msi-map = <0x0000 &msi_a 0x8000 0x08000>,
-			  <0x8000 &msi_a 0x0000 0x08000>,
-			  <0x0000 &msi_b 0x0000 0x10000>;
-	};
-};
diff --git a/Documentation/devicetree/bindings/pci/pci.txt b/Documentation/devicetree/bindings/pci/pci.txt
deleted file mode 100644
index 6a8f2874a24d..000000000000
--- a/Documentation/devicetree/bindings/pci/pci.txt
+++ /dev/null
@@ -1,84 +0,0 @@
-PCI bus bridges have standardized Device Tree bindings:
-
-PCI Bus Binding to: IEEE Std 1275-1994
-https://www.devicetree.org/open-firmware/bindings/pci/pci2_1.pdf
-
-And for the interrupt mapping part:
-
-Open Firmware Recommended Practice: Interrupt Mapping
-https://www.devicetree.org/open-firmware/practice/imap/imap0_9d.pdf
-
-Additionally to the properties specified in the above standards a host bridge
-driver implementation may support the following properties:
-
-- linux,pci-domain:
-   If present this property assigns a fixed PCI domain number to a host bridge,
-   otherwise an unstable (across boots) unique number will be assigned.
-   It is required to either not set this property at all or set it for all
-   host bridges in the system, otherwise potentially conflicting domain numbers
-   may be assigned to root buses behind different host bridges.  The domain
-   number for each host bridge in the system must be unique.
-- max-link-speed:
-   If present this property specifies PCI gen for link capability.  Host
-   drivers could add this as a strategy to avoid unnecessary operation for
-   unsupported link speed, for instance, trying to do training for
-   unsupported link speed, etc.  Must be '4' for gen4, '3' for gen3, '2'
-   for gen2, and '1' for gen1. Any other values are invalid.
-- reset-gpios:
-   If present this property specifies PERST# GPIO. Host drivers can parse the
-   GPIO and apply fundamental reset to endpoints.
-- supports-clkreq:
-   If present this property specifies that CLKREQ signal routing exists from
-   root port to downstream device and host bridge drivers can do programming
-   which depends on CLKREQ signal existence. For example, programming root port
-   not to advertise ASPM L1 Sub-States support if there is no CLKREQ signal.
-
-PCI-PCI Bridge properties
--------------------------
-
-PCIe root ports and switch ports may be described explicitly in the device
-tree, as children of the host bridge node. Even though those devices are
-discoverable by probing, it might be necessary to describe properties that
-aren't provided by standard PCIe capabilities.
-
-Required properties:
-
-- reg:
-   Identifies the PCI-PCI bridge. As defined in the IEEE Std 1275-1994
-   document, it is a five-cell address encoded as (phys.hi phys.mid
-   phys.lo size.hi size.lo). phys.hi should contain the device's BDF as
-   0b00000000 bbbbbbbb dddddfff 00000000. The other cells should be zero.
-
-   The bus number is defined by firmware, through the standard bridge
-   configuration mechanism. If this port is a switch port, then firmware
-   allocates the bus number and writes it into the Secondary Bus Number
-   register of the bridge directly above this port. Otherwise, the bus
-   number of a root port is the first number in the bus-range property,
-   defaulting to zero.
-
-   If firmware leaves the ARI Forwarding Enable bit set in the bridge
-   above this port, then phys.hi contains the 8-bit function number as
-   0b00000000 bbbbbbbb ffffffff 00000000. Note that the PCIe specification
-   recommends that firmware only leaves ARI enabled when it knows that the
-   OS is ARI-aware.
-
-Optional properties:
-
-- external-facing:
-   When present, the port is external-facing. All bridges and endpoints
-   downstream of this port are external to the machine. The OS can, for
-   example, use this information to identify devices that cannot be
-   trusted with relaxed DMA protection, as users could easily attach
-   malicious devices to this port.
-
-Example:
-
-pcie@10000000 {
-	compatible = "pci-host-ecam-generic";
-	...
-	pcie@0008 {
-		/* Root port 00:01.0 is external-facing */
-		reg = <0x00000800 0 0 0 0>;
-		external-facing;
-	};
-};
-- 
2.47.2

Re: [PATCH] dt-bindings: PCI: Remove obsolete .txt docs

[Rob Herring (Arm)]

On Fri, 04 Apr 2025 17:15:57 -0500, Rob Herring (Arm) wrote:
> The content in these files has been moved to the schemas in dtschema.
> pci.txt is covered by pci-bus-common.yaml and pci-host-bridge.yaml.
> pci-iommu.txt is covered by pci-iommu.yaml. pci-msi.txt is covered in
> msi-map property in pci-host-bridge.yaml.
> 
> Cc: Frank Li <Frank.li@nxp.com>
> Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
> ---
>  .../bindings/pci/nvidia,tegra194-pcie-ep.yaml |   2 +-
>  .../devicetree/bindings/pci/pci-iommu.txt     | 171 --------------
>  .../devicetree/bindings/pci/pci-msi.txt       | 220 ------------------
>  Documentation/devicetree/bindings/pci/pci.txt |  84 -------
>  4 files changed, 1 insertion(+), 476 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/pci/pci-iommu.txt
>  delete mode 100644 Documentation/devicetree/bindings/pci/pci-msi.txt
>  delete mode 100644 Documentation/devicetree/bindings/pci/pci.txt
> 

My bot found errors running 'make dt_binding_check' on your patch:

yamllint warnings/errors:

dtschema/dtc warnings/errors:


doc reference errors (make refcheckdocs):
Warning: Documentation/devicetree/bindings/virtio/pci-iommu.yaml references a file that doesn't exist: Documentation/devicetree/bindings/pci/pci.txt
Documentation/devicetree/bindings/virtio/pci-iommu.yaml: Documentation/devicetree/bindings/pci/pci.txt

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20250404221559.552201-1-robh@kernel.org

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.

Re: [PATCH] dt-bindings: PCI: Remove obsolete .txt docs

[kernel test robot]

Hi Rob,

kernel test robot noticed the following build warnings:

[auto build test WARNING on pci/next]
[also build test WARNING on pci/for-linus linus/master v6.14 next-20250404]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Rob-Herring-Arm/dt-bindings-PCI-Remove-obsolete-txt-docs/20250405-061754
base:   https://git.kernel.org/pub/scm/linux/kernel/git/pci/pci.git next
patch link:    https://lore.kernel.org/r/20250404221559.552201-1-robh%40kernel.org
patch subject: [PATCH] dt-bindings: PCI: Remove obsolete .txt docs
reproduce: (https://download.01.org/0day-ci/archive/20250405/202504050824.95rb99r8-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202504050824.95rb99r8-lkp@intel.com/

All warnings (new ones prefixed by >>):

   Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`rt_link<../../networking/netlink_spec/rt_link>`
   Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../networking/netlink_spec/tc>`
   Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../networking/netlink_spec/tc>`
   Warning: Documentation/devicetree/bindings/regulator/siliconmitus,sm5703-regulator.yaml references a file that doesn't exist: Documentation/devicetree/bindings/mfd/siliconmitus,sm5703.yaml
>> Warning: Documentation/devicetree/bindings/virtio/pci-iommu.yaml references a file that doesn't exist: Documentation/devicetree/bindings/pci/pci.txt
   Warning: Documentation/hwmon/g762.rst references a file that doesn't exist: Documentation/devicetree/bindings/hwmon/g762.txt
   Warning: Documentation/translations/ja_JP/SubmittingPatches references a file that doesn't exist: linux-2.6.12-vanilla/Documentation/dontdiff
   Warning: Documentation/translations/ja_JP/process/submit-checklist.rst references a file that doesn't exist: Documentation/translations/ja_JP/SubmitChecklist
   Warning: Documentation/translations/zh_CN/admin-guide/README.rst references a file that doesn't exist: Documentation/dev-tools/kgdb.rst
   Warning: Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst references a file that doesn't exist: Documentation/dev-tools/gdb-kernel-debugging.rst

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

Re: [PATCH] dt-bindings: PCI: Remove obsolete .txt docs

[Frank Li]

On Fri, Apr 04, 2025 at 05:15:57PM -0500, Rob Herring (Arm) wrote:
> The content in these files has been moved to the schemas in dtschema.
> pci.txt is covered by pci-bus-common.yaml and pci-host-bridge.yaml.
> pci-iommu.txt is covered by pci-iommu.yaml. pci-msi.txt is covered in
> msi-map property in pci-host-bridge.yaml.
>
> Cc: Frank Li <Frank.li@nxp.com>
> Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
> ---

Reviewed-by: Frank Li <Frank.Li@nxp.com>

>  .../bindings/pci/nvidia,tegra194-pcie-ep.yaml |   2 +-
>  .../devicetree/bindings/pci/pci-iommu.txt     | 171 --------------
>  .../devicetree/bindings/pci/pci-msi.txt       | 220 ------------------
>  Documentation/devicetree/bindings/pci/pci.txt |  84 -------
>  4 files changed, 1 insertion(+), 476 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/pci/pci-iommu.txt
>  delete mode 100644 Documentation/devicetree/bindings/pci/pci-msi.txt
>  delete mode 100644 Documentation/devicetree/bindings/pci/pci.txt
>
> diff --git a/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie-ep.yaml
> index a24fb8307d29..6d6052a2748f 100644
> --- a/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie-ep.yaml
> +++ b/Documentation/devicetree/bindings/pci/nvidia,tegra194-pcie-ep.yaml
> @@ -74,7 +74,7 @@ properties:
>
>    reset-gpios:
>      description: Must contain a phandle to a GPIO controller followed by GPIO
> -      that is being used as PERST input signal. Please refer to pci.txt.
> +      that is being used as PERST input signal.
>
>    phys:
>      minItems: 1
> diff --git a/Documentation/devicetree/bindings/pci/pci-iommu.txt b/Documentation/devicetree/bindings/pci/pci-iommu.txt
> deleted file mode 100644
> index 0def586fdcdf..000000000000
> --- a/Documentation/devicetree/bindings/pci/pci-iommu.txt
> +++ /dev/null
> @@ -1,171 +0,0 @@
> -This document describes the generic device tree binding for describing the
> -relationship between PCI(e) devices and IOMMU(s).
> -
> -Each PCI(e) device under a root complex is uniquely identified by its Requester
> -ID (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
> -Function number.
> -
> -For the purpose of this document, when treated as a numeric value, a RID is
> -formatted such that:
> -
> -* Bits [15:8] are the Bus number.
> -* Bits [7:3] are the Device number.
> -* Bits [2:0] are the Function number.
> -* Any other bits required for padding must be zero.
> -
> -IOMMUs may distinguish PCI devices through sideband data derived from the
> -Requester ID. While a given PCI device can only master through one IOMMU, a
> -root complex may split masters across a set of IOMMUs (e.g. with one IOMMU per
> -bus).
> -
> -The generic 'iommus' property is insufficient to describe this relationship,
> -and a mechanism is required to map from a PCI device to its IOMMU and sideband
> -data.
> -
> -For generic IOMMU bindings, see
> -Documentation/devicetree/bindings/iommu/iommu.txt.
> -
> -
> -PCI root complex
> -================
> -
> -Optional properties
> --------------------
> -
> -- iommu-map: Maps a Requester ID to an IOMMU and associated IOMMU specifier
> -  data.
> -
> -  The property is an arbitrary number of tuples of
> -  (rid-base,iommu,iommu-base,length).
> -
> -  Any RID r in the interval [rid-base, rid-base + length) is associated with
> -  the listed IOMMU, with the IOMMU specifier (r - rid-base + iommu-base).
> -
> -- iommu-map-mask: A mask to be applied to each Requester ID prior to being
> -  mapped to an IOMMU specifier per the iommu-map property.
> -
> -
> -Example (1)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	iommu: iommu@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the IOMMU is the RID,
> -		 * identity-mapped.
> -		 */
> -		iommu-map = <0x0 &iommu 0x0 0x10000>;
> -	};
> -};
> -
> -
> -Example (2)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	iommu: iommu@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the IOMMU is the RID with the
> -		 * function bits masked out.
> -		 */
> -		iommu-map = <0x0 &iommu 0x0 0x10000>;
> -		iommu-map-mask = <0xfff8>;
> -	};
> -};
> -
> -
> -Example (3)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	iommu: iommu@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the IOMMU is the RID,
> -		 * but the high bits of the bus number are flipped.
> -		 */
> -		iommu-map = <0x0000 &iommu 0x8000 0x8000>,
> -			    <0x8000 &iommu 0x0000 0x8000>;
> -	};
> -};
> -
> -
> -Example (4)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	iommu_a: iommu@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	iommu_b: iommu@b {
> -		reg = <0xb 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	iommu_c: iommu@c {
> -		reg = <0xc 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * Devices with bus number 0-127 are mastered via IOMMU
> -		 * a, with sideband data being RID[14:0].
> -		 * Devices with bus number 128-255 are mastered via
> -		 * IOMMU b, with sideband data being RID[14:0].
> -		 * No devices master via IOMMU c.
> -		 */
> -		iommu-map = <0x0000 &iommu_a 0x0000 0x8000>,
> -			    <0x8000 &iommu_b 0x0000 0x8000>;
> -	};
> -};
> diff --git a/Documentation/devicetree/bindings/pci/pci-msi.txt b/Documentation/devicetree/bindings/pci/pci-msi.txt
> deleted file mode 100644
> index b73d839657b6..000000000000
> --- a/Documentation/devicetree/bindings/pci/pci-msi.txt
> +++ /dev/null
> @@ -1,220 +0,0 @@
> -This document describes the generic device tree binding for describing the
> -relationship between PCI devices and MSI controllers.
> -
> -Each PCI device under a root complex is uniquely identified by its Requester ID
> -(AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
> -Function number.
> -
> -For the purpose of this document, when treated as a numeric value, a RID is
> -formatted such that:
> -
> -* Bits [15:8] are the Bus number.
> -* Bits [7:3] are the Device number.
> -* Bits [2:0] are the Function number.
> -* Any other bits required for padding must be zero.
> -
> -MSIs may be distinguished in part through the use of sideband data accompanying
> -writes. In the case of PCI devices, this sideband data may be derived from the
> -Requester ID. A mechanism is required to associate a device with both the MSI
> -controllers it can address, and the sideband data that will be associated with
> -its writes to those controllers.
> -
> -For generic MSI bindings, see
> -Documentation/devicetree/bindings/interrupt-controller/msi.txt.
> -
> -
> -PCI root complex
> -================
> -
> -Optional properties
> --------------------
> -
> -- msi-map: Maps a Requester ID to an MSI controller and associated
> -  msi-specifier data. The property is an arbitrary number of tuples of
> -  (rid-base,msi-controller,msi-base,length), where:
> -
> -  * rid-base is a single cell describing the first RID matched by the entry.
> -
> -  * msi-controller is a single phandle to an MSI controller
> -
> -  * msi-base is an msi-specifier describing the msi-specifier produced for the
> -    first RID matched by the entry.
> -
> -  * length is a single cell describing how many consecutive RIDs are matched
> -    following the rid-base.
> -
> -  Any RID r in the interval [rid-base, rid-base + length) is associated with
> -  the listed msi-controller, with the msi-specifier (r - rid-base + msi-base).
> -
> -- msi-map-mask: A mask to be applied to each Requester ID prior to being mapped
> -  to an msi-specifier per the msi-map property.
> -
> -- msi-parent: Describes the MSI parent of the root complex itself. Where
> -  the root complex and MSI controller do not pass sideband data with MSI
> -  writes, this property may be used to describe the MSI controller(s)
> -  used by PCI devices under the root complex, if defined as such in the
> -  binding for the root complex.
> -
> -
> -Example (1)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	msi: msi-controller@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the MSI controller is
> -		 * the RID, identity-mapped.
> -		 */
> -		msi-map = <0x0 &msi_a 0x0 0x10000>,
> -	};
> -};
> -
> -
> -Example (2)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	msi: msi-controller@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the MSI controller is
> -		 * the RID, masked to only the device and function bits.
> -		 */
> -		msi-map = <0x0 &msi_a 0x0 0x100>,
> -		msi-map-mask = <0xff>
> -	};
> -};
> -
> -
> -Example (3)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	msi: msi-controller@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the MSI controller is
> -		 * the RID, but the high bit of the bus number is
> -		 * ignored.
> -		 */
> -		msi-map = <0x0000 &msi 0x0000 0x8000>,
> -			  <0x8000 &msi 0x0000 0x8000>;
> -	};
> -};
> -
> -
> -Example (4)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	msi: msi-controller@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the MSI controller is
> -		 * the RID, but the high bit of the bus number is
> -		 * negated.
> -		 */
> -		msi-map = <0x0000 &msi 0x8000 0x8000>,
> -			  <0x8000 &msi 0x0000 0x8000>;
> -	};
> -};
> -
> -
> -Example (5)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	msi_a: msi-controller@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	msi_b: msi-controller@b {
> -		reg = <0xb 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	msi_c: msi-controller@c {
> -		reg = <0xc 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to MSI controller a is the
> -		 * RID, but the high bit of the bus number is negated.
> -		 * The sideband data provided to MSI controller b is the
> -		 * RID, identity-mapped.
> -		 * MSI controller c is not addressable.
> -		 */
> -		msi-map = <0x0000 &msi_a 0x8000 0x08000>,
> -			  <0x8000 &msi_a 0x0000 0x08000>,
> -			  <0x0000 &msi_b 0x0000 0x10000>;
> -	};
> -};
> diff --git a/Documentation/devicetree/bindings/pci/pci.txt b/Documentation/devicetree/bindings/pci/pci.txt
> deleted file mode 100644
> index 6a8f2874a24d..000000000000
> --- a/Documentation/devicetree/bindings/pci/pci.txt
> +++ /dev/null
> @@ -1,84 +0,0 @@
> -PCI bus bridges have standardized Device Tree bindings:
> -
> -PCI Bus Binding to: IEEE Std 1275-1994
> -https://www.devicetree.org/open-firmware/bindings/pci/pci2_1.pdf
> -
> -And for the interrupt mapping part:
> -
> -Open Firmware Recommended Practice: Interrupt Mapping
> -https://www.devicetree.org/open-firmware/practice/imap/imap0_9d.pdf
> -
> -Additionally to the properties specified in the above standards a host bridge
> -driver implementation may support the following properties:
> -
> -- linux,pci-domain:
> -   If present this property assigns a fixed PCI domain number to a host bridge,
> -   otherwise an unstable (across boots) unique number will be assigned.
> -   It is required to either not set this property at all or set it for all
> -   host bridges in the system, otherwise potentially conflicting domain numbers
> -   may be assigned to root buses behind different host bridges.  The domain
> -   number for each host bridge in the system must be unique.
> -- max-link-speed:
> -   If present this property specifies PCI gen for link capability.  Host
> -   drivers could add this as a strategy to avoid unnecessary operation for
> -   unsupported link speed, for instance, trying to do training for
> -   unsupported link speed, etc.  Must be '4' for gen4, '3' for gen3, '2'
> -   for gen2, and '1' for gen1. Any other values are invalid.
> -- reset-gpios:
> -   If present this property specifies PERST# GPIO. Host drivers can parse the
> -   GPIO and apply fundamental reset to endpoints.
> -- supports-clkreq:
> -   If present this property specifies that CLKREQ signal routing exists from
> -   root port to downstream device and host bridge drivers can do programming
> -   which depends on CLKREQ signal existence. For example, programming root port
> -   not to advertise ASPM L1 Sub-States support if there is no CLKREQ signal.
> -
> -PCI-PCI Bridge properties
> --------------------------
> -
> -PCIe root ports and switch ports may be described explicitly in the device
> -tree, as children of the host bridge node. Even though those devices are
> -discoverable by probing, it might be necessary to describe properties that
> -aren't provided by standard PCIe capabilities.
> -
> -Required properties:
> -
> -- reg:
> -   Identifies the PCI-PCI bridge. As defined in the IEEE Std 1275-1994
> -   document, it is a five-cell address encoded as (phys.hi phys.mid
> -   phys.lo size.hi size.lo). phys.hi should contain the device's BDF as
> -   0b00000000 bbbbbbbb dddddfff 00000000. The other cells should be zero.
> -
> -   The bus number is defined by firmware, through the standard bridge
> -   configuration mechanism. If this port is a switch port, then firmware
> -   allocates the bus number and writes it into the Secondary Bus Number
> -   register of the bridge directly above this port. Otherwise, the bus
> -   number of a root port is the first number in the bus-range property,
> -   defaulting to zero.
> -
> -   If firmware leaves the ARI Forwarding Enable bit set in the bridge
> -   above this port, then phys.hi contains the 8-bit function number as
> -   0b00000000 bbbbbbbb ffffffff 00000000. Note that the PCIe specification
> -   recommends that firmware only leaves ARI enabled when it knows that the
> -   OS is ARI-aware.
> -
> -Optional properties:
> -
> -- external-facing:
> -   When present, the port is external-facing. All bridges and endpoints
> -   downstream of this port are external to the machine. The OS can, for
> -   example, use this information to identify devices that cannot be
> -   trusted with relaxed DMA protection, as users could easily attach
> -   malicious devices to this port.
> -
> -Example:
> -
> -pcie@10000000 {
> -	compatible = "pci-host-ecam-generic";
> -	...
> -	pcie@0008 {
> -		/* Root port 00:01.0 is external-facing */
> -		reg = <0x00000800 0 0 0 0>;
> -		external-facing;
> -	};
> -};
> --
> 2.47.2
>

Re: [PATCH] dt-bindings: PCI: Remove obsolete .txt docs

[Rob Herring]

On Fri, Apr 4, 2025 at 6:21 PM Rob Herring (Arm) <robh@kernel.org> wrote:
>
>
> On Fri, 04 Apr 2025 17:15:57 -0500, Rob Herring (Arm) wrote:
> > The content in these files has been moved to the schemas in dtschema.
> > pci.txt is covered by pci-bus-common.yaml and pci-host-bridge.yaml.
> > pci-iommu.txt is covered by pci-iommu.yaml. pci-msi.txt is covered in
> > msi-map property in pci-host-bridge.yaml.
> >
> > Cc: Frank Li <Frank.li@nxp.com>
> > Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
> > ---
> >  .../bindings/pci/nvidia,tegra194-pcie-ep.yaml |   2 +-
> >  .../devicetree/bindings/pci/pci-iommu.txt     | 171 --------------
> >  .../devicetree/bindings/pci/pci-msi.txt       | 220 ------------------
> >  Documentation/devicetree/bindings/pci/pci.txt |  84 -------
> >  4 files changed, 1 insertion(+), 476 deletions(-)
> >  delete mode 100644 Documentation/devicetree/bindings/pci/pci-iommu.txt
> >  delete mode 100644 Documentation/devicetree/bindings/pci/pci-msi.txt
> >  delete mode 100644 Documentation/devicetree/bindings/pci/pci.txt
> >
>
> My bot found errors running 'make dt_binding_check' on your patch:
>
> yamllint warnings/errors:
>
> dtschema/dtc warnings/errors:
>
>
> doc reference errors (make refcheckdocs):
> Warning: Documentation/devicetree/bindings/virtio/pci-iommu.yaml references a file that doesn't exist: Documentation/devicetree/bindings/pci/pci.txt
> Documentation/devicetree/bindings/virtio/pci-iommu.yaml: Documentation/devicetree/bindings/pci/pci.txt

I've fixed this with this[1] patch.

Rob

[1] https://lore.kernel.org/r/20250407165341.2934499-1-robh@kernel.org

Re: [PATCH] dt-bindings: PCI: Remove obsolete .txt docs

[Manivannan Sadhasivam]

On Fri, 04 Apr 2025 17:15:57 -0500, Rob Herring (Arm) wrote:
> The content in these files has been moved to the schemas in dtschema.
> pci.txt is covered by pci-bus-common.yaml and pci-host-bridge.yaml.
> pci-iommu.txt is covered by pci-iommu.yaml. pci-msi.txt is covered in
> msi-map property in pci-host-bridge.yaml.
> 
> 

Applied, thanks!

[1/1] dt-bindings: PCI: Remove obsolete .txt docs
      commit: 7ab8db9042cb37222bebf77beeb1ff4df0789a84

Best regards,
-- 
Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>

Re: [PATCH] dt-bindings: PCI: Remove obsolete .txt docs

[Bjorn Helgaas]

[+cc Jean-Philippe for virtio dangling ref]

On Fri, Apr 04, 2025 at 05:15:57PM -0500, Rob Herring (Arm) wrote:
> The content in these files has been moved to the schemas in dtschema.
> pci.txt is covered by pci-bus-common.yaml and pci-host-bridge.yaml.
> pci-iommu.txt is covered by pci-iommu.yaml. pci-msi.txt is covered in
> msi-map property in pci-host-bridge.yaml.

I guess "dtschema" refers to
https://github.com/devicetree-org/dt-schema?

I kinda wish there was some direct link from the Linux kernel source
to dt-schema where all this information now lives (Requester ID
format, iommu-map, msi-map, linux,pci-domain, reg (and reference to
IEEE Std 1275-1994), interrupt mapping info, external-facing, etc).
Being a DT neophyte, I need all the help I can get ;)

There are a few dangling references to pci.txt:

  Documentation/devicetree/bindings/pci/aardvark-pci.txt: - max-link-speed: see pci.txt
  Documentation/devicetree/bindings/pci/aardvark-pci.txt: - reset-gpios: see pci.txt
  Documentation/devicetree/bindings/pci/v3-v360epc-pci.txt:- bus-range: see pci.txt
  Documentation/devicetree/bindings/pci/v3-v360epc-pci.txt:  1275-1994 (see pci.txt) with the following restriction:
  Documentation/devicetree/bindings/virtio/pci-iommu.yaml:      zero. See Documentation/devicetree/bindings/pci/pci.txt

> --- a/Documentation/devicetree/bindings/pci/pci-iommu.txt
> +++ /dev/null
> @@ -1,171 +0,0 @@
> -This document describes the generic device tree binding for describing the
> -relationship between PCI(e) devices and IOMMU(s).
> -
> -Each PCI(e) device under a root complex is uniquely identified by its Requester
> -ID (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
> -Function number.
> -
> -For the purpose of this document, when treated as a numeric value, a RID is
> -formatted such that:
> -
> -* Bits [15:8] are the Bus number.
> -* Bits [7:3] are the Device number.
> -* Bits [2:0] are the Function number.
> -* Any other bits required for padding must be zero.
> -
> -IOMMUs may distinguish PCI devices through sideband data derived from the
> -Requester ID. While a given PCI device can only master through one IOMMU, a
> -root complex may split masters across a set of IOMMUs (e.g. with one IOMMU per
> -bus).
> -
> -The generic 'iommus' property is insufficient to describe this relationship,
> -and a mechanism is required to map from a PCI device to its IOMMU and sideband
> -data.
> -
> -For generic IOMMU bindings, see
> -Documentation/devicetree/bindings/iommu/iommu.txt.
> -
> -
> -PCI root complex
> -================
> -
> -Optional properties
> --------------------
> -
> -- iommu-map: Maps a Requester ID to an IOMMU and associated IOMMU specifier
> -  data.
> -
> -  The property is an arbitrary number of tuples of
> -  (rid-base,iommu,iommu-base,length).
> -
> -  Any RID r in the interval [rid-base, rid-base + length) is associated with
> -  the listed IOMMU, with the IOMMU specifier (r - rid-base + iommu-base).
> -
> -- iommu-map-mask: A mask to be applied to each Requester ID prior to being
> -  mapped to an IOMMU specifier per the iommu-map property.
> -
> -
> -Example (1)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	iommu: iommu@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the IOMMU is the RID,
> -		 * identity-mapped.
> -		 */
> -		iommu-map = <0x0 &iommu 0x0 0x10000>;
> -	};
> -};
> -
> -
> -Example (2)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	iommu: iommu@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the IOMMU is the RID with the
> -		 * function bits masked out.
> -		 */
> -		iommu-map = <0x0 &iommu 0x0 0x10000>;
> -		iommu-map-mask = <0xfff8>;
> -	};
> -};
> -
> -
> -Example (3)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	iommu: iommu@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the IOMMU is the RID,
> -		 * but the high bits of the bus number are flipped.
> -		 */
> -		iommu-map = <0x0000 &iommu 0x8000 0x8000>,
> -			    <0x8000 &iommu 0x0000 0x8000>;
> -	};
> -};
> -
> -
> -Example (4)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	iommu_a: iommu@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	iommu_b: iommu@b {
> -		reg = <0xb 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	iommu_c: iommu@c {
> -		reg = <0xc 0x1>;
> -		compatible = "vendor,some-iommu";
> -		#iommu-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * Devices with bus number 0-127 are mastered via IOMMU
> -		 * a, with sideband data being RID[14:0].
> -		 * Devices with bus number 128-255 are mastered via
> -		 * IOMMU b, with sideband data being RID[14:0].
> -		 * No devices master via IOMMU c.
> -		 */
> -		iommu-map = <0x0000 &iommu_a 0x0000 0x8000>,
> -			    <0x8000 &iommu_b 0x0000 0x8000>;
> -	};
> -};
> diff --git a/Documentation/devicetree/bindings/pci/pci-msi.txt b/Documentation/devicetree/bindings/pci/pci-msi.txt
> deleted file mode 100644
> index b73d839657b6..000000000000
> --- a/Documentation/devicetree/bindings/pci/pci-msi.txt
> +++ /dev/null
> @@ -1,220 +0,0 @@
> -This document describes the generic device tree binding for describing the
> -relationship between PCI devices and MSI controllers.
> -
> -Each PCI device under a root complex is uniquely identified by its Requester ID
> -(AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
> -Function number.
> -
> -For the purpose of this document, when treated as a numeric value, a RID is
> -formatted such that:
> -
> -* Bits [15:8] are the Bus number.
> -* Bits [7:3] are the Device number.
> -* Bits [2:0] are the Function number.
> -* Any other bits required for padding must be zero.
> -
> -MSIs may be distinguished in part through the use of sideband data accompanying
> -writes. In the case of PCI devices, this sideband data may be derived from the
> -Requester ID. A mechanism is required to associate a device with both the MSI
> -controllers it can address, and the sideband data that will be associated with
> -its writes to those controllers.
> -
> -For generic MSI bindings, see
> -Documentation/devicetree/bindings/interrupt-controller/msi.txt.
> -
> -
> -PCI root complex
> -================
> -
> -Optional properties
> --------------------
> -
> -- msi-map: Maps a Requester ID to an MSI controller and associated
> -  msi-specifier data. The property is an arbitrary number of tuples of
> -  (rid-base,msi-controller,msi-base,length), where:
> -
> -  * rid-base is a single cell describing the first RID matched by the entry.
> -
> -  * msi-controller is a single phandle to an MSI controller
> -
> -  * msi-base is an msi-specifier describing the msi-specifier produced for the
> -    first RID matched by the entry.
> -
> -  * length is a single cell describing how many consecutive RIDs are matched
> -    following the rid-base.
> -
> -  Any RID r in the interval [rid-base, rid-base + length) is associated with
> -  the listed msi-controller, with the msi-specifier (r - rid-base + msi-base).
> -
> -- msi-map-mask: A mask to be applied to each Requester ID prior to being mapped
> -  to an msi-specifier per the msi-map property.
> -
> -- msi-parent: Describes the MSI parent of the root complex itself. Where
> -  the root complex and MSI controller do not pass sideband data with MSI
> -  writes, this property may be used to describe the MSI controller(s)
> -  used by PCI devices under the root complex, if defined as such in the
> -  binding for the root complex.
> -
> -
> -Example (1)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	msi: msi-controller@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the MSI controller is
> -		 * the RID, identity-mapped.
> -		 */
> -		msi-map = <0x0 &msi_a 0x0 0x10000>,
> -	};
> -};
> -
> -
> -Example (2)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	msi: msi-controller@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the MSI controller is
> -		 * the RID, masked to only the device and function bits.
> -		 */
> -		msi-map = <0x0 &msi_a 0x0 0x100>,
> -		msi-map-mask = <0xff>
> -	};
> -};
> -
> -
> -Example (3)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	msi: msi-controller@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the MSI controller is
> -		 * the RID, but the high bit of the bus number is
> -		 * ignored.
> -		 */
> -		msi-map = <0x0000 &msi 0x0000 0x8000>,
> -			  <0x8000 &msi 0x0000 0x8000>;
> -	};
> -};
> -
> -
> -Example (4)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	msi: msi-controller@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to the MSI controller is
> -		 * the RID, but the high bit of the bus number is
> -		 * negated.
> -		 */
> -		msi-map = <0x0000 &msi 0x8000 0x8000>,
> -			  <0x8000 &msi 0x0000 0x8000>;
> -	};
> -};
> -
> -
> -Example (5)
> -===========
> -
> -/ {
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -
> -	msi_a: msi-controller@a {
> -		reg = <0xa 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	msi_b: msi-controller@b {
> -		reg = <0xb 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	msi_c: msi-controller@c {
> -		reg = <0xc 0x1>;
> -		compatible = "vendor,some-controller";
> -		msi-controller;
> -		#msi-cells = <1>;
> -	};
> -
> -	pci: pci@f {
> -		reg = <0xf 0x1>;
> -		compatible = "vendor,pcie-root-complex";
> -		device_type = "pci";
> -
> -		/*
> -		 * The sideband data provided to MSI controller a is the
> -		 * RID, but the high bit of the bus number is negated.
> -		 * The sideband data provided to MSI controller b is the
> -		 * RID, identity-mapped.
> -		 * MSI controller c is not addressable.
> -		 */
> -		msi-map = <0x0000 &msi_a 0x8000 0x08000>,
> -			  <0x8000 &msi_a 0x0000 0x08000>,
> -			  <0x0000 &msi_b 0x0000 0x10000>;
> -	};
> -};
> diff --git a/Documentation/devicetree/bindings/pci/pci.txt b/Documentation/devicetree/bindings/pci/pci.txt
> deleted file mode 100644
> index 6a8f2874a24d..000000000000
> --- a/Documentation/devicetree/bindings/pci/pci.txt
> +++ /dev/null
> @@ -1,84 +0,0 @@
> -PCI bus bridges have standardized Device Tree bindings:
> -
> -PCI Bus Binding to: IEEE Std 1275-1994
> -https://www.devicetree.org/open-firmware/bindings/pci/pci2_1.pdf
> -
> -And for the interrupt mapping part:
> -
> -Open Firmware Recommended Practice: Interrupt Mapping
> -https://www.devicetree.org/open-firmware/practice/imap/imap0_9d.pdf
> -
> -Additionally to the properties specified in the above standards a host bridge
> -driver implementation may support the following properties:
> -
> -- linux,pci-domain:
> -   If present this property assigns a fixed PCI domain number to a host bridge,
> -   otherwise an unstable (across boots) unique number will be assigned.
> -   It is required to either not set this property at all or set it for all
> -   host bridges in the system, otherwise potentially conflicting domain numbers
> -   may be assigned to root buses behind different host bridges.  The domain
> -   number for each host bridge in the system must be unique.
> -- max-link-speed:
> -   If present this property specifies PCI gen for link capability.  Host
> -   drivers could add this as a strategy to avoid unnecessary operation for
> -   unsupported link speed, for instance, trying to do training for
> -   unsupported link speed, etc.  Must be '4' for gen4, '3' for gen3, '2'
> -   for gen2, and '1' for gen1. Any other values are invalid.
> -- reset-gpios:
> -   If present this property specifies PERST# GPIO. Host drivers can parse the
> -   GPIO and apply fundamental reset to endpoints.
> -- supports-clkreq:
> -   If present this property specifies that CLKREQ signal routing exists from
> -   root port to downstream device and host bridge drivers can do programming
> -   which depends on CLKREQ signal existence. For example, programming root port
> -   not to advertise ASPM L1 Sub-States support if there is no CLKREQ signal.
> -
> -PCI-PCI Bridge properties
> --------------------------
> -
> -PCIe root ports and switch ports may be described explicitly in the device
> -tree, as children of the host bridge node. Even though those devices are
> -discoverable by probing, it might be necessary to describe properties that
> -aren't provided by standard PCIe capabilities.
> -
> -Required properties:
> -
> -- reg:
> -   Identifies the PCI-PCI bridge. As defined in the IEEE Std 1275-1994
> -   document, it is a five-cell address encoded as (phys.hi phys.mid
> -   phys.lo size.hi size.lo). phys.hi should contain the device's BDF as
> -   0b00000000 bbbbbbbb dddddfff 00000000. The other cells should be zero.
> -
> -   The bus number is defined by firmware, through the standard bridge
> -   configuration mechanism. If this port is a switch port, then firmware
> -   allocates the bus number and writes it into the Secondary Bus Number
> -   register of the bridge directly above this port. Otherwise, the bus
> -   number of a root port is the first number in the bus-range property,
> -   defaulting to zero.
> -
> -   If firmware leaves the ARI Forwarding Enable bit set in the bridge
> -   above this port, then phys.hi contains the 8-bit function number as
> -   0b00000000 bbbbbbbb ffffffff 00000000. Note that the PCIe specification
> -   recommends that firmware only leaves ARI enabled when it knows that the
> -   OS is ARI-aware.
> -
> -Optional properties:
> -
> -- external-facing:
> -   When present, the port is external-facing. All bridges and endpoints
> -   downstream of this port are external to the machine. The OS can, for
> -   example, use this information to identify devices that cannot be
> -   trusted with relaxed DMA protection, as users could easily attach
> -   malicious devices to this port.
> -
> -Example:
> -
> -pcie@10000000 {
> -	compatible = "pci-host-ecam-generic";
> -	...
> -	pcie@0008 {
> -		/* Root port 00:01.0 is external-facing */
> -		reg = <0x00000800 0 0 0 0>;
> -		external-facing;
> -	};
> -};
> -- 
> 2.47.2
> 

Re: [PATCH] dt-bindings: PCI: Remove obsolete .txt docs

[Rob Herring]

On Tue, Apr 22, 2025 at 12:18 PM Bjorn Helgaas <helgaas@kernel.org> wrote:
>
> [+cc Jean-Philippe for virtio dangling ref]
>
> On Fri, Apr 04, 2025 at 05:15:57PM -0500, Rob Herring (Arm) wrote:
> > The content in these files has been moved to the schemas in dtschema.
> > pci.txt is covered by pci-bus-common.yaml and pci-host-bridge.yaml.
> > pci-iommu.txt is covered by pci-iommu.yaml. pci-msi.txt is covered in
> > msi-map property in pci-host-bridge.yaml.
>
> I guess "dtschema" refers to
> https://github.com/devicetree-org/dt-schema?

Yes.

> I kinda wish there was some direct link from the Linux kernel source
> to dt-schema where all this information now lives (Requester ID
> format, iommu-map, msi-map, linux,pci-domain, reg (and reference to
> IEEE Std 1275-1994), interrupt mapping info, external-facing, etc).
> Being a DT neophyte, I need all the help I can get ;)

Links to each property wouldn't really scale. Might as well copy all
the common schemas into the kernel tree at that point.

I've thought about some tool to look-up the info. It would be easy
enough to write. I'm just not sure what's useful to folks and what the
interface should look like. It could be something like this:

$ dt-info iommu-map
schema file: path/to/schema.yaml
type: uint32-matrix
description:
 blah blah

But maybe that needs to be "dt-info property <prop>" so we could also
do "dt-info compatible <compat>".

>
> There are a few dangling references to pci.txt:
>
>   Documentation/devicetree/bindings/pci/aardvark-pci.txt: - max-link-speed: see pci.txt
>   Documentation/devicetree/bindings/pci/aardvark-pci.txt: - reset-gpios: see pci.txt
>   Documentation/devicetree/bindings/pci/v3-v360epc-pci.txt:- bus-range: see pci.txt
>   Documentation/devicetree/bindings/pci/v3-v360epc-pci.txt:  1275-1994 (see pci.txt) with the following restriction:

If no one cares enough to convert these, then I don't think the link matters.

>   Documentation/devicetree/bindings/virtio/pci-iommu.yaml:      zero. See Documentation/devicetree/bindings/pci/pci.txt

That's fixed in my tree already.

Rob

Re: [PATCH] dt-bindings: PCI: Remove obsolete .txt docs

[Bjorn Helgaas]

On Wed, Apr 23, 2025 at 08:02:04AM -0500, Rob Herring wrote:
> On Tue, Apr 22, 2025 at 12:18 PM Bjorn Helgaas <helgaas@kernel.org> wrote:
> > On Fri, Apr 04, 2025 at 05:15:57PM -0500, Rob Herring (Arm) wrote:
> > > The content in these files has been moved to the schemas in dtschema.
> > > pci.txt is covered by pci-bus-common.yaml and pci-host-bridge.yaml.
> > > pci-iommu.txt is covered by pci-iommu.yaml. pci-msi.txt is covered in
> > > msi-map property in pci-host-bridge.yaml.
> >
> > I guess "dtschema" refers to
> > https://github.com/devicetree-org/dt-schema?
> 
> Yes.
> 
> > I kinda wish there was some direct link from the Linux kernel source
> > to dt-schema where all this information now lives (Requester ID
> > format, iommu-map, msi-map, linux,pci-domain, reg (and reference to
> > IEEE Std 1275-1994), interrupt mapping info, external-facing, etc).
> > Being a DT neophyte, I need all the help I can get ;)
> 
> Links to each property wouldn't really scale. Might as well copy all
> the common schemas into the kernel tree at that point.

Right.  In my ignorance, I found it useful to just grep the Linux
source for these properties, but that doesn't work any more.

> > There are a few dangling references to pci.txt:
> >
> >   Documentation/devicetree/bindings/pci/aardvark-pci.txt: - max-link-speed: see pci.txt
> >   Documentation/devicetree/bindings/pci/aardvark-pci.txt: - reset-gpios: see pci.txt
> >   Documentation/devicetree/bindings/pci/v3-v360epc-pci.txt:- bus-range: see pci.txt
> >   Documentation/devicetree/bindings/pci/v3-v360epc-pci.txt:  1275-1994 (see pci.txt) with the following restriction:
> 
> If no one cares enough to convert these, then I don't think the link matters.

I guess the descriptions of these now live at
https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/pci/pci-bus-common.yaml

There are a few Documentation/devicetree/bindings/ files that include
URLs like that, but maybe that's not considered a canonical source?

Bjorn