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
 110 required:
 111   - compatible
 112   - reg
 113   - ranges
 114
 115 allOf:
 116   - $ref: /schemas/pci/pci-bus.yaml#
 117   - if:
 118       properties:
 119         compatible:
 120           contains:
 121             const: arm,juno-r1-pcie
 122     then:
 123       required:
 124         - dma-coherent
 125
 126   - if:
 127       properties:
 128         compatible:
 129           not:
 130             contains:
 131               enum:
 132                 - cavium,pci-host-thunder-pem
 133                 - hisilicon,hip06-pcie-ecam
 134                 - hisilicon,hip07-pcie-ecam
 135     then:
 136       properties:
 137         reg:
 138           maxItems: 1
 139
 140 unevaluatedProperties: false
 141
 142 examples:
 143   - |
 144
 145     bus {
 146         #address-cells = <2>;
 147         #size-cells = <2>;
 148         pcie@40000000 {
 149             compatible = "pci-host-cam-generic";
 150             device_type = "pci";
 151             #address-cells = <3>;
 152             #size-cells = <2>;
 153             bus-range = <0x0 0x1>;
 154
 155             // CPU_PHYSICAL(2)  SIZE(2)
 156             reg = <0x0 0x40000000  0x0 0x1000000>;
 157
 158             // BUS_ADDRESS(3)  CPU_PHYSICAL(2)  SIZE(2)
 159             ranges = <0x01000000 0x0 0x01000000  0x0 0x01000000  0x0 0x00010000>,
 160                      <0x02000000 0x0 0x41000000  0x0 0x41000000  0x0 0x3f000000>;
 161
 162             #interrupt-cells = <0x1>;
 163
 164             // PCI_DEVICE(3)  INT#(1)  CONTROLLER(PHANDLE)  CONTROLLER_DATA(3)
 165             interrupt-map = <   0x0 0x0 0x0  0x1  &gic  0x0 0x4 0x1>,
 166                             < 0x800 0x0 0x0  0x1  &gic  0x0 0x5 0x1>,
 167                             <0x1000 0x0 0x0  0x1  &gic  0x0 0x6 0x1>,
 168                             <0x1800 0x0 0x0  0x1  &gic  0x0 0x7 0x1>;
 169
 170             // PCI_DEVICE(3)  INT#(1)
 171             interrupt-map-mask = <0xf800 0x0 0x0  0x7>;
 172         };
 173     };
 174 ...