Introduce yet another migration version in API.

Migration just seems to go from bad to worse. We already had to
introduce a second migration protocol when adding the QEMU driver,
since the one from Xen was insufficiently flexible to cope with
passing the data the QEMU driver required.

It turns out that this protocol still has some flaws that we
need to address. The current sequence is

 *  Src: DumpXML
          - Generate XML to pass to dst

 *  Dst: Prepare
          - Get ready to accept incoming VM
          - Generate optional cookie to pass to src

 *  Src: Perform
          - Start migration and wait for send completion
          - Kill off VM if successful, resume if failed

 *  Dst: Finish
          - Wait for recv completion and check status
          - Kill off VM if unsuccessful

The problems with this are:

 - Since the first step is a generic 'DumpXML' call, we can't
   add in other migration specific data. eg, we can't include
   any VM lease data from lock manager plugins
 - Since the first step is a generic 'DumpXML' call, we can't
   emit any 'migration begin' event on the source, or have
   any hook that runs right at the start of the process
 - Since there is no final step on the source, if the Finish
   method fails to receive all migration data & has to kill
   the VM, then there's no way to resume the original VM
   on the source

This patch attempts to introduce a version 3 that uses the
improved 5 step sequence

 *  Src: Begin
          - Generate XML to pass to dst
          - Generate optional cookie to pass to dst

 *  Dst: Prepare
          - Get ready to accept incoming VM
          - Generate optional cookie to pass to src

 *  Src: Perform
          - Start migration and wait for send completion
          - Generate optional cookie to pass to dst

 *  Dst: Finish
          - Wait for recv completion and check status
          - Kill off VM if failed, resume if success
          - Generate optional cookie to pass to src

 *  Src: Confirm
          - Kill off VM if success, resume if failed

The API is designed to allow both input and output cookies
in all methods where applicable. This lets us pass around
arbitrary extra driver specific data between src & dst during
migration. Combined with the extra 'Begin' method this lets
us pass lease information from source to dst at the start of
migration

Moving the killing of the source VM out of Perform and
into Confirm, means we can now recover if the dst host
can't successfully Finish receiving migration data.

docs/apibuild.py

