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
7title: Generic PCI host controller
8
9maintainers:
10  - Will Deacon <will@kernel.org>
11
12description: |
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
36properties:
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
113required:
114  - compatible
115  - reg
116  - ranges
117
118allOf:
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
143unevaluatedProperties: false
144
145examples:
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...
178