Re: [PATCH] migration/qmp: Update "resume" flag doc in "migrate" command

[Markus Armbruster <armbru@redhat.com>]

Peter Xu <peterx@redhat.com> writes:

> On Thu, Oct 23, 2025 at 04:04:40PM +0200, Markus Armbruster wrote:
>> Peter Xu <peterx@redhat.com> writes:
>> 
>> > On Thu, Oct 23, 2025 at 07:47:11AM +0200, Markus Armbruster wrote:
>> >> Peter Xu <peterx@redhat.com> writes:
>> >> 
>> >> > It wasn't obvious how the resume flag should be used when staring at the
>> >> > QAPI doc.  Enrich it to be crystal clear.
>> >> >
>> >> > Reported-by: Markus Armbruster <armbru@redhat.com>
>> >> > Signed-off-by: Peter Xu <peterx@redhat.com>
>> >> > ---
>> >> >  qapi/migration.json | 5 ++++-
>> >> >  1 file changed, 4 insertions(+), 1 deletion(-)
>> >> >
>> >> > diff --git a/qapi/migration.json b/qapi/migration.json
>> >> > index be0f3fcc12..48856078db 100644
>> >> > --- a/qapi/migration.json
>> >> > +++ b/qapi/migration.json
>> >> > @@ -1732,7 +1732,10 @@
>> >> >  # @detach: this argument exists only for compatibility reasons and is
>> >> >  #     ignored by QEMU
>> >> >  #
>> >> > -# @resume: resume one paused migration, default "off".  (since 3.0)
>> >> > +# @resume: when set, resume one paused postcopy migration, using the new
>> >> 
>> >> Scratch "one" unless there can be more than one.
>> >
>> > Sure.
>> >
>> >> 
>> >> > +#     URI/channels specified to replace the old/broken channels.  The user
>> >> > +#     should make sure the migration is in "postcopy-paused" state before
>> >> > +#     the resume request.  Default "off".  (since 3.0)
>> >> >  #
>> >> >  # Features:
>> >> >  #
>> >> 
>> >> What happens when migration is not in state "postcopy-paused"?
>> >
>> > The QMP command "migrate" with resume=true set will be rejected,
>> > corresponds to:
>> >
>> > migrate_prepare():
>> >         if (s->state != MIGRATION_STATUS_POSTCOPY_PAUSED) {
>> >             error_setg(errp, "Cannot resume if there is no "
>> >                        "paused migration");
>> >             return false;
>> >         }
>> 
>> Makes sense, thanks!
>> 
>> I'd suggest something like 'Resume fails unless migration is in
>> "postcopy-paused" state.  (default: false, since 3.0)'
>
> Since it's still a "migrate" QMP command, should I use "the command will
> fail"? I also re-arranged the words slightly.. would below look a better
> next version as a whole?
>
> # @resume: when set, use the new uri/channels specified to resume paused
> #     postcopy migration.  This flag should only be used if the previous
> #     postcopy migration was interrupted.  The command will fail unless
> #     migration is in "postcopy-paused" state.  (default: false, since 3.0)
>
> Thanks,

I like it.

Reviewed-by: Markus Armbruster <armbru@redhat.com>