[libvirt PATCH 11/12] docs: document virtio failover / QEMU auto-plug of hostdev during migration

[Laine Stump]

The information in formatdomain.html seems too detailed, but it also
didn't seem right to put that information in a wiki page before the
patches are even pushed...

Signed-off-by: Laine Stump <laine at redhat.com>
---
 docs/formatdomain.html.in | 70 +++++++++++++++++++++++++++++++++++++++
 docs/news.xml             | 27 +++++++++++++++
 2 files changed, 97 insertions(+)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 6e86d057a8..e3ea89fe25 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -5871,6 +5871,76 @@
 </devices>
 ...</pre>
 
+    <h5><a id="elementsVirtioFailover">Using virtio "failover" to bond an emulated/hostdev NIC pair</a></h5>
+
+    <p>
+      <span class="since">Since 6.1.0 (QEMU and KVM only, requires
+      QEMU 4.2.0 or newer)</span> If the virtio-net driver in the
+      guest OS supports the virtio "failover" feature, it is possible
+      to setup a simple bond device comprised of one emulated virtio
+      NIC and one SRIOV VF "hostdev" NIC. In this configuration, the
+      higher-performing hostdev NIC will normally be preferred for all
+      network traffic, but when the VM is migrated, QEMU will
+      automatically unplug the VF from the VM, and then hotplug a
+      similar device once migration is completed; while migration is
+      taking place, network traffic will use the virtio NIC. (Of
+      course the emulated virtio NIC and the hostdev NIC must be
+      connected to the same subnet for bonding to work properly). The
+      interface <code><driver></code> subelement
+      attributes <code>failover</code> and <code>backupAlias</code>
+      are used to set this up - the virtio NIC will need to
+      have <code>failover='on'</code> set in
+      its <code><driver></code>, and the hostdev NIC will
+      use <code>backupAlias</code> to indicate the alias name of the
+      virtio NIC.
+    </p>
+    <p>
+      NB1: Since you must know the alias name of the virtio
+      NIC when configuring the hostdev NIC, it will need to be
+      manually set in the virtio NIC's configuration (as with all
+      other manually set alias names, it must start with "ua-".
+    </p>
+    <p>
+      NB2: Currently the only known implementation of failover in a
+      guest OS virtio-net driver requires that the MAC addresses of
+      the virtio and hostdev NIC must match. Since that may not always
+      be a requirement, libvirt doesn't enforce this limitation - it
+      is up to the person/management application that is creating the
+      configuration.
+    </p>
+    <p>
+      NB3: Since the PCI addresses of the SRIOV VFs on the hosts that
+      are the source and destination of the migration will almost
+      certainly be different, either higher level management software
+      will need to modify the <code><source></code> of the
+      hostdev NIC (<code><interface type='hostdev'></code>) at
+      the start of migration, or (a simpler solution) the
+      configuration will need to use a libvirt "hostdev" virtual
+      network that maintains a pool of such devices, as is implied in
+      the following example's use of the libvirt network named
+      "hostdev-pool" - as long as the hostdev network pools on both
+      hosts have the same name, libvirt itself will take care of
+      allocating an appropriate device on both ends of the migration.
+    </p>
+
+<pre>
+...
+<devices>
+  <interface type='network'>
+    <source network='mybridge'/>
+    <mac address='00:11:22:33:44:55'/>
+    <model type='virtio'/>
+    <driver failover='on'/>
+    <alias name='ua-backup0'/>
+  </interface>
+  <interface type='network'>
+    <source network='hostdev-pool'/>
+    <mac address='00:11:22:33:44:55'/>
+    <model type='virtio'/>
+    <driver backupAlias='ua-backup0'/>
+  </interface>
+</devices>
+...</pre>
 
     <h5><a id="elementsNICSMulticast">Multicast tunnel</a></h5>
 
diff --git a/docs/news.xml b/docs/news.xml
index 056c7ef026..051b6b3a54 100644
--- a/docs/news.xml
+++ b/docs/news.xml
@@ -44,6 +44,33 @@
 <libvirt>
   <release version="v6.1.0" date="unreleased">
     <section title="New features">
+      <change>
+        <summary>
+          support for virtio "failover" / QEMU auto-unplug of vfio devices
+        </summary>
+        <description>
+          QEMU 4.2.0 and later, combined with a sufficiently recent
+          guest virtio-net driver, supports setting up a simple
+          network bond device comprised of one virtio emulated NIC and
+          one hostdev NIC (which must be an SRIOV VF). The allure of
+          this setup is that the bond will always favor the hostdev
+          device, providing better performance, until the guest is
+          migrated - at that time QEMU will automatically unplug the
+          hostdev NIC and the bond will send all traffic via the
+          virtio NIC until migration is completed, then QEMU on the
+          destination side will hotplug a new hostdev NIC and the bond
+          will switch back to using the hostdev for network
+          traffic. The result is that guests desiring the extra
+          performance of a hostdev NIC are now migratable without
+          network downtime (performance is just degraded during
+          migration) and without requiring a complicated bonding
+          configuration in the guest OS network config and complicated
+          unplug/replug logic in the management application on the
+          host - it can instead all be accomplished in libvirt with
+          the interface <driver> subelement "failover" and
+          "backupAlias" attributes.
+        </description>
+      </change>
     </section>
     <section title="Improvements">
     </section>
-- 
2.24.1