Re: [PATCH V4 13/14] migration: update cpr-reboot description

[Markus Armbruster <armbru@redhat.com>]

Steve Sistare <steven.sistare@oracle.com> writes:

> Clarify qapi for cpr-reboot migration mode, and add vfio support.

The patch only affects documentation, but that's less than clear from
the commit message.  Suggest

  Improve documentation for migration mode @cpr-reboot.  In particular,
  document VFIO support.

> Signed-off-by: Steve Sistare <steven.sistare@oracle.com>
> ---
>  qapi/migration.json | 35 ++++++++++++++++++++++-------------
>  1 file changed, 22 insertions(+), 13 deletions(-)
>
> diff --git a/qapi/migration.json b/qapi/migration.json
> index 5a565d9..0990297 100644
> --- a/qapi/migration.json
> +++ b/qapi/migration.json
> @@ -636,19 +636,28 @@
>  #
>  # @normal: the original form of migration. (since 8.2)
>  #
> -# @cpr-reboot: The migrate command saves state to a file, allowing one to
> -#              quit qemu, reboot to an updated kernel, and restart an updated
> -#              version of qemu.  The caller must specify a migration URI
> -#              that writes to and reads from a file.  Unlike normal mode,
> -#              the use of certain local storage options does not block the
> -#              migration, but the caller must not modify guest block devices
> -#              between the quit and restart.  To avoid saving guest RAM to the
> -#              file, the memory backend must be shared, and the @x-ignore-shared
> -#              migration capability must be set.  Guest RAM must be non-volatile
> -#              across reboot, such as by backing it with a dax device, but this
> -#              is not enforced.  The restarted qemu arguments must match those
> -#              used to initially start qemu, plus the -incoming option.
> -#              (since 8.2)
> +# @cpr-reboot: The migrate command stops the VM and saves state to the URI.
> +#     After quitting qemu, the user resumes by running qemu -incoming.

These two sentences apply to any migration mode, don't they?  Just
checking I understand.

> +#
> +#     This mode allows the user to quit qemu, and restart an updated version
> +#     of qemu.  The user may even update and reboot the OS before restarting,
> +#     as long as the URI persists across a reboot.

Hmm, doesn't normal migration also support migrating to a newer QEMU?

> +#
> +#     Unlike normal mode, the use of certain local storage options does not
> +#     block the migration, but the user must not modify guest block devices
> +#     between the quit and restart.

"Must not modify the contents of the guest block devices"?

> +#
> +#     This mode supports vfio devices provided the user first puts the guest

"VFIO devices"

> +#     in the suspended runstate, such as by issuing guest-suspend-ram to the
> +#     qemu guest agent.
> +#
> +#     Best performance is achieved when the memory backend is shared and the
> +#     @x-ignore-shared migration capability is set, but this is not required.
> +#     Further, if the user reboots before restarting such a configuration, the
> +#     shared backend must be be non-volatile across reboot, such as by backing

Typo: "be be non-volatile"

Suggest "the shared memory must persist"

> +#     it with a dax device.
> +#
> +#     (since 8.2)
>  ##
>  { 'enum': 'MigMode',
>    'data': [ 'normal', 'cpr-reboot' ] }

Thanks for adjusting indentation to conform to conventions.  Please
additionally reflow the text to limit line length to 70 characters.