Re: [Qemu-devel] [Qemu-block] [PATCH 6/6] docs: Document how to stream to an intermediate layer

[Max Reitz <mreitz@redhat.com>]

On 08.04.2015 16:43, Alberto Garcia wrote:
> Signed-off-by: Alberto Garcia <berto@igalia.com>
> ---
>   docs/live-block-ops.txt | 32 ++++++++++++++++++++------------
>   1 file changed, 20 insertions(+), 12 deletions(-)
>
> diff --git a/docs/live-block-ops.txt b/docs/live-block-ops.txt
> index a257087..5e969fd 100644
> --- a/docs/live-block-ops.txt
> +++ b/docs/live-block-ops.txt
> @@ -10,9 +10,9 @@ Snapshot live merge
>   Given a snapshot chain, described in this document in the following
>   format:
>   
> -[A] -> [B] -> [C] -> [D]
> +[A] -> [B] -> [C] -> [D] -> [E]
>   
> -Where the rightmost object ([D] in the example) described is the current
> +Where the rightmost object ([E] in the example) described is the current
>   image which the guest OS has write access to. To the left of it is its base
>   image, and so on accordingly until the leftmost image, which has no
>   base.
> @@ -21,28 +21,36 @@ The snapshot live merge operation transforms such a chain into a
>   smaller one with fewer elements, such as this transformation relative
>   to the first example:
>   
> -[A] -> [D]
> +[A] -> [E]
>   
> -Currently only forward merge with target being the active image is
> -supported, that is, data copy is performed in the right direction with
> -destination being the rightmost image.
> +Data is copied in the right direction with destination being the
> +rightmost image, but any other intermediate image can be specified
> +instead, [D] in this example:

"for instance from [B] into/to [D]"?

> +
> +[A] -> [B] -> [D] -> [E]
>   
>   The operation is implemented in QEMU through image streaming facilities.
>   
>   The basic idea is to execute 'block_stream virtio0' while the guest is
>   running. Progress can be monitored using 'info block-jobs'. When the
>   streaming operation completes it raises a QMP event. 'block_stream'
> -copies data from the backing file(s) into the active image. When finished,
> -it adjusts the backing file pointer.
> +copies data from the backing file(s) into the destination image.
> +When finished, it adjusts the backing file pointer.

Well, the example given here ("block_stream virtio0") would actually 
copy the data into the active image. It's not that "destination image" 
is wrong, but in this case, it really is the active image, so I don't 
think this change is necessary.

> -The 'base' parameter specifies an image which data need not be streamed from.
> -This image will be used as the backing file for the active image when the
> -operation is finished.
> +The 'base' parameter specifies an image which data need not be
> +streamed from. This image will be used as the backing file for the
> +destination image when the operation is finished.

Here, the change is fine, because this paragraph is detached from the 
example (which does not make use of the @base parameter).

>   
> -In the example above, the command would be:
> +In the first example above, the command would be:
>   
>   (qemu) block_stream virtio0 A

I'd like it if you could change the "A" to "A-filename", "filename-A", 
or something like that, to make clear it's a filename and not a node 
name. (I'd personally expect a node name, but I guess block-stream is 
simply older than node names are).

> +In order to specify a destination image different from the active
> +(rightmost) one we can use its (previously set) node name instead.
> +
> +In the second example above, the command would be:
> +
> +(qemu) block_stream node-D A

Hm, wouldn't this yield the chain "A -> D -> E" instead of "A -> B -> D 
-> E"?

Max

>   
>   Live block copy
>   ===============