[v4,for-2.11] QAPI & interop: Clarify events emitted by 'block-job-cancel'

When you cancel an in-progress 'mirror' job (or "active `block-commit`)
with QMP `block-job-cancel`, it emits the event: BLOCK_JOB_CANCELLED.
However, when `block-job-cancel` is issued *after* `drive-mirror` has
indicated (via the event BLOCK_JOB_READY) that the source and
destination have reached synchronization:

    [...] # Snip `drive-mirror` invocation & outputs
    {
      "execute":"block-job-cancel",
      "arguments":{
        "device":"virtio0"
      }
    }

    {"return": {}}

It (`block-job-cancel`) will counterintuitively emit the event
'BLOCK_JOB_COMPLETED':

    {
      "timestamp":{
        "seconds":1510678024,
        "microseconds":526240
      },
      "event":"BLOCK_JOB_COMPLETED",
      "data":{
        "device":"virtio0",
        "len":41126400,
        "offset":41126400,
        "speed":0,
        "type":"mirror"
      }
    }

But this is expected behaviour, where the _COMPLETED event indicates
that synchronization has successfully ended (and the destination now has
a point-in-time copy, which is at the time of cancel).

So add a small note to this effect in 'block-core.json'.  While at it,
also update the "Live disk synchronization -- drive-mirror and
blockdev-mirror" section in 'live-block-operations.rst'.

(Thanks: Max Reitz for reminding me of this caveat on IRC.)

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
Changes in v4:
 - Make the wording nicer [Eric Blake]

Changes in v3:
 - Fix / rewrite the section "Live disk synchronization -- drive-mirror
   and blockdev-mirror" to note this gotcha [John Snow]

Changes in v2:
 - "Note:" seems to be a special construct in Patchew, my usage caused a
    build failure.  So do: s/Note:/Note that/
 - Add the missing 'Signed-off-by'
---
 docs/interop/live-block-operations.rst | 50 ++++++++++++++++++++++------------
 qapi/block-core.json                   |  6 ++++
 2 files changed, 38 insertions(+), 18 deletions(-)

On Fri, Nov 17, 2017 at 07:54:44PM +0100, Kashyap Chamarthy wrote:
> When you cancel an in-progress 'mirror' job (or "active `block-commit`)

When applying, can the maintainer please fix-up the missing closing
double-quote in the brackets above?  It should be: "active
`block-commit`"

[...]

On Fri, Nov 17, 2017 at 07:54:44PM +0100, Kashyap Chamarthy wrote:

[...]

> +So there are two possible actions to take, after a 'mirror' job has
> +emitted the event ``BLOCK_JOB_READY``, indicating that the source and
> +target have reached synchronization:
> +
> +(1) Issuing the command ``block-job-cancel`` (after it emits the event
> +    ``BLOCK_JOB_COMPLETED``) will create a point-in-time (which is at
> +    the time of *triggering* the cancel command) copy of the entire disk
>      image chain (or only the top-most image, depending on the ``sync``
> -    mode).
> +    mode), contained in the target image [E].
>  
> -(2) Issuing the command ``block-job-complete`` after it emits the event
> -    ``BLOCK_JOB_COMPLETED``: will, after completing synchronization of
> -    the content, adjust the guest device (i.e. live QEMU) to point to
> -    the target image, and, causing all the new writes from this point on
> -    to happen there.  One use case for this is live storage migration.
> +(2) Issuing the command ``block-job-complete`` (after it emits the event
> +    ``BLOCK_JOB_COMPLETED``) will adjust the guest device (i.e. live
> +    QEMU) to point to the target image, [E], causing all the new writes
> +    from this point on to happen there.  One use case for this is live
> +    storage migration.

Dave Gilbert pointed out on IRC that last sentence ("One use case for
this is live storage migration") should apply to point (1) above.  He's
right, I'll send a v5 with that (and the commit message tweak I noted
earlier) fix.

[...]

Am 21.11.2017 um 10:58 hat Kashyap Chamarthy geschrieben:
> On Fri, Nov 17, 2017 at 07:54:44PM +0100, Kashyap Chamarthy wrote:
> > +So there are two possible actions to take, after a 'mirror' job has
> > +emitted the event ``BLOCK_JOB_READY``, indicating that the source and
> > +target have reached synchronization:
> > +
> > +(1) Issuing the command ``block-job-cancel`` (after it emits the event
> > +    ``BLOCK_JOB_COMPLETED``) will create a point-in-time (which is at
> > +    the time of *triggering* the cancel command) copy of the entire disk
> >      image chain (or only the top-most image, depending on the ``sync``
> > -    mode).
> > +    mode), contained in the target image [E].
> >  
> > -(2) Issuing the command ``block-job-complete`` after it emits the event
> > -    ``BLOCK_JOB_COMPLETED``: will, after completing synchronization of
> > -    the content, adjust the guest device (i.e. live QEMU) to point to
> > -    the target image, and, causing all the new writes from this point on
> > -    to happen there.  One use case for this is live storage migration.
> > +(2) Issuing the command ``block-job-complete`` (after it emits the event
> > +    ``BLOCK_JOB_COMPLETED``) will adjust the guest device (i.e. live
> > +    QEMU) to point to the target image, [E], causing all the new writes
> > +    from this point on to happen there.  One use case for this is live
> > +    storage migration.
> 
> Dave Gilbert pointed out on IRC that last sentence ("One use case for
> this is live storage migration") should apply to point (1) above.  He's
> right, I'll send a v5 with that (and the commit message tweak I noted
> earlier) fix.

This depends completely on what you mean by "live storage migration".
We've never been able to find a non-confusing terminology there.

What Dave is thinking of is probably "live VM migration with non-shared
storage". What the comment implied was probably "move an image somewhere
else while keeping the VM running where it is".

Maybe the best option would be to completely remove this sentence
instead of moving it to (1) where it's still ambiguous.

Kevin