Re: [PATCH v3 1/3] migration: Add documentation for backwards compatiblity

[Xiaoyao Li <xiaoyao.li@intel.com>]

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 <vsementsov@yandex-team.ru>
>> Message-Id: <20230511082701.12828-1-quintela@redhat.com>
>> Signed-off-by: Juan Quintela <quintela@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.