From patchwork Thu Aug 29 14:00:17 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 270844 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id EADAF2C007C for ; Fri, 30 Aug 2013 00:09:03 +1000 (EST) Received: from localhost ([::1]:43642 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VF2uE-0000hM-1J for incoming@patchwork.ozlabs.org; Thu, 29 Aug 2013 10:09:02 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54136) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VF2mk-0007I8-L4 for qemu-devel@nongnu.org; Thu, 29 Aug 2013 10:01:27 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VF2mc-0008D3-6a for qemu-devel@nongnu.org; Thu, 29 Aug 2013 10:01:18 -0400 Received: from mail-ee0-x236.google.com ([2a00:1450:4013:c00::236]:52693) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VF2mb-0008Cs-Sw for qemu-devel@nongnu.org; Thu, 29 Aug 2013 10:01:10 -0400 Received: by mail-ee0-f54.google.com with SMTP id e53so265432eek.41 for ; Thu, 29 Aug 2013 07:01:09 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references; bh=ePh0oaN6Et+ylbo42x6ta/izkMDUa9g4UcbdvQZx3Zo=; b=UWfMxx2mDfzaT7XknVPZvHe9NPDbfojdX9PH9IcKMZmpa8iLRdlMFQXLiT+02u3roR lqk2eviNtoqccFRq240Fg/x80DYYLcmizvgZnqXKdx8i2Z6osKSkvisGYya0Y7A54Z04 NaVT5WbkmjWy/GHyMEoBckJ7Rk7CihceIUYPg/o77pWWa1qYaeoYXx0E+DMDcd0v8PeO PS8UFoUmkeZ+uQk+/2g7ox6jOgeLVi5bKfnyuKuxvsQVIYe1jTeVJsrB4KtHBzXTmW9a Dy1NPLpaJt2j/poNTKcLoszyaWFqdrDW6r9lw4TQgb8odDwDwHbxcBJl7Ee3gBdwT0AE gqMw== X-Received: by 10.15.101.195 with SMTP id bp43mr3525956eeb.70.1377784868889; Thu, 29 Aug 2013 07:01:08 -0700 (PDT) Received: from yakj.usersys.redhat.com (nat-pool-mxp-t.redhat.com. [209.132.186.18]) by mx.google.com with ESMTPSA id p5sm46359028eeg.5.1969.12.31.16.00.00 (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Thu, 29 Aug 2013 07:01:07 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Date: Thu, 29 Aug 2013 16:00:17 +0200 Message-Id: <1377784821-29561-18-git-send-email-pbonzini@redhat.com> X-Mailer: git-send-email 1.8.3.1 In-Reply-To: <1377784821-29561-1-git-send-email-pbonzini@redhat.com> References: <1377784821-29561-1-git-send-email-pbonzini@redhat.com> X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2a00:1450:4013:c00::236 Cc: kwolf@redhat.com, stefanha@redhat.com Subject: [Qemu-devel] [PATCH v4 17/21] docs, qapi: document qemu-img map X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org 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 Reviewed-by: Eric Blake --- qapi-schema.json | 29 +++++++++++++++++++++++++++++ qemu-img.texi | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+) diff --git a/qapi-schema.json b/qapi-schema.json index a51f7d2..979f0c1 100644 --- a/qapi-schema.json +++ b/qapi-schema.json @@ -813,6 +813,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..8364fa1 100644 --- a/qemu-img.texi +++ b/qemu-img.texi @@ -213,6 +213,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}.