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

[Peter Xu <peterx@redhat.com>]

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,

-- 
Peter Xu