From nobody Tue Apr 16 06:18:10 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 14867247051463.151908258117942; Fri, 10 Feb 2017 03:05:05 -0800 (PST) Received: from localhost ([::1]:43051 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cc90f-00045r-V7 for importer@patchew.org; Fri, 10 Feb 2017 06:05:01 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:48998) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cc8zm-0003oO-J5 for qemu-devel@nongnu.org; Fri, 10 Feb 2017 06:04:08 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cc8zj-0002MK-EG for qemu-devel@nongnu.org; Fri, 10 Feb 2017 06:04:06 -0500 Received: from mx1.redhat.com ([209.132.183.28]:56682) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cc8zj-0002MD-6J for qemu-devel@nongnu.org; Fri, 10 Feb 2017 06:04:03 -0500 Received: from int-mx14.intmail.prod.int.phx2.redhat.com (int-mx14.intmail.prod.int.phx2.redhat.com [10.5.11.27]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id EF195C00B8E5; Fri, 10 Feb 2017 11:04:02 +0000 (UTC) Received: from dgilbert-t530.redhat.com (ovpn-117-134.ams2.redhat.com [10.36.117.134]) by int-mx14.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id v1AB41fT009432; Fri, 10 Feb 2017 06:04:01 -0500 From: "Dr. David Alan Gilbert (git)" To: qemu-devel@nongnu.org, quintela@redhat.com, armbru@redhat.com Date: Fri, 10 Feb 2017 11:03:59 +0000 Message-Id: <20170210110359.8210-1-dgilbert@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.27 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.31]); Fri, 10 Feb 2017 11:04:03 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2] migration: Update docs to discourage version bumps X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" From: "Dr. David Alan Gilbert" Version bumps break backwards migration; update the docs to explain to people that's bad and how to avoid it. Signed-off-by: Dr. David Alan Gilbert --- docs/migration.txt | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 58 insertions(+) diff --git a/docs/migration.txt b/docs/migration.txt index b462ead..1b940a8 100644 --- a/docs/migration.txt +++ b/docs/migration.txt @@ -161,6 +161,11 @@ include/hw/hw.h. =20 =3D=3D=3D More about versions =3D=3D=3D =20 +Version numbers are intended for major incompatible changes to the +migration of a device, and using them breaks backwards-migration +compatibility; in general most changes can be made by adding Subsections +(see below) or _TEST macros (see below) which won't break compatibility. + You can see that there are several version fields: =20 - version_id: the maximum version_id supported by VMState for that device. @@ -175,6 +180,9 @@ version_id. And the function load_state_old() (if pres= ent) is able to load state from minimum_version_id_old to minimum_version_id. This function is deprecated and will be removed when no more users are left. =20 +Saving state will always create a section with the 'version_id' value +and thus can't be loaded by any older QEMU. + =3D=3D=3D Massaging functions =3D=3D=3D =20 Sometimes, it is not enough to be able to save the state directly @@ -292,6 +300,56 @@ save/send this state when we are in the middle of a pi= o operation not enabled, the values on that fields are garbage and don't need to be sent. =20 +Using a condition function that checks a 'property' to determine whether +to send a subsection allows backwards migration compatibility when +new subsections are added. + +For example; + a) Add a new property using DEFINE_PROP_BOOL - e.g. support-foo and + default it to true. + b) Add an entry to the HW_COMPAT_ for the previous version + that sets the property to false. + c) Add a static bool support_foo function that tests the property. + d) Add a subsection with a .needed set to the support_foo function + e) (potentially) Add a pre_load that sets up a default value for 'foo' + to be used if the subsection isn't loaded. + +Now that subsection will not be generated when using an older +machine type and the migration stream will be accepted by older +QEMU versions. pre-load functions can be used to initialise state +on the newer version so that they default to suitable values +when loading streams created by older QEMU versions that do not +generate the subsection. + +In some cases subsections are added for data that had been accidentally +omitted by earlier versions; if the missing data causes the migration +process to succeed but the guest to behave badly then it may be better +to send the subsection and cause the migration to explicitly fail +with the unknown subsection error. If the bad behaviour only happens +with certain data values, making the subsection conditional on +the data value (rather than the machine type) allows migrations to succeed +in most cases. In general the preference is to tie the subsection to +the machine type, and allow reliable migrations, unless the behaviour +from omission of the subsection is really bad. + +=3D Not sending existing elements =3D + +Sometimes members of the VMState are no longer needed; + removing them will break migration compatibility + making them version dependent and bumping the version will break backwar= ds + migration compatibility. + +The best way is to: + a) Add a new property/compatibility/function in the same way for subsect= ions + above. + b) replace the VMSTATE macro with the _TEST version of the macro, e.g.: + VMSTATE_UINT32(foo, barstruct) + becomes + VMSTATE_UINT32_TEST(foo, barstruct, pre_version_baz) + + Sometime in the future when we no longer care about the ancient +versions these can be killed off. + =3D Return path =3D =20 In most migration scenarios there is only a single data path that runs --=20 2.9.3