[PATCH 2/3] qemu: MIGRATION.txt: Move to kbase and rSTisze

[Peter Krempa]

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/kbase/index.rst                          |  3 +
 docs/kbase/internals/meson.build              |  1 +
 .../kbase/internals/qemu-migration.rst        | 67 ++++++++++---------
 3 files changed, 40 insertions(+), 31 deletions(-)
 rename src/qemu/MIGRATION.txt => docs/kbase/internals/qemu-migration.rst (59%)

diff --git a/docs/kbase/index.rst b/docs/kbase/index.rst
index f1cd143fab..d0f2167be8 100644
--- 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 3e84b398b2..4f7b223786 100644
--- 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/src/qemu/MIGRATION.txt b/docs/kbase/internals/qemu-migration.rst
similarity index 59%
rename from src/qemu/MIGRATION.txt
rename to docs/kbase/internals/qemu-migration.rst
index b75fe62788..d9061ca49e 100644
--- a/src/qemu/MIGRATION.txt
+++ b/docs/kbase/internals/qemu-migration.rst
@@ -1,84 +1,89 @@
-    QEMU Migration Phases
-    =====================
+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:

-Sequence v2:
+Migration protocol v2 API Sequence
+----------------------------------

-  Src: DumpXML
+  **Src**: ``DumpXML``
     - Generate XML to pass to dst

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

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

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

-Sequence v3:
+Migration protocol v3 API Sequence
+----------------------------------

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

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

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

-  Dst: Finish
+  **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
+  **Src**: ``Confirm``
     - Kill off VM if success, resume if failed

-    QEMU Migration Locking Rules
-    ============================
+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.
+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:
+primitives (described in `qemu-threads <qemu-threads.html>`__) in the right way:

-* qemuMigrationJobStart
+* ``qemuMigrationJobStart``

-* qemuMigrationJobContinue
+* ``qemuMigrationJobContinue``

-* qemuMigrationJobStartPhase
+* ``qemuMigrationJobStartPhase``

-* qemuMigrationJobSetPhase
+* ``qemuMigrationJobSetPhase``

-* qemuMigrationJobFinish
+* ``qemuMigrationJobFinish``

-The sequence of calling qemuMigrationJob* helper methods is as follows:
+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:
+- 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:
+- All consequent phases except for the last one have to keep the job active::

       if (!qemuMigrationJobIsActive(vm, VIR_JOB_MIGRATION_{IN,OUT}))
           return;
@@ -86,7 +91,7 @@ The sequence of calling qemuMigrationJob* helper methods is as follows:
       ...do work...
       qemuMigrationJobContinue(vm);

-- The last migration phase finally finishes the migration job:
+- The last migration phase finally finishes the migration job::

       if (!qemuMigrationJobIsActive(vm, VIR_JOB_MIGRATION_{IN,OUT}))
           return;
@@ -94,7 +99,7 @@ The sequence of calling qemuMigrationJob* helper methods is as follows:
       ...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
+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_*);
-- 
2.35.3