Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
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
