From patchwork Fri Jan 24 14:02:37 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jeff Cody X-Patchwork-Id: 313904 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)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 10EBD2C009C for ; Sat, 25 Jan 2014 01:03:41 +1100 (EST) Received: from localhost ([::1]:46728 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W6hMA-0008TJ-Sw for incoming@patchwork.ozlabs.org; Fri, 24 Jan 2014 09:03:38 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54901) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W6hLT-0008ML-Lv for qemu-devel@nongnu.org; Fri, 24 Jan 2014 09:03:01 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1W6hLN-0007Tv-NL for qemu-devel@nongnu.org; Fri, 24 Jan 2014 09:02:55 -0500 Received: from mx1.redhat.com ([209.132.183.28]:24329) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W6hLN-0007Tr-F4 for qemu-devel@nongnu.org; Fri, 24 Jan 2014 09:02:49 -0500 Received: from int-mx12.intmail.prod.int.phx2.redhat.com (int-mx12.intmail.prod.int.phx2.redhat.com [10.5.11.25]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s0OE2l5h021687 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 24 Jan 2014 09:02:47 -0500 Received: from localhost (ovpn-112-40.phx2.redhat.com [10.3.112.40]) by int-mx12.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s0OE2j1Y006788 (version=TLSv1/SSLv3 cipher=AES128-SHA bits=128 verify=NO); Fri, 24 Jan 2014 09:02:46 -0500 From: Jeff Cody To: qemu-devel@nongnu.org Date: Fri, 24 Jan 2014 09:02:37 -0500 Message-Id: In-Reply-To: References: In-Reply-To: References: X-Scanned-By: MIMEDefang 2.68 on 10.5.11.25 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 209.132.183.28 Cc: kwolf@redhat.com, benoit.canet@irqsave.net, famz@redhat.com, stefanha@redhat.com Subject: [Qemu-devel] [PATCH v5 3/3] block: update block commit documentation regarding image truncation 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 This updates the documentation for commiting snapshot images. Specifically, this highlights what happens when the base image is either smaller or larger than the snapshot image being committed. In the case of the base image being smaller, it is resized to the larger size of the snapshot image. In the case of the base image being larger, it is not resized automatically, but once the commit has completed it is safe for the user to truncate the base image. Signed-off-by: Jeff Cody Reviewed-by: Fam Zheng Reviewed-by: Eric Blake --- hmp-commands.hx | 5 +++++ qapi-schema.json | 7 +++++++ qemu-img.texi | 7 ++++++- qmp-commands.hx | 39 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 57 insertions(+), 1 deletion(-) diff --git a/hmp-commands.hx b/hmp-commands.hx index feca084..f3fc514 100644 --- a/hmp-commands.hx +++ b/hmp-commands.hx @@ -35,6 +35,11 @@ STEXI @item commit @findex commit Commit changes to the disk images (if -snapshot is used) or backing files. +If the backing file is smaller than the snapshot, then the backing file will be +resized to be the same size as the snapshot. If the snapshot is smaller than +the backing file, the backing file will not be truncated. If you want the +backing file to match the size of the smaller snapshot, you can safely truncate +it yourself once the commit operation successfully completes. ETEXI { diff --git a/qapi-schema.json b/qapi-schema.json index f27c48a..64a108b 100644 --- a/qapi-schema.json +++ b/qapi-schema.json @@ -1973,6 +1973,13 @@ # user needs to complete the job with the block-job-complete # command after getting the ready event. (Since 2.0) # +# If the base image is smaller than top, then the base image +# will be resized to be the same size as top. If top is +# smaller than the base image, the base will not be +# truncated. If you want the base image size to match the +# size of the smaller top, you can safely truncate it +# yourself once the commit operation successfully completes. +# # # @speed: #optional the maximum speed, in bytes per second # diff --git a/qemu-img.texi b/qemu-img.texi index 1bba91e..22556df 100644 --- a/qemu-img.texi +++ b/qemu-img.texi @@ -140,7 +140,12 @@ it doesn't need to be specified separately in this case. @item commit [-f @var{fmt}] [-t @var{cache}] @var{filename} -Commit the changes recorded in @var{filename} in its base image. +Commit the changes recorded in @var{filename} in its base image or backing file. +If the backing file is smaller than the snapshot, then the backing file will be +resized to be the same size as the snapshot. If the snapshot is smaller than +the backing file, the backing file will not be truncated. If you want the +backing file to match the size of the smaller snapshot, you can safely truncate +it yourself once the commit operation successfully completes. @item compare [-f @var{fmt}] [-F @var{fmt}] [-p] [-s] [-q] @var{filename1} @var{filename2} diff --git a/qmp-commands.hx b/qmp-commands.hx index 02cc815..d7ed5ba 100644 --- a/qmp-commands.hx +++ b/qmp-commands.hx @@ -965,6 +965,45 @@ EQMP .mhandler.cmd_new = qmp_marshal_input_block_commit, }, +SQMP +block-commit +------------ + +Live commit of data from overlay image nodes into backing nodes - i.e., writes +data between 'top' and 'base' into 'base'. + +Arguments: + +- "device": The device's ID, must be unique (json-string) +- "base": The file name of the backing image to write data into. + If not specified, this is the deepest backing image + (json-string, optional) +- "top": The file name of the backing image within the image chain, + which contains the topmost data to be committed down. + + If top == base, that is an error. + If top == active, the job will not be completed by itself, + user needs to complete the job with the block-job-complete + command after getting the ready event. (Since 2.0) + + If the base image is smaller than top, then the base image + will be resized to be the same size as top. If top is + smaller than the base image, the base will not be + truncated. If you want the base image size to match the + size of the smaller top, you can safely truncate it + yourself once the commit operation successfully completes. + (json-string) +- "speed": the maximum speed, in bytes per second (json-int, optional) + + +Example: + +-> { "execute": "block-commit", "arguments": { "device": "virtio0", + "top": "/tmp/snap1.qcow2" } } +<- { "return": {} } + +EQMP + { .name = "drive-backup", .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"