Re: [Qemu-devel] [PATCH v5 6/6] docs/interop: add nbd.txt

[Eric Blake <eblake@redhat.com>]

On 06/09/2018 10:17 AM, Vladimir Sementsov-Ogievskiy wrote:
> Describe new metadata namespace: "qemu".
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> ---
>   docs/interop/nbd.txt | 37 +++++++++++++++++++++++++++++++++++++
>   MAINTAINERS          |  1 +
>   2 files changed, 38 insertions(+)
>   create mode 100644 docs/interop/nbd.txt
> 
> diff --git a/docs/interop/nbd.txt b/docs/interop/nbd.txt
> new file mode 100644
> index 0000000000..7366269fc0
> --- /dev/null
> +++ b/docs/interop/nbd.txt
> @@ -0,0 +1,37 @@
> +Qemu supports NBD protocol, and has internal NBD client (look at

s/supports/supports the/

> +block/nbd.c), internal NBD server (look at blockdev-nbd.c) as well as

s/internal/an internal/2

> +external NBD server tool - qemu-nbd.c. The common code is placed in

s/external/an external/

> +nbd/*.
> +
> +NBD protocol is specified here:

s/NBD/The NBD/

> +https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
> +
> +This following paragraphs describe some specific properties of NBD
> +protocol realization in Qemu.
> +
> +
> += Metadata namespaces =
> +
> +Qemu supports "base:allocation" metadata context as defined in the NBD

s/supports/supports the/

> +protocol specification and defines own metadata namespace: "qemu".

s/own/an additional/

> +
> +
> +== "qemu" namespace ==
> +
> +For now, the only type of metadata context in the namespace is dirty
> +bitmap. All available metadata contexts have the following form:

maybe:

The "qemu" namespace currently contains only one type of context, 
related to exposing the contents of a dirty bitmap alongside the 
associated disk contents.  The available metadata context has the 
following form:

> +
> +   qemu:dirty-bitmap:<dirty-bitmap-export-name>
> +
> +Each dirty-bitmap metadata context defines the only one flag for
> +extents in reply for NBD_CMD_BLOCK_STATUS:
> +
> +    bit 0: NBD_STATE_DIRTY, means that the extent is "dirty"
> +
> +For NBD_OPT_LIST_META_CONTEXT the following queries are supported
> +additionally to "qemu:dirty-bitmap:<dirty-bitmap-export-name>":

s/additionally/in addition/

> +
> +* "qemu:" : returns list of all available metadata contexts in the
> +            namespace.
> +* "qemu:dirty-bitmap:" : returns list of all available dirty-bitmap
> +                         metadata contexts.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index e187b1f18f..887b479440 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1923,6 +1923,7 @@ F: nbd/
>   F: include/block/nbd*
>   F: qemu-nbd.*
>   F: blockdev-nbd.c
> +F: docs/interop/nbd.txt
>   T: git git://repo.or.cz/qemu/ericb.git nbd
>   
>   NFS
> 

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

At this point, I think I'll touch up the issues I've spotted and submit 
a pull request, in order to make it easier for me to test my libvirt code.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org