shippable.yml: Remove the Debian9-based MinGW cross-compiler tests
[qemu.git] / docs / pcie_pci_bridge.txt
1 Generic PCI Express to PCI Bridge
2 ================================
3
4 Description
5 ===========
6 PCIE-to-PCI bridge is a new method for legacy PCI
7 hierarchies creation on Q35 machines.
8
9 Previously Intel DMI-to-PCI bridge was used for this purpose.
10 But due to its strict limitations - no support of hot-plug,
11 no cross-platform and cross-architecture support - a new generic
12 PCIE-to-PCI bridge should now be used for any legacy PCI device usage
13 with PCI Express machine.
14
15 This generic PCIE-PCI bridge is a cross-platform device,
16 can be hot-plugged into appropriate root port (requires additional actions,
17 see 'PCIE-PCI bridge hot-plug' section),
18 and supports devices hot-plug into the bridge itself
19 (with some limitations, see below).
20
21 Hot-plug of legacy PCI devices into the bridge
22 is provided by bridge's built-in Standard hot-plug Controller.
23 Though it still has some limitations, see below.
24
25 PCIE-PCI bridge hot-plug
26 =======================
27 Guest OSes require extra efforts to enable PCIE-PCI bridge hot-plug.
28 Motivation - now on init any PCI Express root port which doesn't have
29 any device plugged in, has no free buses reserved to provide any of them
30 to a hot-plugged devices in future.
31
32 To solve this problem we reserve additional buses on a firmware level.
33 Currently only SeaBIOS is supported.
34 The way of bus number to reserve delivery is special
35 Red Hat vendor-specific PCI capability, added to the root port
36 that is planned to have PCIE-PCI bridge hot-plugged in.
37
38 Capability 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
59 If any reservation field is -1 then this kind of reservation is not
60 needed and must be ignored by firmware.
61
62 At the moment this capability is used only in QEMU generic PCIe root port
63 (-device pcie-root-port). Capability construction function takes all reservation
64 fields values from corresponding device properties. By default all of them are
65 set to -1 to leave root port's default behavior unchanged.
66
67 Usage
68 =====
69 A detailed command line would be:
70
71 [qemu-bin + storage options] \
72 -m 2G \
73 -device pcie-root-port,bus=pcie.0,id=rp1 \
74 -device pcie-root-port,bus=pcie.0,id=rp2 \
75 -device pcie-root-port,bus=pcie.0,id=rp3,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
80 Then in monitor it's OK to execute next commands:
81 device_add pcie-pci-bridge,id=br3,bus=rp3 \
82 device_add e1000,bus=br2,addr=1 \
83 device_add e1000,bus=br3,addr=1
84
85 Here 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
96 Limitations
97 ===========
98 The PCIE-PCI bridge can be hot-plugged only into pcie-root-port that
99 has proper 'bus-reserve' property value to provide secondary bus for the
100 hot-plugged bridge.
101
102 Windows 7 and older versions don't support hot-plug devices into the PCIE-PCI bridge.
103 To enable device hot-plug into the bridge on Linux there're 3 ways:
104 1) Build shpchp module with this patch http://www.spinics.net/lists/linux-pci/msg63052.html
105 2) Use kernel 4.14+ where the patch mentioned above is already merged.
106 3) 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
110 Implementation
111 ==============
112 The PCIE-PCI bridge is based on PCI-PCI bridge, but also accumulates PCI Express
113 features as a PCI Express device.
114