From 4faf359accb274d37ddb0e7b68617b9297b9120e Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:33 +0000 Subject: docs: Move virtio-net-failover.rst into the system manual The virtio-net-failover documentation is currently orphan and not included in any manual; move it into the system manual, immediately following the general network emulation section. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/system/index.rst | 1 + docs/system/virtio-net-failover.rst | 68 +++++++++++++++++++++++++++++++++++++ docs/virtio-net-failover.rst | 68 ------------------------------------- 3 files changed, 69 insertions(+), 68 deletions(-) create mode 100644 docs/system/virtio-net-failover.rst delete mode 100644 docs/virtio-net-failover.rst (limited to 'docs') diff --git a/docs/system/index.rst b/docs/system/index.rst index c0f685b818..d0613cd5f7 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -21,6 +21,7 @@ Contents: monitor images net + virtio-net-failover usb ivshmem linuxboot diff --git a/docs/system/virtio-net-failover.rst b/docs/system/virtio-net-failover.rst new file mode 100644 index 0000000000..6002dc5d96 --- /dev/null +++ b/docs/system/virtio-net-failover.rst @@ -0,0 +1,68 @@ +====================================== +QEMU virtio-net standby (net_failover) +====================================== + +This document explains the setup and usage of virtio-net standby feature which +is used to create a net_failover pair of devices. + +The general idea is that we have a pair of devices, a (vfio-)pci and a +virtio-net device. Before migration the vfio device is unplugged and data flows +through the virtio-net device, on the target side another vfio-pci device is +plugged in to take over the data-path. In the guest the net_failover kernel +module will pair net devices with the same MAC address. + +The two devices are called primary and standby device. The fast hardware based +networking device is called the primary device and the virtio-net device is the +standby device. + +Restrictions +------------ + +Currently only PCIe devices are allowed as primary devices, this restriction +can be lifted in the future with enhanced QEMU support. Also, only networking +devices are allowed as primary device. The user needs to ensure that primary +and standby devices are not plugged into the same PCIe slot. + +Usecase +------- + + Virtio-net standby allows easy migration while using a passed-through fast + networking device by falling back to a virtio-net device for the duration of + the migration. It is like a simple version of a bond, the difference is that it + requires no configuration in the guest. When a guest is live-migrated to + another host QEMU will unplug the primary device via the PCIe based hotplug + handler and traffic will go through the virtio-net device. On the target + system the primary device will be automatically plugged back and the + net_failover module registers it again as the primary device. + +Usage +----- + + The primary device can be hotplugged or be part of the startup configuration + + -device virtio-net-pci,netdev=hostnet1,id=net1,mac=52:54:00:6f:55:cc, \ + bus=root2,failover=on + + With the parameter failover=on the VIRTIO_NET_F_STANDBY feature will be enabled. + + -device vfio-pci,host=5e:00.2,id=hostdev0,bus=root1,failover_pair_id=net1 + + failover_pair_id references the id of the virtio-net standby device. This + is only for pairing the devices within QEMU. The guest kernel module + net_failover will match devices with identical MAC addresses. + +Hotplug +------- + + Both primary and standby device can be hotplugged via the QEMU monitor. Note + that if the virtio-net device is plugged first a warning will be issued that it + couldn't find the primary device. + +Migration +--------- + + A new migration state wait-unplug was added for this feature. If failover primary + devices are present in the configuration, migration will go into this state. + It will wait until the device unplug is completed in the guest and then move into + active state. On the target system the primary devices will be automatically hotplugged + when the feature bit was negotiated for the virtio-net standby device. diff --git a/docs/virtio-net-failover.rst b/docs/virtio-net-failover.rst deleted file mode 100644 index 6002dc5d96..0000000000 --- a/docs/virtio-net-failover.rst +++ /dev/null @@ -1,68 +0,0 @@ -====================================== -QEMU virtio-net standby (net_failover) -====================================== - -This document explains the setup and usage of virtio-net standby feature which -is used to create a net_failover pair of devices. - -The general idea is that we have a pair of devices, a (vfio-)pci and a -virtio-net device. Before migration the vfio device is unplugged and data flows -through the virtio-net device, on the target side another vfio-pci device is -plugged in to take over the data-path. In the guest the net_failover kernel -module will pair net devices with the same MAC address. - -The two devices are called primary and standby device. The fast hardware based -networking device is called the primary device and the virtio-net device is the -standby device. - -Restrictions ------------- - -Currently only PCIe devices are allowed as primary devices, this restriction -can be lifted in the future with enhanced QEMU support. Also, only networking -devices are allowed as primary device. The user needs to ensure that primary -and standby devices are not plugged into the same PCIe slot. - -Usecase -------- - - Virtio-net standby allows easy migration while using a passed-through fast - networking device by falling back to a virtio-net device for the duration of - the migration. It is like a simple version of a bond, the difference is that it - requires no configuration in the guest. When a guest is live-migrated to - another host QEMU will unplug the primary device via the PCIe based hotplug - handler and traffic will go through the virtio-net device. On the target - system the primary device will be automatically plugged back and the - net_failover module registers it again as the primary device. - -Usage ------ - - The primary device can be hotplugged or be part of the startup configuration - - -device virtio-net-pci,netdev=hostnet1,id=net1,mac=52:54:00:6f:55:cc, \ - bus=root2,failover=on - - With the parameter failover=on the VIRTIO_NET_F_STANDBY feature will be enabled. - - -device vfio-pci,host=5e:00.2,id=hostdev0,bus=root1,failover_pair_id=net1 - - failover_pair_id references the id of the virtio-net standby device. This - is only for pairing the devices within QEMU. The guest kernel module - net_failover will match devices with identical MAC addresses. - -Hotplug -------- - - Both primary and standby device can be hotplugged via the QEMU monitor. Note - that if the virtio-net device is plugged first a warning will be issued that it - couldn't find the primary device. - -Migration ---------- - - A new migration state wait-unplug was added for this feature. If failover primary - devices are present in the configuration, migration will go into this state. - It will wait until the device unplug is completed in the guest and then move into - active state. On the target system the primary devices will be automatically hotplugged - when the feature bit was negotiated for the virtio-net standby device. -- cgit v1.2.3-55-g7522