diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index e903526da8046e8b1c1421a915c87d80389b57dc..fba8cfc6f35f910739b281f41a1eb638c4881fd9 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -3505,7 +3505,9 @@ appear more than once, with a group of virtual devices tied to a virtual controller. Normally, libvirt can automatically infer such controllers without requiring explicit XML markup, but sometimes - it is necessary to provide an explicit controller element. + it is necessary to provide an explicit controller element, notably + when planning the PCI topology + for guests where device hotplug is expected.

diff --git a/docs/pci-hotplug.html.in b/docs/pci-hotplug.html.in
new file mode 100644
index 0000000000000000000000000000000000000000..809e36f5d965de579e2a2957ee9022da1d97f879
--- /dev/null
+++ b/docs/pci-hotplug.html.in
@@ -0,0 +1,164 @@
+
+
+
+  
+    

PCI topology and hotplug

+ + + +

+ Perhaps surprisingly, most libvirt guests support only limited PCI + device hotplug out of the box, or even none at all. +

+

+ The reason for this apparent limitation is the fact that each + hotplugged PCI device might require additional PCI controllers to + be added to the guest, and libvirt has no way of knowing in advance + how many devices will be hotplugged during the guest's lifetime, + thus making it impossible to automatically provide the right amount + of PCI controllers: any arbitrary number would end up being too big + for some users, and too small for others. +

+

+ Ultimately, the user is the only one who knows how much the guest + will need to grow dynamically, so the responsibility of planning + a suitable PCI topology in advance falls on them. +

+

+ This document aims at providing all the information needed to + successfully plan the PCI topology of a guest. Note that the + details can vary a lot between architectures and even machine + types, hence the way it's organized. +

+ +

x86_64 architecture

+ +

q35 machine type

+ +

+ This is a PCI Express native machine type. The default PCI topology + looks like +

+ +
+<controller type='pci' index='0' model='pcie-root'/>
+<controller type='pci' index='1' model='pcie-root-port'>
+  <model name='pcie-root-port'/>
+  <target chassis='1' port='0x10'/>
+  <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/>
+</controller>
+ +

+ and supports hotplugging a single PCI Express device, either + emulated or assigned from the host. +

+

+ Slots on the pcie-root controller do not support + hotplug, so the device will be hotplugged into the + pcie-root-port controller. If you plan to hotplug + more than a single PCI Express device, you should add a suitable + number of pcie-root-port controllers when defining + the guest: for example, add +

+ +
+<controller type='pci' model='pcie-root-port'/>
+<controller type='pci' model='pcie-root-port'/>
+<controller type='pci' model='pcie-root-port'/>
+ +

+ if you expect to hotplug up to three PCI Express devices, + either emulated or assigned from the host. That's all the + information you need to provide: libvirt will fill in the + remaining details automatically. +

+

+ If you expect to hotplug legacy PCI devices, then you will need + specialized controllers, since all those mentioned above are + intended for PCI Express devices only: add +

+ +
+<controller type='pci' model='dmi-to-pci-bridge'/>
+<controller type='pci' model='pci-bridge'/>
+ +

+ and you'll be able to hotplug up to 31 legacy PCI devices, + either emulated or assigned from the host. +

+ +

i440fx (pc) machine type

+ +

+ This is a legacy PCI native machine type. The default PCI + topology looks like +

+ +
+<controller type='pci' index='0' model='pci-root'/>
+ +

+ where each of the 31 slots on the pci-root + controller is hotplug capable and can accept a legacy PCI + device, either emulated or assigned from the guest. +

+ +

ppc64 architecture

+ +

pseries machine type

+ +

+ The default PCI topology for the pseries machine + type looks like +

+ +
+<controller type='pci' index='0' model='pci-root'>
+  <model name='spapr-pci-host-bridge'/>
+  <target index='0'/>
+</controller>
+ +

+ The 31 slots on a pci-root controller are all + hotplug capable and, despite the name suggesting otherwise, + starting with QEMU 2.9 all of them can accept PCI Express + devices in addition to legacy PCI devices; however, + libvirt will only place emulated devices on the default + pci-root controller. +

+

+ In order to take advantage of improved error reporting and + recovering capabilities, PCI devices assigned from the + host need to be isolated by placing each on a separate + pci-root controller, which has to be prepared + in advance for hotplug to work: for example, add +

+ +
+<controller type='pci' model='pci-root'/>
+<controller type='pci' model='pci-root'/>
+<controller type='pci' model='pci-root'/>
+ +

+ if you expect to hotplug up to three PCI devices assigned + from the host. +

+ +

aarch64 architecture

+ +

mach-virt (virt) machine type

+ +

+ This machine type mostly behaves the same as the + q35 machine type, so you can just + refer to that section for information. +

+

+ The only difference worth mentioning is that using legacy + PCI for mach-virt guests is extremely uncommon, + so you'll probably never need to add controllers other than + pcie-root-port. +

+ + +