Message-ID: <Z/PjBZVA4kgEOWm0@lizhi-Precision-Tower-5810>
Date: Mon, 7 Apr 2025 10:36:53 -0400
From: Frank Li <Frank.li@....com>
To: "Rob Herring (Arm)" <robh@...nel.org>
Cc: Bjorn Helgaas <bhelgaas@...gle.com>,
	Lorenzo Pieralisi <lpieralisi@...nel.org>,
	Krzysztof Wilczyński <kw@...ux.com>,
	Manivannan Sadhasivam <manivannan.sadhasivam@...aro.org>,
	Krzysztof Kozlowski <krzk+dt@...nel.org>,
	Conor Dooley <conor+dt@...nel.org>,
	Thierry Reding <thierry.reding@...il.com>,
	Jonathan Hunter <jonathanh@...dia.com>,
	Vidya Sagar <vidyas@...dia.com>, linux-pci@...r.kernel.org,
	devicetree@...r.kernel.org, linux-tegra@...r.kernel.org,
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH] dt-bindings: PCI: Remove obsolete .txt docs

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@....com>
> Signed-off-by: Rob Herring (Arm) <robh@...nel.org>
> ---

Reviewed-by: Frank Li <Frank.Li@....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@...00000 {
> -	compatible = "pci-host-ecam-generic";
> -	...
> -	pcie@...8 {
> -		/* Root port 00:01.0 is external-facing */
> -		reg = <0x00000800 0 0 0 0>;
> -		external-facing;
> -	};
> -};
> --
> 2.47.2
>

Powered by blists - more mailing lists