From nobody Mon Feb 9 01:22:41 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1652716338; cv=none; d=zohomail.com; s=zohoarc; b=jIjWRl7lMVx+BrI80UO5B8JRYmQuPADzaRdH+xWGQMztz8Zi7kY0tyyXlDG1figEz+n2AuW9lHjiuHwnxYp7WYeN2YjMJHr8+9210QHPJkqHKzXfeH46ual4nzEXrlm1AN8Pnhru+avsgn8ifKuDVoFgEQ9UBjARNyPKeDlpnUQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1652716338; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Xx2FTWVeMAQokeHPcoMHLq8mQsZ3MDq5Jt6v4mrbHog=; b=mYO5VLVYu7DTmTT2wnU7mVzYUYy2e8K3q09OiF/VaGidpMRqe/eybIkdrgYHPwywVavdScUCZ56bPdIfTHjvhPV8VuFv4AxA3EY8NrRa3HqQA/eNUq1Ch3z04ZkYjWMAUT3InvMZGxjxX+3k8R/ACDSgIFsws3FHrHSwaXzygVA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1652716338919597.7346272875106; Mon, 16 May 2022 08:52:18 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-394-Zfz28VuIMcmeQEiQDcDXVg-1; Mon, 16 May 2022 11:51:35 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id EFF0F1DB28A8; Mon, 16 May 2022 15:51:32 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (unknown [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 575471541C40; Mon, 16 May 2022 15:51:32 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 1B87B1947054; Mon, 16 May 2022 15:51:32 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 4FDEA194704E for ; Mon, 16 May 2022 15:51:31 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 32B3E1541C42; Mon, 16 May 2022 15:51:31 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.21]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8F4D61541C40 for ; Mon, 16 May 2022 15:51:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1652716338; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Xx2FTWVeMAQokeHPcoMHLq8mQsZ3MDq5Jt6v4mrbHog=; b=BvBk05QBJYXvTwCECadtvGNsutTL4AKIfU2rz2l1OKc/TRQOfV3nuiO95zZq9sKwH9t0ND xZi7PIkj1Vv09mboDuVFmKEnqM1H5quRBRzYUSw0/FkXUH4AldmIRLXuSO4MDI5Q1Tda7m x35z/tpVzaGeQnLHPJkDLeajAxzFKGk= X-MC-Unique: Zfz28VuIMcmeQEiQDcDXVg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 2/3] qemu: MIGRATION.txt: Move to kbase and rSTisze Date: Mon, 16 May 2022 17:51:25 +0200 Message-Id: <4b10f1254c16ee9485ee3fa8c8d662f39b65d4e2.1652715463.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1652716339820100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa --- 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 =3D> 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 `__ Basics of locking and threaded access to qemu driver primitives. + +`QEMU migration internals `__ + Description of migration phases in the ``v2`` and ``v3`` migration prot= ocol. 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 =3D [ 'locking', 'migration', 'overview', + 'qemu-migration', 'qemu-threads', 'rpc', ] diff --git a/src/qemu/MIGRATION.txt b/docs/kbase/internals/qemu-migration.r= st 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 - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +QEMU Migration Phases +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. 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 - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D +QEMU Migration Locking Rules +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D 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 migratin= g in a consistent state during the whole process. To avoid anyone from changing the domain in the middle of migration we nee= d 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 f= rom +``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 `__) in the righ= t 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 dependin= g on - migration type and version) has to start migration job and keep it activ= e: +- 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 activ= e: +- All consequent phases except for the last one have to keep the job activ= e:: 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 bef= ore -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 us= ing:: qemuMigrationJobSetPhase(driver, vm, QEMU_MIGRATION_PHASE_*); --=20 2.35.3