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

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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