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 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)'

>> Remind me, how can migration get into and out of this state?
>
> It can happen if any interruption happened during a postcopy migration.  So
> it needs to be postcopy-active state first, then something wrong happened
> e.g. the network is down.  Then the channel will break on both sides of
> QEMU, and both QEMUs will jump into postcopy-paused.
>
> To get out of the state, one needs to explicitly recover the migration, the
> core steps are:
>
>   - (optional) Run migrate_recover on dest QEMU to re-establish the ports,
>     if the old listening ports are not available anymore.
>
>   - Run migrate on src QEMU with resume=true flag here to resume the
>     postcopy migration.
>
> If the recover succeeded, it'll switch from postcopy-paused finally back to
> postcopy-active.
>
> Thanks,

Got it, thanks!