From nobody Sat May 4 09:12:15 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1500979397208228.85451674365595; Tue, 25 Jul 2017 03:43:17 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id DC5A4FB88; Tue, 25 Jul 2017 10:43:13 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 222C38E820; Tue, 25 Jul 2017 10:43:12 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 2AAFC180597B; Tue, 25 Jul 2017 10:43:09 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id v6PAh7dB012387 for ; Tue, 25 Jul 2017 06:43:07 -0400 Received: by smtp.corp.redhat.com (Postfix) id 66C458FB17; Tue, 25 Jul 2017 10:43:07 +0000 (UTC) Received: from inaba.usersys.redhat.com (unknown [10.43.2.85]) by smtp.corp.redhat.com (Postfix) with ESMTPS id DEB708FB0D for ; Tue, 25 Jul 2017 10:43:03 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com DC5A4FB88 Authentication-Results: ext-mx03.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx03.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=libvir-list-bounces@redhat.com From: Andrea Bolognani To: libvir-list@redhat.com Date: Tue, 25 Jul 2017 12:42:59 +0200 Message-Id: <1500979379-26525-1-git-send-email-abologna@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH] docs: Add "PCI topology and hotplug" guidelines X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.27]); Tue, 25 Jul 2017 10:43:15 +0000 (UTC) X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" 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 bceddd2..7c4450c 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.

=20 
diff --git a/docs/pci-hotplug.html.in b/docs/pci-hotplug.html.in
new file mode 100644
index 0000000..f3d1610
--- /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 responsability of planning
+      a suitabile 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=3D'pci' index=3D'0' model=3D'pcie-root'/>
+<controller type=3D'pci' index=3D'1' model=3D'pcie-root-port'>
+  <model name=3D'pcie-root-port'/>
+  <target chassis=3D'1' port=3D'0x10'/>
+  <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x01' fu=
nction=3D'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=3D'pci' model=3D'pcie-root-port'/>
+<controller type=3D'pci' model=3D'pcie-root-port'/>
+<controller type=3D'pci' model=3D'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=3D'pci' model=3D'dmi-to-pci-bridge'/>
+<controller type=3D'pci' model=3D'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=3D'pci' index=3D'0' model=3D'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=3D'pci' index=3D'0' model=3D'pcie-root'>
+  <model name=3D'spapr-pci-host-bridge'/>
+  <target index=3D'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=3D'pci' model=3D'pci-root'/>
+<controller type=3D'pci' model=3D'pci-root'/>
+<controller type=3D'pci' model=3D'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.
+    
    
+
+  
+
--=20
2.7.5

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list