| Message ID | 1374762197-7261-15-git-send-email-pbonzini@redhat.com |
|---|---|
| State | New |
| Headers | show |
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.
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Il 30/07/2013 17:48, Eric Blake ha scritto: > 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? On first error. The reason is that usually everything will be encrypted (in the common case where you have encryption but no backing files), and it would be a waste of time to walk the whole image. Paolo > 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. -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQIcBAEBAgAGBQJR9+GyAAoJEBvWZb6bTYbycHkQAJ4vGYkpxvCMRbJcgAL4UgTM 0gxYOeUjz2CsxkbTn+gYN6hYyuAreuIDWiuQ4nlS573CIXaZXUiCw4iuIZItgUuU gD2l9/PMz2GdeJk7rP7XaybRh5FUsKjbxXcWMSz5lSvIw4QYD0a0xe+GUZCUJ+Yj sbw4EWmWsp/fQftm0HIeU/UdZ2S+frMw7owsxRrbLVnf5tCLGAp+iHmMMu1Jtz97 f6z5ijvXia+q0JUF4ui1zosCybLNJ7yiG63TLdu/Pk1NymBMNAAIkLbzSRrR/xoc un0IHG1aIrTldmaoJL0SfdkHWP2f7jzfNuhODptVWk8XnJIK+bpSbF1KjfJ6irrE VjfxFbJN/V8f7tJf3Ck3SUHMzQSsHMTtG5IwD//au1ppb467j96OXAOUftxY4s8A 10C0e2jVPeTmbJxOkN3rQFwhYVhYre2sd0VfSbZqHw/FDkcpHqlMCsu6BqNy5iHI WiTNMS9KP7hNGVD7JHOTnCUmeVfBQXCqL6QMr8Da5cJxbBIQ36XDep/Gr1Qd593P BNs74MT80H4xpdwl+bBK8WHpzmD6+o0PlhpbxZq5abji8WitgvcPRM9v7ydq/d77 qGJ8JcfNmY7hlqU/Cwom3WP6Wdv+sayojZJ1aI4TXTuXVzGzlqck+KSspv7sTTwE eRwSQdD1/81OpppvIy+R =sVYH -----END PGP SIGNATURE-----
diff --git a/qapi-schema.json b/qapi-schema.json index 592bb9c..421ea8a 100644 --- a/qapi-schema.json +++ 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") +# +# @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.6 +## +{ 'type': 'BlockDeviceMapEntry', + 'data': { 'start': 'int', 'length': 'int', 'depth': 'int', 'zero': 'bool', + 'data': 'bool', '*offset': 'int' } } + +## # @BlockDirtyInfo: # # Block dirty bitmap information. diff --git a/qemu-img.texi b/qemu-img.texi index 69f1bda..43f0b31 100644 --- a/qemu-img.texi +++ b/qemu-img.texi @@ -213,6 +213,52 @@ 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; 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. + +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{depth}, @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}); +@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}.
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(+)