1* Generic PCI host controller
2
3Firmware-initialised PCI host controllers and PCI emulations, such as the
4virtio-pci implementations found in kvmtool and other para-virtualised
5systems, do not require driver support for complexities such as regulator
6and clock management. In fact, the controller may not even require the
7configuration of a control interface by the operating system, instead
8presenting a set of fixed windows describing a subset of IO, Memory and
9Configuration Spaces.
10
11Such a controller can be described purely in terms of the standardized device
12tree bindings communicated in pci.txt:
13
14
15Properties of the host controller node:
16
17- compatible     : Must be "pci-host-cam-generic" or "pci-host-ecam-generic"
18                   depending on the layout of configuration space (CAM vs
19                   ECAM respectively).
20
21- device_type    : Must be "pci".
22
23- ranges         : As described in IEEE Std 1275-1994, but must provide
24                   at least a definition of non-prefetchable memory. One
25                   or both of prefetchable Memory and IO Space may also
26                   be provided.
27
28- bus-range      : Optional property (also described in IEEE Std 1275-1994)
29                   to indicate the range of bus numbers for this controller.
30                   If absent, defaults to <0 255> (i.e. all buses).
31
32- #address-cells : Must be 3.
33
34- #size-cells    : Must be 2.
35
36- reg            : The Configuration Space base address and size, as accessed
37                   from the parent bus.  The base address corresponds to
38                   the first bus in the "bus-range" property.  If no
39                   "bus-range" is specified, this will be bus 0 (the default).
40
41Properties of the /chosen node:
42
43- linux,pci-probe-only
44                 : Optional property which takes a single-cell argument.
45                   If '0', then Linux will assign devices in its usual manner,
46                   otherwise it will not try to assign devices and instead use
47                   them as they are configured already.
48
49Configuration Space is assumed to be memory-mapped (as opposed to being
50accessed via an ioport) and laid out with a direct correspondence to the
51geography of a PCI bus address by concatenating the various components to
52form an offset.
53
54For CAM, this 24-bit offset is:
55
56        cfg_offset(bus, device, function, register) =
57                   bus << 16 | device << 11 | function << 8 | register
58
59Whilst ECAM extends this by 4 bits to accommodate 4k of function space:
60
61        cfg_offset(bus, device, function, register) =
62                   bus << 20 | device << 15 | function << 12 | register
63
64Interrupt mapping is exactly as described in `Open Firmware Recommended
65Practice: Interrupt Mapping' and requires the following properties:
66
67- #interrupt-cells   : Must be 1
68
69- interrupt-map      : <see aforementioned specification>
70
71- interrupt-map-mask : <see aforementioned specification>
72
73
74Example:
75
76pci {
77    compatible = "pci-host-cam-generic"
78    device_type = "pci";
79    #address-cells = <3>;
80    #size-cells = <2>;
81    bus-range = <0x0 0x1>;
82
83    // CPU_PHYSICAL(2)  SIZE(2)
84    reg = <0x0 0x40000000  0x0 0x1000000>;
85
86    // BUS_ADDRESS(3)  CPU_PHYSICAL(2)  SIZE(2)
87    ranges = <0x01000000 0x0 0x01000000  0x0 0x01000000  0x0 0x00010000>,
88             <0x02000000 0x0 0x41000000  0x0 0x41000000  0x0 0x3f000000>;
89
90
91    #interrupt-cells = <0x1>;
92
93    // PCI_DEVICE(3)  INT#(1)  CONTROLLER(PHANDLE)  CONTROLLER_DATA(3)
94    interrupt-map = <  0x0 0x0 0x0  0x1  &gic  0x0 0x4 0x1
95                     0x800 0x0 0x0  0x1  &gic  0x0 0x5 0x1
96                    0x1000 0x0 0x0  0x1  &gic  0x0 0x6 0x1
97                    0x1800 0x0 0x0  0x1  &gic  0x0 0x7 0x1>;
98
99    // PCI_DEVICE(3)  INT#(1)
100    interrupt-map-mask = <0xf800 0x0 0x0  0x7>;
101}
102