[+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 >
