dt-bindings: PCI: Remove obsolete .txt docs

  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

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>;

	};

};

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>;

	};

};

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;

	};

};