qemu/docs/pcie.txt

25 QEMU does not have a clear socket-device matching mechanism
34 PCI Express devices should be plugged only into PCI Express Root Ports and
37 2.1 Root Bus (pcie.0)
39 Place only the following kinds of devices directly on the Root Complex:
42         the Root Complex. These will be considered Integrated Endpoints.
43         Note: Integrated Endpoints are not hot-pluggable.
47         devices with the Root Complex. Guest OSes are suspected to behave
49         with the Root Complex.
51     (2) PCI Express Root Ports (pcie-root-port), for starting exclusively
54     (3) PCI Express to PCI Bridge (pcie-pci-bridge), for starting legacy PCI
57     (4) Extra Root Complexes (pxb-pcie), if multiple PCI Express Root Buses
61    ----------------------------------------------------------------------------
63    -----------   ------------------   -------------------   --------------
64    | PCI Dev |   | PCIe Root Port |   | PCIe-PCI Bridge |   |  pxb-pcie  |
65    -----------   ------------------   -------------------   --------------
67 2.1.1 To plug a device into pcie.0 as a Root Complex Integrated Endpoint use:
68           -device <dev>[,bus=pcie.0]
69 2.1.2 To expose a new PCI Express Root Bus use:
70           -device pxb-pcie,id=pcie.1,bus_nr=x[,numa_node=y][,addr=z]
71       PCI Express Root Ports and PCI Express to PCI bridges can be
73           -device pcie-root-port,id=root_port1[,bus=pcie.1][,chassis=x][,slot=y][,addr=z] \
74           -device pcie-pci-bridge,id=pcie_pci_bridge1,bus=pcie.1
79 Always use PCI Express Root Ports to start PCI Express hierarchies.
81 A PCI Express Root bus supports up to 32 devices. Since each
82 PCI Express Root Port is a function and a multi-function
84 number of PCI Express Root Ports per PCI Express Root Bus is 256.
86 Prefer grouping PCI Express Root Ports into multi-function devices
88 Only use PCI Express Switches (x3130-upstream, xio3130-downstream)
89 if there is no more room for PCI Express Root Ports.
96    ----------------------------------------------------------------------------------
98    -------------    -------------                        -------------
99    | Root Port |    | Root Port |                        | Root Port |
100    ------------     -------------                        -------------
101          |                            -------------------------|------------------------
102     ------------                      |                 -----------------              |
104     ------------                      |      Switch     -----------------              |
106                                       |    -------------------    -------------------  |
108                                       |    -------------------    -------------------  |
109                                       -------------|-----------------------|------------
110                                              ------------
112                                              ------------
114 2.2.1 Plugging a PCI Express device into a PCI Express Root Port:
115           -device pcie-root-port,id=root_port1,chassis=x,slot=y[,bus=pcie.0][,addr=z]  \
116           -device <dev>,bus=root_port1
117 2.2.2 Using multi-function PCI Express Root Ports:
118 …   -device pcie-root-port,id=root_port1,multifunction=on,chassis=x,addr=z.0[,slot=y][,bus=pcie.0] \
119       -device pcie-root-port,id=root_port2,chassis=x1,addr=z.1[,slot=y1][,bus=pcie.0] \
120       -device pcie-root-port,id=root_port3,chassis=x2,addr=z.2[,slot=y2][,bus=pcie.0] \
122       -device pcie-root-port,id=root_port1,chassis=x,slot=y[,bus=pcie.0][,addr=z]  \
123       -device x3130-upstream,id=upstream_port1,bus=root_port1[,addr=x]          \
124 …  -device xio3130-downstream,id=downstream_port1,bus=upstream_port1,chassis=x1,slot=y1[,addr=z1]] \
125       -device <dev>,bus=downstream_port1
128   - (slot, chassis) pair is mandatory and must be unique for each
129     PCI Express Root Port. slot defaults to 0 when not specified.
130   - 'addr' parameter can be 0 for all the examples above.
137 device in question will be incapable of hot-unplugging.
138 Besides that use PCI Express to PCI Bridges (pcie-pci-bridge) in
139 combination with PCI-PCI Bridges (pci-bridge) to start PCI hierarchies.
142 (having 32 slots) and several PCI-PCI Bridges attached to it
144 The recommendation is to populate one PCI-PCI Bridge under the
145 PCI Express to PCI Bridge until is full and then plug a new PCI-PCI Bridge...
148    ----------------------------------------------
150    -----------               -------------------
151    | PCI Dev |               | PCIe-PCI Bridge |
152    -----------               -------------------
154                   ------------------    ------------------
155                   | PCI-PCI Bridge |    | PCI-PCI Bridge |
156                   ------------------    ------------------
158                                   -----------     -----------
160                                   -----------     -----------
163       -device <dev>[,bus=pcie.0]
164 2.3.2 Plugging a PCI device into a PCI-PCI Bridge:
165       -device pcie-pci-bridge,id=pcie_pci_bridge1[,bus=pcie.0] \
166       -device pci-bridge,id=pci_bridge1,bus=pcie_pci_bridge1[,chassis_nr=x][,addr=y] \
167       -device <dev>,bus=pci_bridge1[,addr=x]
173 The PCI Express Root Ports and PCI Express Downstream ports are seen by
174 Firmware/Guest OS as PCI-PCI Bridges. As required by the PCI spec, each
180 by not allocating IO space for each PCI Express Root / PCI Express
185 The IO space is very limited, to 65536 byte-wide IO ports, and may even be
187 10 PCI Express Root Ports or PCI Express Downstream Ports per system
199 machines do not support multiple PCI domains even if extra Root
200 Complexes (pxb-pcie) are used.
202 Each element of the PCI Express hierarchy (Root Complexes,
203 PCI Express Root Ports, PCI Express Downstream/Upstream ports)
205 can be attached to a PCI Express Root Port or PCI Express Downstream
213 The bus_nr properties of the pxb-pcie devices partition the 0..255 bus
215 given pxb-pcie device's root bus must fit between the bus_nr property of
216 that pxb-pcie device, and the lowest of the higher bus_nr properties
217 that the command line sets for other pxb-pcie devices.
220 5. Hot-plug
222 The PCI Express root buses (pcie.0 and the buses exposed by pxb-pcie devices)
223 do not support hot-plug, so any devices plugged into Root Complexes
224 cannot be hot-plugged/hot-unplugged:
226     (2) PCI Express Root Ports
228     (4) pxb-pcie
230 Be aware that PCI Express Downstream Ports can't be hot-plugged into
233 PCI devices can be hot-plugged into PCI Express to PCI and PCI-PCI Bridges.
234 The PCI hot-plug into PCI-PCI bridge is ACPI based, whereas hot-plug into
235 PCI Express to PCI bridges is SHPC-based. They both can work side by side with
236 the PCI Express native hot-plug.
238 PCI Express devices can be natively hot-plugged/hot-unplugged into/from
239 PCI Express Root Ports (and PCI Express Downstream Ports).
241 5.1 Planning for hot-plug:
243         Leave enough PCI-PCI Bridge slots empty or add one
244         or more empty PCI-PCI Bridges to the PCI Express to PCI Bridge.
246         For each such PCI-PCI Bridge the Guest Firmware is expected to reserve
251         per system don't use more than 9 PCI-PCI Bridges, leaving 4K for the
255         Leave enough PCI Express Root Ports empty. Use multifunction
256         PCI Express Root Ports (up to 8 ports per pcie.0 slot)
257         on the Root Complex(es), for keeping the
261         that could be put to better use with another Root Port or Downstream
262         Port, which may come handy for hot-plugging another device.
265 5.3 Hot-plug example:
266 Using HMP: (add -monitor stdio to QEMU command line)
267 …device_add <dev>,id=<id>,bus=<PCI Express Root Port Id/PCI Express Downstream Port Id/PCI-PCI Brid…
273 PCI Express Root Ports or PCI Express Downstream Ports.
274 PCI-PCI Bridge slots can be used for legacy PCI host devices.
277   > lspci -s 03:00.0 -v (as root)
280     Subsystem: Intel Corporation Dual Band Wireless-AC 7260
282     Memory at f0400000 (64-bit, non-prefetchable) [size=8K]
284     Capabilities: [d0] MSI: Enable+ Count=1/1 Maskable- 64bit+
288     Capabilities: [140] Device Serial Number 7c-7a-91-ff-ff-90-db-20
306 In both cases disable-legacy and disable-modern properties can be used
309 Note that setting disable-legacy=off will enable legacy mode (enabling