[libvirt] [PATCH 1/3] Enhance documentation of virDomainMigrateFlags
Jiri Denemark
jdenemar at redhat.com
Fri Nov 25 10:51:41 UTC 2016
The enhanced documentation of VIR_MIGRATE_RDMA_PIN_ALL fixes
https://bugzilla.redhat.com/show_bug.cgi?id=1373783
Signed-off-by: Jiri Denemark <jdenemar at redhat.com>
---
include/libvirt/libvirt-domain.h | 153 +++++++++++++++++++++++++++++++++------
1 file changed, 132 insertions(+), 21 deletions(-)
diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 5f5066074..a8435ab16 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -683,27 +683,138 @@ typedef enum {
/* Domain migration flags. */
typedef enum {
- VIR_MIGRATE_LIVE = (1 << 0), /* live migration */
- VIR_MIGRATE_PEER2PEER = (1 << 1), /* direct source -> dest host control channel */
- /* Note the less-common spelling that we're stuck with:
- VIR_MIGRATE_TUNNELLED should be VIR_MIGRATE_TUNNELED */
- VIR_MIGRATE_TUNNELLED = (1 << 2), /* tunnel migration data over libvirtd connection */
- VIR_MIGRATE_PERSIST_DEST = (1 << 3), /* persist the VM on the destination */
- VIR_MIGRATE_UNDEFINE_SOURCE = (1 << 4), /* undefine the VM on the source */
- VIR_MIGRATE_PAUSED = (1 << 5), /* pause on remote side */
- VIR_MIGRATE_NON_SHARED_DISK = (1 << 6), /* migration with non-shared storage with full disk copy */
- VIR_MIGRATE_NON_SHARED_INC = (1 << 7), /* migration with non-shared storage with incremental copy */
- /* (same base image shared between source and destination) */
- VIR_MIGRATE_CHANGE_PROTECTION = (1 << 8), /* protect for changing domain configuration through the
- * whole migration process; this will be used automatically
- * when supported */
- VIR_MIGRATE_UNSAFE = (1 << 9), /* force migration even if it is considered unsafe */
- VIR_MIGRATE_OFFLINE = (1 << 10), /* offline migrate */
- VIR_MIGRATE_COMPRESSED = (1 << 11), /* compress data during migration */
- VIR_MIGRATE_ABORT_ON_ERROR = (1 << 12), /* abort migration on I/O errors happened during migration */
- VIR_MIGRATE_AUTO_CONVERGE = (1 << 13), /* force convergence */
- VIR_MIGRATE_RDMA_PIN_ALL = (1 << 14), /* RDMA memory pinning */
- VIR_MIGRATE_POSTCOPY = (1 << 15), /* enable (but do not start) post-copy migration */
+ /* Do not pause the domain during migration. The domain's memory will
+ * be transferred to the destination host while the domain is running.
+ * The migration may never converge if the domain is changing its memory
+ * faster then it can be transferred. The domain can be manually paused
+ * anytime during migration using virDomainSuspend.
+ */
+ VIR_MIGRATE_LIVE = (1 << 0),
+
+ /* Tell the source libvirtd to connect directly to the destination host.
+ * Without this flag the client (e.g., virsh) connects to both hosts and
+ * controls the migration process. In peer-to-peer mode, the source
+ * libvirtd controls the migration by calling the destination daemon
+ * directly.
+ */
+ VIR_MIGRATE_PEER2PEER = (1 << 1),
+
+ /* Tunnel migration data over libvirtd connection. Without this flag the
+ * source hypervisor sends migration data directly to the destination
+ * hypervisor. This flag can only be used when VIR_MIGRATE_PEER2PEER is
+ * set as well.
+ *
+ * Note the less-common spelling that we're stuck with:
+ * VIR_MIGRATE_TUNNELLED should be VIR_MIGRATE_TUNNELED.
+ */
+ VIR_MIGRATE_TUNNELLED = (1 << 2),
+
+ /* Define the domain as persistent on the destination host after successful
+ * migration. If the domain was persistent on the source host and
+ * VIR_MIGRATE_UNDEFINE_SOURCE is not used, it will end up persistent on
+ * both hosts.
+ */
+ VIR_MIGRATE_PERSIST_DEST = (1 << 3),
+
+ /* Undefine the domain on the source host once migration successfully
+ * finishes.
+ */
+ VIR_MIGRATE_UNDEFINE_SOURCE = (1 << 4),
+
+ /* Leave the domain suspended on the destination host. virDomainResume (on
+ * the virDomainPtr returned by the migration API) has to be called
+ * explicitly to resume domain's virtual CPUs.
+ */
+ VIR_MIGRATE_PAUSED = (1 << 5),
+
+ /* Migrate full disk images in addition to domain's memory. By default
+ * only non-shared non-readonly disk images are transferred. The
+ * VIR_MIGRATE_PARAM_MIGRATE_DISKS parameter can be used to specify which
+ * disks should be migrated.
+ *
+ * This flag and VIR_MIGRATE_NON_SHARED_INC are mutually exclusive.
+ */
+ VIR_MIGRATE_NON_SHARED_DISK = (1 << 6),
+
+ /* Migrate disk images in addition to domain's memory. This is similar to
+ * VIR_MIGRATE_NON_SHARED_DISK, but only the top level of each disk's
+ * backing chain is copied. That is, the rest of the backing chain is
+ * expected to be present on the destination and to be exactly the same as
+ * on the source host.
+ *
+ * This flag and VIR_MIGRATE_NON_SHARED_DISK are mutually exclusive.
+ */
+ VIR_MIGRATE_NON_SHARED_INC = (1 << 7),
+
+ /* Protect against domain configuration changes during the migration
+ * process. This flag is used automatically when both sides support it.
+ * Explicitly setting this flag will cause migration to fail if either the
+ * source or the destination does not support it.
+ */
+ VIR_MIGRATE_CHANGE_PROTECTION = (1 << 8),
+
+ /* Force migration even if it is considered unsafe. In some cases libvirt
+ * may refuse to migrate the domain because doing so may lead to potential
+ * problems such as data corruption, and thus the migration is considered
+ * unsafe. For a QEMU domain this may happen if the domain uses disks
+ * without explicitly setting cache mode to "none". Migrating such domains
+ * is unsafe unless the disk images are stored on coherent clustered
+ * filesystem, such as GFS2 or GPFS.
+ */
+ VIR_MIGRATE_UNSAFE = (1 << 9),
+
+ /* Migrate a domain definition without starting the domain on the
+ * destination and without stopping it on the source host. Offline
+ * migration requires VIR_MIGRATE_PERSIST_DEST to be set.
+ *
+ * Offline migration may not copy disk storage or any other file based
+ * storage (such as UEFI variables).
+ */
+ VIR_MIGRATE_OFFLINE = (1 << 10),
+
+ /* Compress migration data. The compression methods can be specified using
+ * VIR_MIGRATE_PARAM_COMPRESSION. A hypervisor default method will be used
+ * if this parameter is omitted. Individual compression methods can be
+ * tuned via their specific VIR_MIGRATE_PARAM_COMPRESSION_* parameters.
+ */
+ VIR_MIGRATE_COMPRESSED = (1 << 11),
+
+ /* Cancel migration if a soft error (such as I/O error) happens during
+ * migration.
+ */
+ VIR_MIGRATE_ABORT_ON_ERROR = (1 << 12),
+
+ /* Enable algorithms that ensure a live migration will eventually converge.
+ * This usually means the domain will be slowed down to make sure it does
+ * not change its memory faster than a hypervisor can transfer the changed
+ * memory to the destination host. VIR_MIGRATE_PARAM_AUTO_CONVERGE_*
+ * parameters can be used to tune the algorithm.
+ */
+ VIR_MIGRATE_AUTO_CONVERGE = (1 << 13),
+
+ /* This flag can be used with RDMA migration (i.e., when
+ * VIR_MIGRATE_PARAM_URI starts with "rdma://") to tell the hypervisor
+ * to pin all domain's memory at once before migration starts rather then
+ * letting it pin memory pages as needed. This means that all memory pages
+ * belonging to the domain will be locked in host's memory and the host
+ * will not be allowed to swap them out.
+ *
+ * For QEMU/KVM this requires hard_limit memory tuning element (in the
+ * domain XML) to be used and set to the maximum memory configured for the
+ * domain plus any memory consumed by the QEMU process itself. Beware of
+ * setting the memory limit too high (and thus allowing the domain to lock
+ * most of the host's memory). Doing so may be dangerous to both the
+ * domain and the host itself since the host's kernel may run out of
+ * memory.
+ */
+ VIR_MIGRATE_RDMA_PIN_ALL = (1 << 14),
+
+ /* Setting the VIR_MIGRATE_POSTCOPY flag tells libvirt to enable post-copy
+ * migration. However, the migration will start normally and
+ * virDomainMigrateStartPostCopy needs to be called to switch it into the
+ * post-copy mode. See virDomainMigrateStartPostCopy for more details.
+ */
+ VIR_MIGRATE_POSTCOPY = (1 << 15),
} virDomainMigrateFlags;
--
2.11.0.rc2
More information about the libvir-list
mailing list