On 5/17/2023 7:39 AM, Peter Xu wrote:
On Mon, May 15, 2023 at 10:31:59AM +0200, Juan Quintela wrote:
State what are the requeriments to get migration working between qemu
versions. And once there explain how one is supposed to implement a
new feature/default value and not break migration.
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsement...@yandex-team.ru>
Message-Id: <20230511082701.12828-1-quint...@redhat.com>
Signed-off-by: Juan Quintela <quint...@redhat.com>
---
docs/devel/migration.rst | 216 +++++++++++++++++++++++++++++++++++++++
1 file changed, 216 insertions(+)
diff --git a/docs/devel/migration.rst b/docs/devel/migration.rst
index 6f65c23b47..b4c4f3ec35 100644
--- a/docs/devel/migration.rst
+++ b/docs/devel/migration.rst
@@ -142,6 +142,222 @@ General advice for device developers
may be different on the destination. This can result in the
device state being loaded into the wrong device.
+How backwards compatibility works
+---------------------------------
+
+When we do migration, we have to QEMU process: the source and the
s/to/two/, s/process/processes/
+target. There are two cases, they are the same version or they are a
+different version.
s/a different version/different versions/
+The easy case is when they are the same version.
+The difficult one is when they are different versions.
+
+There are two things that are different, but they have very similar
+names and sometimes get confused:
(space)
+- QEMU version
+- machine version
It's normally called "machine type", so maybe use that? Or just "machine
version / machine type"?
+
+Let's start with a practical example, we start with:
+
+- qemu-system-x86_64 (v5.2), from now on qemu-5.2.
+- qemu-system-x86_64 (v5.1), from now on qemu-5.1.
+
+Related to this are the "latest" machine types defined on each of
+them:
+
+- pc-q35-5.2 (newer one in qemu-5.2) from now on pc-5.2
+- pc-q35-5.1 (newer one in qemu-5.1) from now on pc-5.1
+
+First of all, migration is only supposed to work if you use the same
+machine type in both source and destination. The QEMU hardware
+configuration needs to be the same also on source and destination.
+Most aspects of the backend configuration can be changed at will,
+except for a few cases where the backend features influence frontend
+device feature exposure. But that is not relevant for this section.
+
+I am going to list the number of combinations that we can have. Let's
+start with the trivial ones, QEMU is the same on source and
+destination:
+
+1 - qemu-5.2 -M pc-5.2 -> migrates to -> qemu-5.2 -M pc-5.2
+
+ This is the latest QEMU with the latest machine type.
+ This have to work, and if it doesn't work it is a bug.
+
+2 - qemu-5.1 -M pc-5.1 -> migrates to -> qemu-5.1 -M pc-5.1
+
+ Exactly the same case than the previous one, but for 5.1.
+ Nothing to see here either.
+
+This are the easiest ones, we will not talk more about them in this
+section.
+
+Now we start with the more interesting cases. Consider the case where
+we have the same QEMU version in both sides (qemu-5.2) but we are using
s/we are using/we are not
+the latest machine type for that version (pc-5.2) but one of an older
+QEMU version, in this case pc-5.1.
