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

[Stefan Hajnoczi <stefanha@gmail.com>]

Here is the latest interface, I'm not updating existing patches to
implement and test it (not yet using generic image stream):

http://wiki.qemu.org/Features/LiveBlockMigration/ImageStreamingAPI

=Changelog=
v2:
* Remove iteration interface where management tool drives individual
copy iterations
* Add block_stream_cancel command (like migrate_cancel)
* Add 'base' common backing file argument to block_stream
* Replace QError object in BLOCK_STREAM_COMPLETED with an error string
* Add error documentation

=Image streaming API=

The stream commands populate an image file by streaming data from its backing
file.  Once all blocks have been streamed, the dependency on the original
backing image is removed.  The stream commands can be used to implement
post-copy live block migration and rapid deployment.

The block_stream command starts streaming the image file.  When streaming
completes successfully or with an error, the BLOCK_STREAM_COMPLETED event is
raised.

The progress of a streaming operation can be polled using query-block-stream.
This returns information regarding how much of the image has been streamed.

The block_stream_cancel command stops streaming the image file.  The image file
retains its backing file.  A new streaming operation can be started at a later
time.

The command synopses are as follows:

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

 Copy data from a backing file into a block device.

 The block streaming operation is performed in the background until the entire
 backing file has been copied.  This command returns immediately once streaming
 has started.  The status of ongoing block streaming operations can be checked
 with query-block-stream.  The operation can be stopped before it has completed
 using the block_stream_cancel command.

 If a base file is specified then sectors are not copied from that base file and
 its backing chain.  When streaming completes the image file will have the base
 file as its backing file.  This can be used to stream a subset of the backing
 file chain instead of flattening the entire image.

 On successful completion the image file is updated to drop the backing file.

 Arguments:

 - device: device name (json-string)
 - base:   common backing file (json-string, optional)

 Errors:

 DeviceInUse:    streaming is already active on this device
 DeviceNotFound: device name is invalid
 NotSupported:   image streaming is not supported by this device

 Events:

 On completion the BLOCK_STREAM_COMPLETED event is raised with the following
 fields:

 - device: device name (json-string)
 - len:    size of the device, in bytes (json-int)
 - offset: last offset of completed I/O, in bytes (json-int)
 - error:  error message (json-string, only on error)

 The completion event is raised both on success and on failure.

 Examples:

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

 block_stream_cancel
 -------------------

 Stop an active block streaming operation.

 This command returns once the active block streaming operation has been
 stopped.  It is an error to call this command if no operation is in progress.

 The image file retains its backing file unless the streaming operation happens
 to complete just as it is being cancelled.

 A new block streaming operation can be started at a later time to finish
 copying all data from the backing file.

 Arguments:

 - device: device name (json-string)

 Errors:

 DeviceNotActive: streaming is not active on this device
 DeviceInUse:     cancellation already in progress

 Examples:

 -> { "execute": "block_stream_cancel", "arguments": { "device": "virtio0" } }
 <- { "return":  {} }

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

 Show progress of ongoing block_stream operations.

 Return a json-array of all block streaming operations.  If no operation is
 active then return an empty array.  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}
    ]
  }

=How live block copy works=

Live block copy does the following:

# Create and switch to the destination file: snapshot_blkdev
virtio-blk0 destination.$fmt $fmt
# Stream the base into the image file: block_stream -a virtio-blk0

Stefan