Enhance documentation of virDomainMigrateFlags

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@redhat.com>

include/libvirt/libvirt-domain.h

@@ -683,27 +683,138 @@ typedef enum {
 
 /* Domain migration flags. */
 typedef enum {
-    VIR_MIGRATE_LIVE              = (1 << 0), /* live migration */
+    /* Do not pause the domain during migration. The domain's memory will
-    VIR_MIGRATE_PEER2PEER         = (1 << 1), /* direct source -> dest host control channel */
+     * be transferred to the destination host while the domain is running.
-    /* Note the less-common spelling that we're stuck with:
+     * The migration may never converge if the domain is changing its memory
-       VIR_MIGRATE_TUNNELLED should be VIR_MIGRATE_TUNNELED */
+     * faster then it can be transferred. The domain can be manually paused
-    VIR_MIGRATE_TUNNELLED         = (1 << 2), /* tunnel migration data over libvirtd connection */
+     * anytime during migration using virDomainSuspend.
-    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_LIVE              = (1 << 0),
-    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 */
+    /* Tell the source libvirtd to connect directly to the destination host.
-    VIR_MIGRATE_NON_SHARED_INC    = (1 << 7), /* migration with non-shared storage with incremental copy */
+     * Without this flag the client (e.g., virsh) connects to both hosts and
-                                              /* (same base image shared between source and destination) */
+     * controls the migration process. In peer-to-peer mode, the source
-    VIR_MIGRATE_CHANGE_PROTECTION = (1 << 8), /* protect for changing domain configuration through the
+     * libvirtd controls the migration by calling the destination daemon
-                                               * whole migration process; this will be used automatically
+     * directly.
-                                               * when supported */
+     */
-    VIR_MIGRATE_UNSAFE            = (1 << 9), /* force migration even if it is considered unsafe */
+    VIR_MIGRATE_PEER2PEER         = (1 << 1),
-    VIR_MIGRATE_OFFLINE           = (1 << 10), /* offline migrate */
+
-    VIR_MIGRATE_COMPRESSED        = (1 << 11), /* compress data during migration */
+    /* Tunnel migration data over libvirtd connection. Without this flag the
-    VIR_MIGRATE_ABORT_ON_ERROR    = (1 << 12), /* abort migration on I/O errors happened during migration */
+     * source hypervisor sends migration data directly to the destination
-    VIR_MIGRATE_AUTO_CONVERGE     = (1 << 13), /* force convergence */
+     * hypervisor. This flag can only be used when VIR_MIGRATE_PEER2PEER is
-    VIR_MIGRATE_RDMA_PIN_ALL      = (1 << 14), /* RDMA memory pinning */
+     * set as well.
-    VIR_MIGRATE_POSTCOPY          = (1 << 15), /* enable (but do not start) post-copy migration */
+     *
+     * 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;