Re: [PATCH] migration: Add documentation for backwards compatiblity

[Juan Quintela <quintela@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> wrote:
> On Wed, May 10, 2023 at 09:53:41PM +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.
>> 
>> Signed-off-by: Juan Quintela <quintela@redhat.com>
>> 
>> ---
>> 
>> Hi
>> 
>> I will really appreciate reviews:
>> 
>> - I don't speak natively .rst format, so let me what I have done
>>   wrong.
>> 
>> - English is not my native language either (no points if had guessed
>>   that).
>> 
>> - This is stuff is obvious to me, so let me when I have assumed
>>   things, things that need to be claried, explained better, etc.
>> 
>> Thanks, Juan.
>> ---
>>  docs/devel/migration.rst | 212 +++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 212 insertions(+)
>> 
>> diff --git a/docs/devel/migration.rst b/docs/devel/migration.rst
>> index 6f65c23b47..daa510da42 100644
>> --- a/docs/devel/migration.rst
>> +++ b/docs/devel/migration.rst
>> @@ -142,6 +142,218 @@ 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 work
>
> s/work/works/

Don.

>
>> +--------------------------------
>> +
>> +When we do migration, we have to qemus: source and target qemu.  There
>
> 'have two qemu process, the source and the target'

Done.

>> +are two cases, they are the same version or they are a different
>> +version.  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:
>> +- qemu version
>> +- machine version
>> +
>> +Let's start with a practical example, we start with:
>> +
>> +- qemu-system-x86_64 (v5.2), from now one qemu-5.2.
>> +- qemu-system-x86_64 (v5.1), from now one qemu-5.1.
>
> s/one/on/

I did this one right on next paragraph. Sniff.
Done.

>> +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 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 configuration
>
> s/configuration/hardware configuration/ - 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.

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.



>> +
>> +If we get a device that get a new feature, or change a default value,
>
> s/get a new/has a new/

Done.

>> +we have a problem when we try to migrate between different qemu
>> +versions.
>> +
>> +So we need a way to tell qemu-5.2 than when we are using machine type
>
> s/than when/that when/

Done.

>> +pc-5.1, it needs to **not** use the feature, to be able to migrate to
>> +read qemu-5.1.
>
> s/read/real/

Done

>> +
>> +And the equivalent part when migrating from qemu-5.1 to qemu-5.2.
>> +qemu-5.2 have to expect that it is not going to get data for the new
>
> s/have/has/

Done.

>> +feature, because qemu-5.1 don't know about it.
>> +
>> +How do we tell qemu about this device feature changes?  In
>
> s/this/these/
>
>> +hw/core/machine.c:hw_compat_X_Y arrays.
>> +
>> +If we change a default value, we need to put back the old value on
>
> s/on that array/in that array/

Done.

>> +Let's see a practical example.
>> +
>> +In qemu-5.2 virtio-blk-device got multi queue support.  This is a
>> +change that is not backward compatible.  In qemu-5.1 it has one
>> +queue. In qemu-5.2 it has the same number of queues than the number of
>
> s/than the number/as the number/

Done.

>> +3 - qemu-5.2 -M pc-5.1  -> migrates to -> qemu-5.2 -M pc-5.1
>> +
>> +    Here we have the same qemu in both sides.  So it don't matter a
>
> s/don't/doesn't/

Done.

>> +    lot if we have setup the number of queues to 1 or not, because
>
> s/setup/set/

Done.

> With regards,
> Daniel

Thanks very much.

Appreciated, Juan.