Re: [Qemu-devel] live block copy/stream/snapshot discussion

[Stefan Hajnoczi]

Kevin, Marcelo,
I'd like to reach agreement on the QMP/HMP APIs for live block copy
and image streaming.  Libvirt has acked the image streaming APIs that
Adam proposed and I think they are a good fit for the feature.  I have
described that API below for your review (it's exactly what the QED
Image Streaming patches provide).

Marcelo: Are you happy with this API for live block copy?  Also please
take a look at the switch command that I am proposing.

Image streaming API
===================

For leaf images with copy-on-read semantics, the stream commands allow the user
to populate local blocks by manually streaming them from the backing image.
Once all blocks have been streamed, the dependency on the original backing
image can be removed.  Therefore, stream commands can be used to implement
post-copy live block migration and rapid deployment.

The block_stream command can be used to stream a single cluster, to
start streaming the entire device, and to cancel an active stream.  It
is easiest to allow the block_stream command to manage streaming for the
entire device but a managent tool could use single cluster mode to
throttle the I/O rate.

The command synopses are as follows:

block_stream
------------

Copy data from a backing file into a block device.

If the optional 'all' argument is true, this operation is performed in the
background until the entire backing file has been copied.  The status of
ongoing block_stream operations can be checked with query-block-stream.

Arguments:

- all:    copy entire device (json-bool, optional)
- stop:   stop copying to device (json-bool, optional)
- device: device name (json-string)

Return:

- device: device name (json-string)
- len:    size of the device, in bytes (json-int)
- offset: ending offset of the completed I/O, in bytes (json-int)

Examples:

-> { "execute": "block_stream", "arguments": { "device": "virtio0" } }
<- { "return":  { "device": "virtio0", "len": 10737418240, "offset": 512 } }

-> { "execute": "block_stream", "arguments": { "all": true, "device":
"virtio0" } }
<- { "return": {} }

-> { "execute": "block_stream", "arguments": { "stop": true, "device":
"virtio0" } }
<- { "return": {} }

query-block-stream
------------------

Show progress of ongoing block_stream operations.

Return a json-array of all operations.  If no operation is active then an empty
array will be returned.  Each operation is a json-object with the following
data:

- device: device name (json-string)
- len:    size of the device, in bytes (json-int)
- offset: ending offset of the completed I/O, in bytes (json-int)

Example:

-> { "execute": "query-block-stream" }
<- { "return":[
       { "device": "virtio0", "len": 10737418240, "offset": 709632}
    ]
  }


Block device switching API
==========================

Extend the 'change' command to support changing the image file without
media change notification.

Perhaps we should take the opportunity to add a "format" argument for
image files?

change
------

Change a removable medium or VNC configuration.

Arguments:

- "device": device name (json-string)
- "target": filename or item (json-string)
- "arg": additional argument (json-string, optional)
- "notify": whether to notify guest, defaults to true (json-bool, optional)

Examples:

1. Change a removable medium

-> { "execute": "change",
             "arguments": { "device": "ide1-cd0",
                            "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
<- { "return": {} }

2. Change a disk without media change notification

-> { "execute": "change",
             "arguments": { "device": "virtio-blk0",
                            "target": "/srv/images/vm_1.img",
                            "notify": false } }

3. Change VNC password

-> { "execute": "change",
             "arguments": { "device": "vnc", "target": "password",
                            "arg": "foobar1" } }
<- { "return": {} }

How live block copy works
=========================

Live block copy does the following:

1. Create the destination file: qemu-img create -f $cow_fmt -o
backing_file=$base destination.$cow_fmt
2. Switch to the destination file: change -n virtio-blk0 /srv/images/vm_1.img
3. Stream the base into the image file: block_stream -a virtio-blk0

Stefan