Re: [Qemu-devel] [PATCH] migration: update docs

[Eric Blake]

On 04/20/2018 12:57 PM, Dr. David Alan Gilbert (git) wrote:
> From: "Dr. David Alan Gilbert" <address@hidden>
> 
> Update the migration docs:
> 
> Among other changes:
>   * Added a general list of advice for device authors
>   * Reordered the section on conditional state (subsections etc)
>     into the order we prefer.
>   * Add a note about firmware
> 
> Signed-off-by: Dr. David Alan Gilbert <address@hidden>
> ---
>  docs/devel/migration.rst | 524 +++++++++++++++++++++++++++------------
>  1 file changed, 370 insertions(+), 154 deletions(-)

> @@ -40,16 +40,16 @@ to do migration:
>  - fd migration: do the migration using an file descriptor that is
>    passed to QEMU.  QEMU doesn't care how this file descriptor is opened.
>  
> -All these four migration protocols use the same infrastructure to
> +In addition support is included for migration using RDMA migration which

The double migration in this phrase sounds redundant.  I think you can:

s/In addition/In addition,/
s/RDMA migration which/RDMA, which/

> +transports the page data using ``RDMA``, where the hardware takes care of
> +transporting the pages, and the load on the CPU is much lower.  While the
> +internals of RDMA migration are a bit different, this isn't really visible
> +outside the RAM migration code.
> +

> +For most devices, the state is saved in a single call to the migration
> +infrastrucutre; these are *non-iterative* devices.  The data for these

s/infrastrucutre/infrastructure/

> +devices is sent at the end of precopy migration, when the CPUs are paused.
> +Where the data associated with the device is very large (e.g. RAM or large 
> tables)
> +see the iterative device section below.

> +
> +- Migrations timing out or being failed by higher levels of management,
> +  or failures of the destination host are not unusual, and care should
> +  be taken to ensure that the source VM can be restarted up until the point
> +  when the destination starts runing.  Valid examples include the management

s/runing/running/

> +  layer reverting the migration even though the QEMU level of migration has
> +  succeeded.  For this reason, the state on the source VM should not be
> +  destroyed during the migration process in normal use.
> +
> +- Busses and devices should be able to explicitly specify addresses when

s/Busses/Buses/ ? (both spellings are common, but busses can also be
confused with a synonym of kisses)

> +When we migrate a device, we save/load the state as a series
> +of fields.  Some times, due to bugs or new functionality, we need to
> +change the state to store more/different information.  Changing the migration
> +state saved for a device can break migration comppatibility unless

s/comppatibility/compatibility/

> +care is taken to use the appropriate techniques.  In general QEMU tries
> +to maintain forward migration compaitibility (i.e. migrating from

s/compaitibility/compatibility/

> +QEMU n->n+1) and there are users who benefit from backwards compatibility
> +as well.

(fun - 3 spellings among 3 uses in 2 sentences - at least the last one
was right)


> +Note that the contents of the sections for iterative migration tend
> +to be open-coded by the devices;  care should be taken in parsing

Why the double space?


> +
> +The ``device data`` in each section consists of the data produced
> +by the code described above.  For non-iterative devices they have a single
> +section; iterative devices have an initial and last section and a set
> +of parts inbetween.

s/inbetween/in between/

> +Note that there is very little checking by the common code of the integrity
> +of the ``device data`` contents, that's upto the devices themselves.

s/upto/up to/

> +Only a unidirectional stream is required for normal migration, however a
> +``return path`` can be created when bidirecitonal communication is desired.

s/bidirecitonal/bidirectional/

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

signature.asc
Description: OpenPGP digital signature