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

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2564 bytes --]

On 04/16/2015 09:12 AM, Alberto Garcia wrote:
> Signed-off-by: Alberto Garcia <berto@igalia.com>
> ---
>  docs/live-block-ops.txt | 30 +++++++++++++++++++-----------
>  1 file changed, 19 insertions(+), 11 deletions(-)
> 
> diff --git a/docs/live-block-ops.txt b/docs/live-block-ops.txt
> index a257087..3bf86be 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]

I think on the list we've mostly settled on a notation where we express
this relation as:

[A] <- [B]

that is, the symbol "<-" makes more sense as "serves as a backing file
of" than "->", so that you end up reading the relationship as "[A]
serves as a backing of [B]" (or read right-to-left as "[B] has a backing
file of [A]").

Of course, the direction of the arrows is pre-existing, so it doesn't
hold up this patch, but we probably ought to scrub our examples to
consistently use <-.

>  
> -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,11 +21,13 @@ 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, for instance from [B] into [D]:
> +
> +[A] -> [B] -> [D] -> [E]

Should you really describe that as moving data from [B] into [D], or
would it be better to describe it as moving the data from [C] into [D]
such that [D] can now be backed by [B] instead of [C]?

I don't know if it is worth a tweak, and modulo my question on this one
sentence, I think you've done a good job documenting the feature
addition, so:

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]