qemu: MIGRATION.txt: Move to kbase and rSTisze

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>

diff --git a/docs/kbase/index.rst b/docs/kbase/index.rst
index f1cd143fabbf83ed55cec4cee409a9c345e9a386..d0f2167be883b50bcb33d32478b45190e55ffb28 100644 (file)
--- a/docs/kbase/index.rst
+++ b/docs/kbase/index.rst
@@ -104,3 +104,6 @@ Internals
 
 `QEMU driver threading <internals/qemu-threads.html>`__
    Basics of locking and threaded access to qemu driver primitives.
+
+`QEMU migration internals <internals/qemu-migration.html>`__
+   Description of migration phases in the ``v2`` and ``v3`` migration protocol.

diff --git a/docs/kbase/internals/meson.build b/docs/kbase/internals/meson.build
index 3e84b398b2efaa9fda5f5175bb6e0746a7f1de5c..4f7b223786018674df194288a3b98c39c64f3145 100644 (file)
--- a/docs/kbase/internals/meson.build
+++ b/docs/kbase/internals/meson.build
@@ -5,6 +5,7 @@ docs_kbase_internals_files = [
   'locking',
   'migration',
   'overview',
+  'qemu-migration',
   'qemu-threads',
   'rpc',
 ]

diff --git a/docs/kbase/internals/qemu-migration.rst b/docs/kbase/internals/qemu-migration.rst
new file mode 100644 (file)
index 0000000..d9061ca
--- /dev/null
+++ b/docs/kbase/internals/qemu-migration.rst
@@ -0,0 +1,105 @@
+QEMU Migration Phases
+=====================
+
+.. contents::
+
+QEMU supports only migration protocols 2 and 3 (1 was lacking too many
+steps).  Repeating the protocol sequences from libvirt.c:
+
+Migration protocol v2 API Sequence
+----------------------------------
+
+  **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
+
+Migration protocol v3 API 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
+
+QEMU Migration Locking Rules
+============================
+
+Migration is a complicated beast which may span across several APIs on both
+source and destination side and we need to keep the domain we are migrating in
+a consistent state during the whole process.
+
+To avoid anyone from changing the domain in the middle of migration we need to
+keep ``MIGRATION_OUT`` job active during migration from ``Begin`` to
+``Confirm`` on the source side and ``MIGRATION_IN`` job has to be active from
+``Prepare`` to ``Finish`` on the destination side.
+
+For this purpose we introduce several helper methods to deal with locking
+primitives (described in `qemu-threads <qemu-threads.html>`__) in the right way:
+
+* ``qemuMigrationJobStart``
+
+* ``qemuMigrationJobContinue``
+
+* ``qemuMigrationJobStartPhase``
+
+* ``qemuMigrationJobSetPhase``
+
+* ``qemuMigrationJobFinish``
+
+The sequence of calling ``qemuMigrationJob*`` helper methods is as follows:
+
+- The first API of a migration protocol (``Prepare`` or ``Perform/Begin``
+  depending on migration type and version) has to start migration job and keep
+  it active::
+
+      qemuMigrationJobStart(driver, vm, VIR_JOB_MIGRATION_{IN,OUT});
+      qemuMigrationJobSetPhase(driver, vm, QEMU_MIGRATION_PHASE_*);
+      ...do work...
+      qemuMigrationJobContinue(vm);
+
+- All consequent phases except for the last one have to keep the job active::
+
+      if (!qemuMigrationJobIsActive(vm, VIR_JOB_MIGRATION_{IN,OUT}))
+          return;
+      qemuMigrationJobStartPhase(driver, vm, QEMU_MIGRATION_PHASE_*);
+      ...do work...
+      qemuMigrationJobContinue(vm);
+
+- The last migration phase finally finishes the migration job::
+
+      if (!qemuMigrationJobIsActive(vm, VIR_JOB_MIGRATION_{IN,OUT}))
+          return;
+      qemuMigrationJobStartPhase(driver, vm, QEMU_MIGRATION_PHASE_*);
+      ...do work...
+      qemuMigrationJobFinish(driver, vm);
+
+While migration job is running (i.e., after ``qemuMigrationJobStart*`` but before
+``qemuMigrationJob{Continue,Finish}``), migration phase can be advanced using::
+
+      qemuMigrationJobSetPhase(driver, vm, QEMU_MIGRATION_PHASE_*);

diff --git a/src/qemu/MIGRATION.txt b/src/qemu/MIGRATION.txt
deleted file mode 100644 (file)
index b75fe62..0000000
--- a/src/qemu/MIGRATION.txt
+++ /dev/null
@@ -1,100 +0,0 @@
-    QEMU Migration Phases
-    =====================
-
-QEMU supports only migration protocols 2 and 3 (1 was lacking too many
-steps).  Repeating the protocol sequences from libvirt.c:
-
-Sequence v2:
-
-  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
-
-Sequence v3:
-
-  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
-
-    QEMU Migration Locking Rules
-    ============================
-
-Migration is a complicated beast which may span across several APIs on both
-source and destination side and we need to keep the domain we are migrating in
-a consistent state during the whole process.
-
-To avoid anyone from changing the domain in the middle of migration we need to
-keep MIGRATION_OUT job active during migration from Begin to Confirm on the
-source side and MIGRATION_IN job has to be active from Prepare to Finish on
-the destination side.
-
-For this purpose we introduce several helper methods to deal with locking
-primitives (described in THREADS.txt) in the right way:
-
-* qemuMigrationJobStart
-
-* qemuMigrationJobContinue
-
-* qemuMigrationJobStartPhase
-
-* qemuMigrationJobSetPhase
-
-* qemuMigrationJobFinish
-
-The sequence of calling qemuMigrationJob* helper methods is as follows:
-
-- The first API of a migration protocol (Prepare or Perform/Begin depending on
-  migration type and version) has to start migration job and keep it active:
-
-      qemuMigrationJobStart(driver, vm, VIR_JOB_MIGRATION_{IN,OUT});
-      qemuMigrationJobSetPhase(driver, vm, QEMU_MIGRATION_PHASE_*);
-      ...do work...
-      qemuMigrationJobContinue(vm);
-
-- All consequent phases except for the last one have to keep the job active:
-
-      if (!qemuMigrationJobIsActive(vm, VIR_JOB_MIGRATION_{IN,OUT}))
-          return;
-      qemuMigrationJobStartPhase(driver, vm, QEMU_MIGRATION_PHASE_*);
-      ...do work...
-      qemuMigrationJobContinue(vm);
-
-- The last migration phase finally finishes the migration job:
-
-      if (!qemuMigrationJobIsActive(vm, VIR_JOB_MIGRATION_{IN,OUT}))
-          return;
-      qemuMigrationJobStartPhase(driver, vm, QEMU_MIGRATION_PHASE_*);
-      ...do work...
-      qemuMigrationJobFinish(driver, vm);
-
-While migration job is running (i.e., after qemuMigrationJobStart* but before
-qemuMigrationJob{Continue,Finish}), migration phase can be advanced using
-
-      qemuMigrationJobSetPhase(driver, vm, QEMU_MIGRATION_PHASE_*);