@@ -42,6 +42,12 @@ ignored_functions = {
   "virDomainMigratePrepare": "private function for migration",
   "virDomainMigratePrepare2": "private function for migration",
   "virDomainMigratePrepareTunnel": "private function for tunnelled migration",
+  "virDomainMigrateBegin3": "private function for migration",
+  "virDomainMigrateFinish3": "private function for migration",
+  "virDomainMigratePerform3": "private function for migration",
+  "virDomainMigratePrepare3": "private function for migration",
+  "virDomainMigrateConfirm3": "private function for migration",
+  "virDomainMigratePrepareTunnel3": "private function for tunnelled migration",
   "virDrvSupportsFeature": "private function for remote access",
   "DllMain": "specific function for Win32",
   "virEventAddHandle": "internal function in event.c",

docs/hvsupport.pl

@@ -127,7 +127,7 @@ $apis{virDomainMigratePrepare3} = "0.9.2";
 $apis{virDomainMigratePrepareTunnel3} = "0.9.2";
 $apis{virDomainMigratePerform3} = "0.9.2";
 $apis{virDomainMigrateFinish3} = "0.9.2";
-$apis{virDomainMigrateConfirm} = "0.9.2";
+$apis{virDomainMigrateConfirm3} = "0.9.2";
 
 
 

src/driver.h

@@ -413,7 +413,7 @@ typedef int
 
 typedef int
     (*virDrvDomainMigratePrepareTunnel)
-                    (virConnectPtr conn,
+                    (virConnectPtr dconn,
                      virStreamPtr st,
                      unsigned long flags,
                      const char *dname,
@@ -528,6 +528,75 @@ typedef int
 typedef int
     (*virDrvDomainInjectNMI)(virDomainPtr dom, unsigned int flags);
 
+typedef char *
+    (*virDrvDomainMigrateBegin3)
+                    (virDomainPtr domain,
+                     char **cookieout,
+                     int *cookieoutlen,
+                     unsigned long flags,
+                     const char *dname,
+                     unsigned long resource);
+
+typedef int
+    (*virDrvDomainMigratePrepare3)
+                    (virConnectPtr dconn,
+                     const char *cookiein,
+                     int cookieinlen,
+                     char **cookieout,
+                     int *cookieoutlen,
+                     const char *uri_in,
+                     char **uri_out,
+                     unsigned long flags,
+                     const char *dname,
+                     unsigned long resource,
+                     const char *dom_xml);
+
+typedef int
+    (*virDrvDomainMigratePrepareTunnel3)
+                    (virConnectPtr dconn,
+                     virStreamPtr st,
+                     const char *cookiein,
+                     int cookieinlen,
+                     char **cookieout,
+                     int *cookieoutlen,
+                     unsigned long flags,
+                     const char *dname,
+                     unsigned long resource,
+                     const char *dom_xml);
+
+
+typedef int
+    (*virDrvDomainMigratePerform3)
+                    (virDomainPtr dom,
+                     const char *cookiein,
+                     int cookieinlen,
+                     char **cookieout,
+                     int *cookieoutlen,
+                     const char *uri,
+                     unsigned long flags,
+                     const char *dname,
+                     unsigned long resource);
+
+typedef int
+    (*virDrvDomainMigrateFinish3)
+                    (virConnectPtr dconn,
+                     const char *dname,
+                     const char *cookiein,
+                     int cookieinlen,
+                     char **cookieout,
+                     int *cookieoutlen,
+                     const char *uri,
+                     unsigned long flags,
+                     int cancelled,
+                     virDomainPtr *newdom);
+
+typedef int
+    (*virDrvDomainMigrateConfirm3)
+                    (virDomainPtr domain,
+                     const char *cookiein,
+                     int cookieinlen,
+                     unsigned long flags,
+                     int cancelled);
 
 /**
  * _virDriver:
@@ -655,6 +724,12 @@ struct _virDriver {
     virDrvDomainQemuMonitorCommand qemuDomainMonitorCommand;
     virDrvDomainOpenConsole domainOpenConsole;
     virDrvDomainInjectNMI domainInjectNMI;
+    virDrvDomainMigrateBegin3	domainMigrateBegin3;
+    virDrvDomainMigratePrepare3	domainMigratePrepare3;
+    virDrvDomainMigratePrepareTunnel3	domainMigratePrepareTunnel3;
+    virDrvDomainMigratePerform3	domainMigratePerform3;
+    virDrvDomainMigrateFinish3	domainMigrateFinish3;
+    virDrvDomainMigrateConfirm3	domainMigrateConfirm3;
 };
 
 typedef int

src/libvirt_internal.h

@@ -66,6 +66,13 @@ enum {
      * perform step is used.
      */
     VIR_DRV_FEATURE_MIGRATION_DIRECT = 5,
+
+    /*
+     * Driver supports V3-style virDomainMigrate, ie domainMigrateBegin3/
+     * domainMigratePrepare3/domainMigratePerform3/domainMigrateFinish3/
+     * domainMigrateConfirm3.
+     */
+    VIR_DRV_FEATURE_MIGRATION_V3 = 6,
 };
 
 
@@ -115,4 +122,63 @@ int virDomainMigratePrepareTunnel(virConnectPtr dconn,
                                   unsigned long resource,
                                   const char *dom_xml);
 
+
+char *virDomainMigrateBegin3(virDomainPtr domain,
+                             char **cookieout,
+                             int *cookieoutlen,
+                             unsigned long flags,
+                             const char *dname,
+                             unsigned long resource);
+
+int virDomainMigratePrepare3(virConnectPtr dconn,
+                             const char *cookiein,
+                             int cookieinlen,
+                             char **cookieout,
+                             int *cookieoutlen,
+                             const char *uri_in,
+                             char **uri_out,
+                             unsigned long flags,
+                             const char *dname,
+                             unsigned long resource,
+                             const char *dom_xml);
+
+int virDomainMigratePrepareTunnel3(virConnectPtr dconn,
+                                   virStreamPtr st,
+                                   const char *cookiein,
+                                   int cookieinlen,
+                                   char **cookieout,
+                                   int *cookieoutlen,
+                                   unsigned long flags,
+                                   const char *dname,
+                                   unsigned long resource,
+                                   const char *dom_xml);
+
+
+int virDomainMigratePerform3(virDomainPtr dom,
+                             const char *cookiein,
+                             int cookieinlen,
+                             char **cookieout,
+                             int *cookieoutlen,
+                             const char *uri,
+                             unsigned long flags,
+                             const char *dname,
+                             unsigned long resource);
+
+int virDomainMigrateFinish3(virConnectPtr dconn,
+                            const char *dname,
+                            const char *cookiein,
+                            int cookieinlen,
+                            char **cookieout,
+                            int *cookieoutlen,
+                            const char *uri,
+                            unsigned long flags,
+                            int cancelled, /* Kill the dst VM */
+                            virDomainPtr *newdom);
+
+int virDomainMigrateConfirm3(virDomainPtr domain,
+                             const char *cookiein,
+                             int cookieinlen,
+                             unsigned long flags,
+                             int restart); /* Restart the src VM */
+
 #endif

src/libvirt_private.syms

@@ -568,6 +568,12 @@ virDomainMigratePerform;
 virDomainMigratePrepare2;
 virDomainMigratePrepare;
 virDomainMigratePrepareTunnel;
+virDomainMigrateBegin3;
+virDomainMigratePrepare3;
+virDomainMigratePrepareTunnel3;
+virDomainMigratePerform3;
+virDomainMigrateFinish3;
+virDomainMigrateConfirm3;
 virDrvSupportsFeature;
 virRegisterDeviceMonitor;
 virRegisterDriver;