Re: [Qemu-devel] [PATCH v3 14/19] docs, qapi: document qemu-img map

[Eric Blake <eblake@redhat.com>]

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

On 07/25/2013 08:23 AM, Paolo Bonzini wrote:
> Eric Blake also requested including the output in qapi-schema.json,
> so that it is published through the introspection mechanism.
> 
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>  qapi-schema.json | 29 +++++++++++++++++++++++++++++
>  qemu-img.texi    | 46 ++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 75 insertions(+)
> 

> +++ b/qapi-schema.json
> @@ -803,6 +803,35 @@
>  { 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] }
>  
>  ##
> +# @BlockDeviceMapEntry:
> +#
> +# Entry in the metadata map of the device (returned by "qemu-img map")

Thanks for also referencing where this type is relevant (if we later add
a QMP command that also exposes the map via this type, we would remove
the parenthetical comment at that time).

> +#
> +# Since 1.6

Are we still shooting for 1.6, or has this missed the freeze?

>  
> +@item map [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}
> +
> +Dump the metadata of image @var{filename} and its backing file chain.
> +In particular, this commands dumps the allocation state of every sector

s/commands/command/

> +of @var{filename}, together with the topmost file that allocates it in
> +the backing file chain.
> +
> +Two option formats are possible.  The default format (@code{human})
> +only dumps known-nonzero areas of the file.  Known-zero parts of the
> +file are omitted altogether, and likewise for parts that are not allocated
> +throughout the chain.  @command{qemu-img} output will identify a file
> +from where the data can be read, and the offset in the file.  Each line
> +will include four fields; for example:
> +@example
> +0       131072       2        327680
> +@end example
> +@noindent
> +means that 131072 bytes starting at offset 0 in the image are available at
> +depth 2 (i.e. by opening in @code{raw} format the backing file of the
> +backing file of @var{filename}) starting at offset 327680.  Data that
> +is compressed, encrypted, or otherwise not available in raw format will
> +cause an error if @code{human} format is in use.

In case of a hybrid file (part raw, part encrypted), does this command
exit on first error, or only after printing as much raw information was
available?  That is, even if we can't describe the entire allocation
map, it may still be useful to dump as much information as possible
before declaring that more data is inaccessible via raw mapping.

-- 
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: 621 bytes --]