From b9b0aa06a026e1f1f90223258567c524a66ffd1a Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Tue, 25 Jul 2017 09:34:53 +0200 Subject: [PATCH] docs: Add "PCI topology and hotplug" guidelines For all machine types except i440fx, making a guest hotplug capable requires some sort of planning. Add some information to help users make educated choices when defining the PCI topology of guests. Signed-off-by: Andrea Bolognani --- docs/formatdomain.html.in | 4 +- docs/pci-hotplug.html.in | 164 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 167 insertions(+), 1 deletion(-) create mode 100644 docs/pci-hotplug.html.in diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index e903526da8..fba8cfc6f3 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 0000000000..809e36f5d9
--- /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.
+    
    
+
+  
+
-- 
GitLab