docs, qapi: document qemu-img map

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>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
This commit is contained in:
Paolo Bonzini 2013-09-04 19:00:34 +02:00 committed by Stefan Hajnoczi
parent 4c93a13b5d
commit facd6e2b5c
2 changed files with 84 additions and 0 deletions

View File

@ -830,6 +830,35 @@
##
{ 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] }
##
# @BlockDeviceMapEntry:
#
# Entry in the metadata map of the device (returned by "qemu-img map")
#
# @start: Offset in the image of the first byte described by this entry
# (in bytes)
#
# @length: Length of the range described by this entry (in bytes)
#
# @depth: Number of layers (0 = top image, 1 = top image's backing file, etc.)
# before reaching one for which the range is allocated. The value is
# in the range 0 to the depth of the image chain - 1.
#
# @zero: the sectors in this range read as zeros
#
# @data: reading the image will actually read data from a file (in particular,
# if @offset is present this means that the sectors are not simply
# preallocated, but contain actual data in raw format)
#
# @offset: if present, the image file stores the data for this range in
# raw format at the given offset.
#
# Since 1.7
##
{ 'type': 'BlockDeviceMapEntry',
'data': { 'start': 'int', 'length': 'int', 'depth': 'int', 'zero': 'bool',
'data': 'bool', '*offset': 'int' } }
##
# @BlockDirtyInfo:
#

View File

@ -226,6 +226,61 @@ To enumerate information about each disk image in the above chain, starting from
qemu-img info --backing-chain snap2.qcow2
@end example
@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
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, the first three of which are hexadecimal
numbers. For example the first line of:
@example
Offset Length Mapped to File
0 0x20000 0x50000 /tmp/overlay.qcow2
0x100000 0x10000 0x95380000 /tmp/backing.qcow2
@end example
@noindent
means that 0x20000 (131072) bytes starting at offset 0 in the image are
available in /tmp/overlay.qcow2 (opened in @code{raw} format) starting
at offset 0x50000 (327680). Data that is compressed, encrypted, or
otherwise not available in raw format will cause an error if @code{human}
format is in use. Note that file names can include newlines, thus it is
not safe to parse this output format in scripts.
The alternative format @code{json} will return an array of dictionaries
in JSON format. It will include similar information in
the @code{start}, @code{length}, @code{offset} fields;
it will also include other more specific information:
@itemize @minus
@item
whether the sectors contain actual data or not (boolean field @code{data};
if false, the sectors are either unallocated or stored as optimized
all-zero clusters);
@item
whether the data is known to read as zero (boolean field @code{zero});
@item
in order to make the output shorter, the target file is expressed as
a @code{depth}; for example, a depth of 2 refers to the backing file
of the backing file of @var{filename}.
@end itemize
In JSON format, the @code{offset} field is optional; it is absent in
cases where @code{human} format would omit the entry or exit with an error.
If @code{data} is false and the @code{offset} field is present, the
corresponding sectors in the file are not yet in use, but they are
preallocated.
For more information, consult @file{include/block/block.h} in QEMU's
source code.
@item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
List, apply, create or delete snapshots in image @var{filename}.