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 | 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

Only the latest APIs are fully documented and the documentation of the older variants (which are just limited versions of the new APIs anyway) points to the newest APIs. Signed-off-by: Jiri Denemark <jdenemar@redhat.com> --- src/libvirt-domain.c | 348 ++++++--------------------------------------------- 1 file changed, 36 insertions(+), 312 deletions(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index f9f5a4696..e0c69dbe7 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -3519,77 +3519,9 @@ virDomainMigrateUnmanaged(virDomainPtr domain, * Migrate the domain object from its current host to the destination * host given by dconn (a connection to the destination host). * - * Flags may be one of more of the following: - * VIR_MIGRATE_LIVE Do not pause the VM during migration - * VIR_MIGRATE_PEER2PEER Direct connection between source & destination hosts - * VIR_MIGRATE_TUNNELLED Tunnel migration data over the libvirt RPC channel - * VIR_MIGRATE_PERSIST_DEST If the migration is successful, persist the domain - * on the destination host. - * VIR_MIGRATE_UNDEFINE_SOURCE If the migration is successful, undefine the - * domain on the source host. - * VIR_MIGRATE_PAUSED Leave the domain suspended on the remote side. - * VIR_MIGRATE_NON_SHARED_DISK Migration with non-shared storage with full - * disk copy - * VIR_MIGRATE_NON_SHARED_INC Migration with non-shared storage with - * incremental disk copy - * VIR_MIGRATE_CHANGE_PROTECTION Protect against domain configuration - * changes during the migration process (set - * automatically when supported). - * VIR_MIGRATE_UNSAFE Force migration even if it is considered unsafe. - * VIR_MIGRATE_OFFLINE Migrate offline - * VIR_MIGRATE_POSTCOPY Enable (but do not start) post-copy - * - * VIR_MIGRATE_TUNNELLED requires that VIR_MIGRATE_PEER2PEER be set. - * Applications using the VIR_MIGRATE_PEER2PEER flag will probably - * prefer to invoke virDomainMigrateToURI, avoiding the need to - * open connection to the destination host themselves. - * - * If a hypervisor supports renaming domains during migration, - * then you may set the dname parameter to the new name (otherwise - * it keeps the same name). If this is not supported by the - * hypervisor, dname must be NULL or else you will get an error. - * - * If the VIR_MIGRATE_PEER2PEER flag is set, the uri parameter - * must be a valid libvirt connection URI, by which the source - * libvirt driver can connect to the destination libvirt. If - * omitted, the dconn connection object will be queried for its - * current URI. - * - * If the VIR_MIGRATE_PEER2PEER flag is NOT set, the URI parameter - * takes a hypervisor specific format. The hypervisor capabilities - * XML includes details of the support URI schemes. If omitted - * the dconn will be asked for a default URI. - * - * If you want to copy non-shared storage within migration you - * can use either VIR_MIGRATE_NON_SHARED_DISK or - * VIR_MIGRATE_NON_SHARED_INC as they are mutually exclusive. - * - * In either case it is typically only necessary to specify a - * URI if the destination host has multiple interfaces and a - * specific interface is required to transmit migration data. - * - * The maximum bandwidth (in MiB/s) that will be used to do migration - * can be specified with the bandwidth parameter. If set to 0, - * libvirt will choose a suitable default. Some hypervisors do - * not support this feature and will return an error if bandwidth - * is not 0. - * - * Users should note that implementation of VIR_MIGRATE_OFFLINE - * flag in some drivers does not copy storage or any other file - * based storage (e.g. UEFI variable storage). - * - * Enabling the VIR_MIGRATE_POSTCOPY flag tells libvirt to enable post-copy - * migration. Use virDomainMigrateStartPostCopy to switch migration into - * the post-copy mode. See virDomainMigrateStartPostCopy for more details - * about post-copy. - * - * To see which features are supported by the current hypervisor, - * see virConnectGetCapabilities, /capabilities/host/migration_features. - * - * There are many limitations on migration imposed by the underlying - * technology - for example it may not be possible to migrate between - * different processors even with the same architecture, or between - * different types of hypervisor. + * This function is similar to virDomainMigrate3, but it only supports a fixed + * set of parameters: @dname corresponds to VIR_MIGRATE_PARAM_DEST_NAME, @uri + * is VIR_MIGRATE_PARAM_URI, and @bandwidth is VIR_MIGRATE_PARAM_BANDWIDTH. * * virDomainFree should be used to free the resources after the * returned domain object is no longer needed. @@ -3740,89 +3672,10 @@ virDomainMigrate(virDomainPtr domain, * Migrate the domain object from its current host to the destination * host given by dconn (a connection to the destination host). * - * Flags may be one of more of the following: - * VIR_MIGRATE_LIVE Do not pause the VM during migration - * VIR_MIGRATE_PEER2PEER Direct connection between source & destination hosts - * VIR_MIGRATE_TUNNELLED Tunnel migration data over the libvirt RPC channel - * VIR_MIGRATE_PERSIST_DEST If the migration is successful, persist the domain - * on the destination host. - * VIR_MIGRATE_UNDEFINE_SOURCE If the migration is successful, undefine the - * domain on the source host. - * VIR_MIGRATE_PAUSED Leave the domain suspended on the remote side. - * VIR_MIGRATE_NON_SHARED_DISK Migration with non-shared storage with full - * disk copy - * VIR_MIGRATE_NON_SHARED_INC Migration with non-shared storage with - * incremental disk copy - * VIR_MIGRATE_CHANGE_PROTECTION Protect against domain configuration - * changes during the migration process (set - * automatically when supported). - * VIR_MIGRATE_UNSAFE Force migration even if it is considered unsafe. - * VIR_MIGRATE_OFFLINE Migrate offline - * VIR_MIGRATE_POSTCOPY Enable (but do not start) post-copy - * - * VIR_MIGRATE_TUNNELLED requires that VIR_MIGRATE_PEER2PEER be set. - * Applications using the VIR_MIGRATE_PEER2PEER flag will probably - * prefer to invoke virDomainMigrateToURI, avoiding the need to - * open connection to the destination host themselves. - * - * If a hypervisor supports renaming domains during migration, - * then you may set the dname parameter to the new name (otherwise - * it keeps the same name). If this is not supported by the - * hypervisor, dname must be NULL or else you will get an error. - * - * If the VIR_MIGRATE_PEER2PEER flag is set, the uri parameter - * must be a valid libvirt connection URI, by which the source - * libvirt driver can connect to the destination libvirt. If - * omitted, the dconn connection object will be queried for its - * current URI. - * - * If the VIR_MIGRATE_PEER2PEER flag is NOT set, the URI parameter - * takes a hypervisor specific format. The hypervisor capabilities - * XML includes details of the support URI schemes. If omitted - * the dconn will be asked for a default URI. - * - * If you want to copy non-shared storage within migration you - * can use either VIR_MIGRATE_NON_SHARED_DISK or - * VIR_MIGRATE_NON_SHARED_INC as they are mutually exclusive. - * - * In either case it is typically only necessary to specify a - * URI if the destination host has multiple interfaces and a - * specific interface is required to transmit migration data. - * - * The maximum bandwidth (in MiB/s) that will be used to do migration - * can be specified with the bandwidth parameter. If set to 0, - * libvirt will choose a suitable default. Some hypervisors do - * not support this feature and will return an error if bandwidth - * is not 0. - * - * Users should note that implementation of VIR_MIGRATE_OFFLINE - * flag in some drivers does not copy storage or any other file - * based storage (e.g. UEFI variable storage). - * - * Enabling the VIR_MIGRATE_POSTCOPY flag tells libvirt to enable post-copy - * migration. Use virDomainMigrateStartPostCopy to switch migration into - * the post-copy mode. See virDomainMigrateStartPostCopy for more details - * about post-copy. - * - * To see which features are supported by the current hypervisor, - * see virConnectGetCapabilities, /capabilities/host/migration_features. - * - * There are many limitations on migration imposed by the underlying - * technology - for example it may not be possible to migrate between - * different processors even with the same architecture, or between - * different types of hypervisor. - * - * If the hypervisor supports it, @dxml can be used to alter - * host-specific portions of the domain XML that will be used on - * the destination. For example, it is possible to alter the - * backing filename that is associated with a disk device, in order - * to account for naming differences between source and destination - * in accessing the underlying storage. The migration will fail - * if @dxml would cause any guest-visible changes. Pass NULL - * if no changes are needed to the XML between source and destination. - * @dxml cannot be used to rename the domain during migration (use - * @dname for that purpose). Domain name in @dxml must match the - * original domain name. + * This function is similar to virDomainMigrate3, but it only supports a fixed + * set of parameters: @dxml corresponds to VIR_MIGRATE_PARAM_DEST_XML, @dname + * is VIR_MIGRATE_PARAM_DEST_NAME, @uri is VIR_MIGRATE_PARAM_URI, and + * @bandwidth is VIR_MIGRATE_PARAM_BANDWIDTH. * * virDomainFree should be used to free the resources after the * returned domain object is no longer needed. @@ -3984,19 +3837,6 @@ virDomainMigrate2(virDomainPtr domain, * VIR_MIGRATE_TUNNELLED and VIR_MIGRATE_PEER2PEER are not supported by this * API, use virDomainMigrateToURI3 instead. * - * If you want to copy non-shared storage within migration you - * can use either VIR_MIGRATE_NON_SHARED_DISK or - * VIR_MIGRATE_NON_SHARED_INC as they are mutually exclusive. - * - * Users should note that implementation of VIR_MIGRATE_OFFLINE - * flag in some drivers does not copy storage or any other file - * based storage (e.g. UEFI variable storage). - * - * Enabling the VIR_MIGRATE_POSTCOPY flag tells libvirt to enable post-copy - * migration. Use virDomainMigrateStartPostCopy to switch migration into - * the post-copy mode. See virDomainMigrateStartPostCopy for more details - * about post-copy. - * * There are many limitations on migration imposed by the underlying * technology - for example it may not be possible to migrate between * different processors even with the same architecture, or between @@ -4219,69 +4059,20 @@ int virDomainMigrateUnmanagedCheckCompat(virDomainPtr domain, * Migrate the domain object from its current host to the destination * host given by duri. * - * Flags may be one of more of the following: - * VIR_MIGRATE_LIVE Do not pause the VM during migration - * VIR_MIGRATE_PEER2PEER Direct connection between source & destination hosts - * VIR_MIGRATE_TUNNELLED Tunnel migration data over the libvirt RPC channel - * VIR_MIGRATE_PERSIST_DEST If the migration is successful, persist the domain - * on the destination host. - * VIR_MIGRATE_UNDEFINE_SOURCE If the migration is successful, undefine the - * domain on the source host. - * VIR_MIGRATE_PAUSED Leave the domain suspended on the remote side. - * VIR_MIGRATE_NON_SHARED_DISK Migration with non-shared storage with full - * disk copy - * VIR_MIGRATE_NON_SHARED_INC Migration with non-shared storage with - * incremental disk copy - * VIR_MIGRATE_CHANGE_PROTECTION Protect against domain configuration - * changes during the migration process (set - * automatically when supported). - * VIR_MIGRATE_UNSAFE Force migration even if it is considered unsafe. - * VIR_MIGRATE_OFFLINE Migrate offline - * VIR_MIGRATE_POSTCOPY Enable (but do not start) post-copy + * This function is similar to virDomainMigrateToURI3, but it only supports a + * fixed set of parameters: @dname corresponds to VIR_MIGRATE_PARAM_DEST_NAME, + * and @bandwidth corresponds to VIR_MIGRATE_PARAM_BANDWIDTH. * * The operation of this API hinges on the VIR_MIGRATE_PEER2PEER flag. - * If the VIR_MIGRATE_PEER2PEER flag is NOT set, the duri parameter - * takes a hypervisor specific format. The uri_transports element of the - * hypervisor capabilities XML includes details of the supported URI - * schemes. Not all hypervisors will support this mode of migration, so - * if the VIR_MIGRATE_PEER2PEER flag is not set, then it may be necessary - * to use the alternative virDomainMigrate API providing and explicit - * virConnectPtr for the destination host. * - * If the VIR_MIGRATE_PEER2PEER flag IS set, the duri parameter - * must be a valid libvirt connection URI, by which the source - * libvirt driver can connect to the destination libvirt. + * If the VIR_MIGRATE_PEER2PEER flag IS set, the @duri parameter must be a + * valid libvirt connection URI, by which the source libvirt driver can connect + * to the destination libvirt. In other words, @duri corresponds to @dconnuri + * of virDomainMigrateToURI3. * - * VIR_MIGRATE_TUNNELLED requires that VIR_MIGRATE_PEER2PEER be set. - * - * If you want to copy non-shared storage within migration you - * can use either VIR_MIGRATE_NON_SHARED_DISK or - * VIR_MIGRATE_NON_SHARED_INC as they are mutually exclusive. - * - * If a hypervisor supports renaming domains during migration, - * the dname parameter specifies the new name for the domain. - * Setting dname to NULL keeps the domain name the same. If domain - * renaming is not supported by the hypervisor, dname must be NULL or - * else an error will be returned. - * - * The maximum bandwidth (in MiB/s) that will be used to do migration - * can be specified with the bandwidth parameter. If set to 0, - * libvirt will choose a suitable default. Some hypervisors do - * not support this feature and will return an error if bandwidth - * is not 0. - * - * Enabling the VIR_MIGRATE_POSTCOPY flag tells libvirt to enable post-copy - * migration. Use virDomainMigrateStartPostCopy to switch migration into - * the post-copy mode. See virDomainMigrateStartPostCopy for more details - * about post-copy. - * - * To see which features are supported by the current hypervisor, - * see virConnectGetCapabilities, /capabilities/host/migration_features. - * - * There are many limitations on migration imposed by the underlying - * technology - for example it may not be possible to migrate between - * different processors even with the same architecture, or between - * different types of hypervisor. + * If the VIR_MIGRATE_PEER2PEER flag is NOT set, the @duri parameter takes a + * hypervisor specific URI used to initiate the migration. In this case @duri + * corresponds to VIR_MIGRATE_PARAM_URI of virDomainMigrateToURI3. * * Returns 0 if the migration succeeded, -1 upon error. */ @@ -4336,84 +4127,24 @@ virDomainMigrateToURI(virDomainPtr domain, * @bandwidth: (optional) specify migration bandwidth limit in MiB/s * * Migrate the domain object from its current host to the destination - * host given by duri. + * host given by @dconnuri. * - * Flags may be one of more of the following: - * VIR_MIGRATE_LIVE Do not pause the VM during migration - * VIR_MIGRATE_PEER2PEER Direct connection between source & destination hosts - * VIR_MIGRATE_TUNNELLED Tunnel migration data over the libvirt RPC channel - * VIR_MIGRATE_PERSIST_DEST If the migration is successful, persist the domain - * on the destination host. - * VIR_MIGRATE_UNDEFINE_SOURCE If the migration is successful, undefine the - * domain on the source host. - * VIR_MIGRATE_PAUSED Leave the domain suspended on the remote side. - * VIR_MIGRATE_NON_SHARED_DISK Migration with non-shared storage with full - * disk copy - * VIR_MIGRATE_NON_SHARED_INC Migration with non-shared storage with - * incremental disk copy - * VIR_MIGRATE_CHANGE_PROTECTION Protect against domain configuration - * changes during the migration process (set - * automatically when supported). - * VIR_MIGRATE_UNSAFE Force migration even if it is considered unsafe. - * VIR_MIGRATE_OFFLINE Migrate offline - * VIR_MIGRATE_POSTCOPY Enable (but do not start) post-copy + * This function is similar to virDomainMigrateToURI3, but it only supports a + * fixed set of parameters: @miguri corresponds to VIR_MIGRATE_PARAM_URI, @dxml + * is VIR_MIGRATE_PARAM_DEST_XML, @dname is VIR_MIGRATE_PARAM_DEST_NAME, and + * @bandwidth corresponds to VIR_MIGRATE_PARAM_BANDWIDTH. * * The operation of this API hinges on the VIR_MIGRATE_PEER2PEER flag. * - * If the VIR_MIGRATE_PEER2PEER flag is set, the @dconnuri parameter - * must be a valid libvirt connection URI, by which the source - * libvirt driver can connect to the destination libvirt. If the - * VIR_MIGRATE_PEER2PEER flag is NOT set, then @dconnuri must be - * NULL. + * If the VIR_MIGRATE_PEER2PEER flag IS set, the @dconnuri parameter must be a + * valid libvirt connection URI, by which the source libvirt driver can connect + * to the destination libvirt. In other words, @dconnuri has the same semantics + * as in virDomainMigrateToURI3. * - * If the VIR_MIGRATE_TUNNELLED flag is NOT set, then the @miguri - * parameter allows specification of a URI to use to initiate the - * VM migration. It takes a hypervisor specific format. The uri_transports - * element of the hypervisor capabilities XML includes details of the - * supported URI schemes. - * - * VIR_MIGRATE_TUNNELLED requires that VIR_MIGRATE_PEER2PEER be set. - * - * If you want to copy non-shared storage within migration you - * can use either VIR_MIGRATE_NON_SHARED_DISK or - * VIR_MIGRATE_NON_SHARED_INC as they are mutually exclusive. - * As of 1.2.11 disks of some types ('file' and 'volume') are - * precreated automatically, if there's a pool defined on the - * destination for the disk path. - * - * If a hypervisor supports changing the configuration of the guest - * during migration, the @dxml parameter specifies the new config - * for the guest. The configuration must include an identical set - * of virtual devices, to ensure a stable guest ABI across migration. - * Only parameters related to host side configuration can be - * changed in the XML. Hypervisors will validate this and refuse to - * allow migration if the provided XML would cause a change in the - * guest ABI, - * - * If a hypervisor supports renaming domains during migration, - * the dname parameter specifies the new name for the domain. - * Setting dname to NULL keeps the domain name the same. If domain - * renaming is not supported by the hypervisor, dname must be NULL or - * else an error will be returned. - * - * The maximum bandwidth (in MiB/s) that will be used to do migration - * can be specified with the bandwidth parameter. If set to 0, - * libvirt will choose a suitable default. Some hypervisors do - * not support this feature and will return an error if bandwidth - * is not 0. - * - * Enabling the VIR_MIGRATE_POSTCOPY flag tells libvirt to enable post-copy - * migration. Use virDomainMigrateStartPostCopy to switch migration into - * the post-copy mode. See virDomainMigrateStartPostCopy for more details - * about post-copy. - * - * To see which features are supported by the current hypervisor, - * see virConnectGetCapabilities, /capabilities/host/migration_features. - * - * There are many limitations on migration imposed by the underlying - * technology - for example it may not be possible to migrate between - * different processors even with the same architecture, or between - * different types of hypervisor. + * If the VIR_MIGRATE_PEER2PEER flag is NOT set, the @dconnuri must be NULL + * and the @miguri parameter takes a hypervisor specific URI used to initiate + * the migration. In this case @miguri corresponds to VIR_MIGRATE_PARAM_URI of + * virDomainMigrateToURI3. * * Returns 0 if the migration succeeded, -1 upon error. */ @@ -4478,19 +4209,12 @@ virDomainMigrateToURI2(virDomainPtr domain, * * If the VIR_MIGRATE_PEER2PEER flag is NOT set, then @dconnuri must be NULL * and VIR_MIGRATE_PARAM_URI migration parameter must be filled in with - * hypervisor specific URI used to initiate the migration. This is called - * "direct" migration. - * - * VIR_MIGRATE_TUNNELLED requires that VIR_MIGRATE_PEER2PEER be set. - * - * If you want to copy non-shared storage within migration you - * can use either VIR_MIGRATE_NON_SHARED_DISK or - * VIR_MIGRATE_NON_SHARED_INC as they are mutually exclusive. - * - * Enabling the VIR_MIGRATE_POSTCOPY flag tells libvirt to enable post-copy - * migration. Use virDomainMigrateStartPostCopy to switch migration into - * the post-copy mode. See virDomainMigrateStartPostCopy for more details - * about post-copy. + * hypervisor specific URI used to initiate the migration. The uri_transports + * element of the hypervisor capabilities XML includes supported URI schemes. + * This is called "direct" migration. Not all hypervisors support this mode of + * migration, so if the VIR_MIGRATE_PEER2PEER flag is not set, then it may be + * necessary to use the alternative virDomainMigrate3 API providing an explicit + * virConnectPtr for the destination host. * * There are many limitations on migration imposed by the underlying * technology - for example it may not be possible to migrate between -- 2.11.0.rc2