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

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

[Peter Xu]

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
+#     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:
 #
-- 
2.50.1

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

[Markus Armbruster]

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.

> +#     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"?

Remind me, how can migration get into and out of this state?

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

[Peter Xu]

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;
        }

> 
> 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,

-- 
Peter Xu

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

[Markus Armbruster]

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!

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

[Peter Xu]

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

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

[Markus Armbruster]

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>

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

[Peter Xu]

On Thu, Oct 23, 2025 at 07:20:38PM +0200, Markus Armbruster wrote:
> 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>

Rather than a new resend to bother everyone, I'll just queue it with the
amended version and the tag.. thanks Markus!

-- 
Peter Xu