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

[Dr. David Alan Gilbert]

* Eric Blake (address@hidden) wrote:
> On 04/27/2018 12:34 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 | 531 +++++++++++++++++++++++++++------------
> >  1 file changed, 375 insertions(+), 156 deletions(-)
> 
> > +
> > +General advice for device developers
> > +------------------------------------
> > +
> > +- The migration state saved should reflect the device being modelled rather
> > +  than the way your implementation works.   That way if you change the 
> > implementation
> 
> Three spaces between sentences is unusual.
> 

Fixed.

> > +
> > +- The migration might happen at an inconvenient point,
> > +  e.g. right in the middle of the guest reprogramming the device, during
> > +  guest reboot or shutdown or while the device is waiting for external IO.
> > +  It's strongly preferred that migrations do not fail in this situation,
> > +  since in the cloud environment migrations might happen automatically to
> > +  VMs that the administrator doesn't directly control.
> 
> Not for this patch, but is there any mechanism for a device to request
> that migration be delayed just long enough for the device to have a
> chance to get out of that inconsistent state, rather than having to
> migrate the inconvenient state?

Not generally no;  for an iterative device you can lie and say you've
still got data to migrate but it gets very messy.
For a non-iterative device it's too late, the CPU is already paused and
you're expected to stream the device state.

> > +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
> 
> Sometimes

Done.

> 
> > @@ -328,9 +329,12 @@ 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 
> > backwards migration compatibility.
> > +  - making them version dependent and bumping the version will break 
> > backward migration compatibility.
> 
> Is it worth worrying about long lines?

I'm not too bothered, but I've wrapped this one.

Dave

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



--
Dr. David Alan Gilbert / address@hidden / Manchester, UK