[libvirt] [PATCH 2/3] Consolidate documentation of virDomainMigrate{, ToURI}{, 2, 3}
Jiri Denemark
jdenemar at redhat.com
Fri Nov 25 10:51:42 UTC 2016
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 at 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
More information about the libvir-list
mailing list