Documentation/devicetree/bindings/pci/host-generic-pci.yaml

   1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/pci/host-generic-pci.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: Generic PCI host controller
   8
   9 maintainers:
  10   - Will Deacon <will@kernel.org>
  11
  12 description: |
  13   Firmware-initialised PCI host controllers and PCI emulations, such as the
  14   virtio-pci implementations found in kvmtool and other para-virtualised
  15   systems, do not require driver support for complexities such as regulator
  16   and clock management. In fact, the controller may not even require the
  17   configuration of a control interface by the operating system, instead
  18   presenting a set of fixed windows describing a subset of IO, Memory and
  19   Configuration Spaces.
  20
  21   Configuration Space is assumed to be memory-mapped (as opposed to being
  22   accessed via an ioport) and laid out with a direct correspondence to the
  23   geography of a PCI bus address by concatenating the various components to
  24   form an offset.
  25
  26   For CAM, this 24-bit offset is:
  27
  28           cfg_offset(bus, device, function, register) =
  29                      bus << 16 | device << 11 | function << 8 | register
  30
  31   While ECAM extends this by 4 bits to accommodate 4k of function space:
  32
  33           cfg_offset(bus, device, function, register) =
  34                      bus << 20 | device << 15 | function << 12 | register
  35
  36 properties:
  37   compatible:
  38     description: Depends on the layout of configuration space (CAM vs ECAM
  39       respectively). May also have more specific compatibles.
  40     oneOf:
  41       - description:
  42           PCIe host controller in Arm Juno based on PLDA XpressRICH3-AXI IP
  43         items:
  44           - const: arm,juno-r1-pcie
  45           - const: plda,xpressrich3-axi
  46           - const: pci-host-ecam-generic
  47       - description: |
  48           ThunderX PCI host controller for pass-1.x silicon
  49
  50           Firmware-initialized PCI host controller to on-chip devices found on
  51           some Cavium ThunderX processors.  These devices have ECAM-based config
  52           access, but the BARs are all at fixed addresses.  We handle the fixed
  53           addresses by synthesizing Enhanced Allocation (EA) capabilities for
  54           these devices.
  55         const: cavium,pci-host-thunder-ecam
  56       - description:
  57           Cavium ThunderX PEM firmware-initialized PCIe host controller
  58         const: cavium,pci-host-thunder-pem
  59       - description:
  60           HiSilicon Hip06/Hip07 PCIe host bridge in almost-ECAM mode. Some
  61           firmware places the host controller in a mode where it is ECAM
  62           compliant for all devices other than the root complex.
  63         enum:
  64           - hisilicon,hip06-pcie-ecam
  65           - hisilicon,hip07-pcie-ecam
  66       - description: |
  67           In some cases, firmware may already have configured the Synopsys
  68           DesignWare PCIe controller in RC mode with static ATU window mappings
  69           that cover all config, MMIO and I/O spaces in a [mostly] ECAM
  70           compatible fashion. In this case, there is no need for the OS to
  71           perform any low level setup of clocks, PHYs or device registers, nor
  72           is there any reason for the driver to reconfigure ATU windows for
  73           config and/or IO space accesses at runtime.
  74
  75           In cases where the IP was synthesized with a minimum ATU window size
  76           of 64 KB, it cannot be supported by the generic ECAM driver, because
  77           it requires special config space accessors that filter accesses to
  78           device #1 and beyond on the first bus.
  79         items:
  80           - enum:
  81               - marvell,armada8k-pcie-ecam
  82               - socionext,synquacer-pcie-ecam
  83           - const: snps,dw-pcie-ecam
  84       - description:
  85           CAM or ECAM compliant PCI host controllers without any quirks
  86         enum:
  87           - pci-host-cam-generic
  88           - pci-host-ecam-generic
  89
  90   reg:
  91     description:
  92       The Configuration Space base address and size, as accessed from the parent
  93       bus. The base address corresponds to the first bus in the "bus-range"
  94       property. If no "bus-range" is specified, this will be bus 0 (the
  95       default). Some host controllers have a 2nd non-compliant address range,
  96       so 2 entries are allowed.
  97     minItems: 1
  98     maxItems: 2
  99
 100   ranges:
 101     description:
 102       As described in IEEE Std 1275-1994, but must provide at least a
 103       definition of non-prefetchable memory. One or both of prefetchable Memory
 104       and IO Space may also be provided.
 105     minItems: 1
 106     maxItems: 3
 107
 108   dma-coherent: true
 109   iommu-map: true
 110   iommu-map-mask: true
 111   msi-parent: true
 112
 113 required:
 114   - compatible
 115   - reg
 116   - ranges
 117
 118 allOf:
 119   - $ref: /schemas/pci/pci-bus.yaml#
 120   - if:
 121       properties:
 122         compatible:
 123           contains:
 124             const: arm,juno-r1-pcie
 125     then:
 126       required:
 127         - dma-coherent
 128
 129   - if:
 130       properties:
 131         compatible:
 132           not:
 133             contains:
 134               enum:
 135                 - cavium,pci-host-thunder-pem
 136                 - hisilicon,hip06-pcie-ecam
 137                 - hisilicon,hip07-pcie-ecam
 138     then:
 139       properties:
 140         reg:
 141           maxItems: 1
 142
 143 unevaluatedProperties: false
 144
 145 examples:
 146   - |
 147
 148     bus {
 149         #address-cells = <2>;
 150         #size-cells = <2>;
 151         pcie@40000000 {
 152             compatible = "pci-host-cam-generic";
 153             device_type = "pci";
 154             #address-cells = <3>;
 155             #size-cells = <2>;
 156             bus-range = <0x0 0x1>;
 157
 158             // CPU_PHYSICAL(2)  SIZE(2)
 159             reg = <0x0 0x40000000  0x0 0x1000000>;
 160
 161             // BUS_ADDRESS(3)  CPU_PHYSICAL(2)  SIZE(2)
 162             ranges = <0x01000000 0x0 0x01000000  0x0 0x01000000  0x0 0x00010000>,
 163                      <0x02000000 0x0 0x41000000  0x0 0x41000000  0x0 0x3f000000>;
 164
 165             #interrupt-cells = <0x1>;
 166
 167             // PCI_DEVICE(3)  INT#(1)  CONTROLLER(PHANDLE)  CONTROLLER_DATA(3)
 168             interrupt-map = <   0x0 0x0 0x0  0x1  &gic  0x0 0x4 0x1>,
 169                             < 0x800 0x0 0x0  0x1  &gic  0x0 0x5 0x1>,
 170                             <0x1000 0x0 0x0  0x1  &gic  0x0 0x6 0x1>,
 171                             <0x1800 0x0 0x0  0x1  &gic  0x0 0x7 0x1>;
 172
 173             // PCI_DEVICE(3)  INT#(1)
 174             interrupt-map-mask = <0xf800 0x0 0x0  0x7>;
 175         };
 176     };
 177 ...