qemu: MIGRATION.txt: Move to kbase and rSTisze

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

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.

docs/kbase/internals/meson.build

@@ -5,6 +5,7 @@ docs_kbase_internals_files = [
   'locking',
   'migration',
   'overview',
+  'qemu-migration',
   'qemu-threads',
   'rpc',
 ]

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_*);