xref: /openbmc/qemu/docs/pcie_pci_bridge.txt (revision efee71c8) 
1Generic PCI Express to PCI Bridge
2================================
3
4Description
5===========
6PCIE-to-PCI bridge is a new method for legacy PCI
7hierarchies creation on Q35 machines.
8
9Previously Intel DMI-to-PCI bridge was used for this purpose.
10But due to its strict limitations - no support of hot-plug,
11no cross-platform and cross-architecture support - a new generic
12PCIE-to-PCI bridge should now be used for any legacy PCI device usage
13with PCI Express machine.
14
15This generic PCIE-PCI bridge is a cross-platform device,
16can be hot-plugged into appropriate root port (requires additional actions,
17see 'PCIE-PCI bridge hot-plug' section),
18and supports devices hot-plug into the bridge itself
19(with some limitations, see below).
20
21Hot-plug of legacy PCI devices into the bridge
22is provided by bridge's built-in Standard hot-plug Controller.
23Though it still has some limitations, see below.
24
25PCIE-PCI bridge hot-plug
26=======================
27Guest OSes require extra efforts to enable PCIE-PCI bridge hot-plug.
28Motivation - now on init any PCI Express root port which doesn't have
29any device plugged in, has no free buses reserved to provide any of them
30to a hot-plugged devices in future.
31
32To solve this problem we reserve additional buses on a firmware level.
33Currently only SeaBIOS is supported.
34The way of bus number to reserve delivery is special
35Red Hat vendor-specific PCI capability, added to the root port
36that is planned to have PCIE-PCI bridge hot-plugged in.
37
38Capability layout (defined in include/hw/pci/pci_bridge.h):
39
40    uint8_t id;     Standard PCI capability header field
41    uint8_t next;   Standard PCI capability header field
42    uint8_t len;    Standard PCI vendor-specific capability header field
43
44    uint8_t type;   Red Hat vendor-specific capability type
45                    List of currently existing types:
46                        RESOURCE_RESERVE = 1
47
48
49    uint32_t bus_res;   Minimum number of buses to reserve
50
51    uint64_t io;           IO space to reserve
52    uint32_t mem           Non-prefetchable memory to reserve
53
54    At most one of the following two fields may be set to a value
55    different from -1:
56    uint32_t mem_pref_32;  Prefetchable memory to reserve (32-bit MMIO)
57    uint64_t mem_pref_64;  Prefetchable memory to reserve (64-bit MMIO)
58
59If any reservation field is -1 then this kind of reservation is not
60needed and must be ignored by firmware.
61
62At the moment this capability is used only in QEMU generic PCIe root port
63(-device pcie-root-port). Capability construction function takes all reservation
64fields values from corresponding device properties. By default all of them are
65set to -1 to leave root port's default behavior unchanged.
66
67Usage
68=====
69A detailed command line would be:
70
71[qemu-bin + storage options] \
72-m 2G \
73-device pcie-root-port,bus=pcie.0,id=rp1,slot=1 \
74-device pcie-root-port,bus=pcie.0,id=rp2,slot=2 \
75-device pcie-root-port,bus=pcie.0,id=rp3,slot=3,bus-reserve=1 \
76-device pcie-pci-bridge,id=br1,bus=rp1 \
77-device pcie-pci-bridge,id=br2,bus=rp2 \
78-device e1000,bus=br1,addr=8
79
80Then in monitor it's OK to execute next commands:
81device_add pcie-pci-bridge,id=br3,bus=rp3 \
82device_add e1000,bus=br2,addr=1 \
83device_add e1000,bus=br3,addr=1
84
85Here you have:
86 (1) Cold-plugged:
87    - Root ports: 1 QEMU generic root port with the capability mentioned above,
88                  2 QEMU generic root ports without this capability;
89    - 2 PCIE-PCI bridges plugged into 2 different root ports;
90    - e1000 plugged into the first bridge.
91 (2) Hot-plugged:
92    - PCIE-PCI bridge, plugged into QEMU generic root port;
93    - 2 e1000 cards, one plugged into the cold-plugged PCIE-PCI bridge,
94                     another plugged into the hot-plugged bridge.
95
96Limitations
97===========
98The PCIE-PCI bridge can be hot-plugged only into pcie-root-port that
99has proper 'bus-reserve' property value to provide secondary bus for the
100hot-plugged bridge.
101
102Windows 7 and older versions don't support hot-plug devices into the PCIE-PCI bridge.
103To enable device hot-plug into the bridge on Linux there're 3 ways:
1041) Build shpchp module with this patch http://www.spinics.net/lists/linux-pci/msg63052.html
1052) Use kernel 4.14+ where the patch mentioned above is already merged.
1063) Set 'msi' property to off - this forces the bridge to use legacy INTx,
107    which allows the bridge to notify the OS about hot-plug event without having
108    BUSMASTER set.
109
110Implementation
111==============
112The PCIE-PCI bridge is based on PCI-PCI bridge, but also accumulates PCI Express
113features as a PCI Express device.
114
115