Blame SOURCES/kvm-block-update-block-commit-documentation-regarding-im.patch

0a122b
From c7c21ebc0dcddd666c616e161b0f9bbb4ade9cf4 Mon Sep 17 00:00:00 2001
0a122b
From: Jeffrey Cody <jcody@redhat.com>
0a122b
Date: Tue, 11 Feb 2014 16:14:27 +0100
0a122b
Subject: [PATCH 21/28] block: update block commit documentation regarding image truncation
0a122b
0a122b
RH-Author: Jeffrey Cody <jcody@redhat.com>
0a122b
Message-id: <d4d68c21d4b8936f3bcdc442abe0425e01352167.1392134912.git.jcody@redhat.com>
0a122b
Patchwork-id: 57217
0a122b
O-Subject: [RHEL7 qemu-kvm PATCH 3/6] block: update block commit documentation regarding image truncation
0a122b
Bugzilla: 1047254
0a122b
RH-Acked-by: Kevin Wolf <kwolf@redhat.com>
0a122b
RH-Acked-by: Markus Armbruster <armbru@redhat.com>
0a122b
RH-Acked-by: Miroslav Rezanina <mrezanin@redhat.com>
0a122b
0a122b
This updates the documentation for commiting snapshot images.
0a122b
Specifically, this highlights what happens when the base image
0a122b
is either smaller or larger than the snapshot image being committed.
0a122b
0a122b
In the case of the base image being smaller, it is resized to the
0a122b
larger size of the snapshot image.  In the case of the base image
0a122b
being larger, it is not resized automatically, but once the commit
0a122b
has completed it is safe for the user to truncate the base image.
0a122b
0a122b
Signed-off-by: Jeff Cody <jcody@redhat.com>
0a122b
Reviewed-by: Fam Zheng <famz@redhat.com>
0a122b
Reviewed-by: Eric Blake <eblake@redhat.com>
0a122b
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
0a122b
(cherry picked from commit 37222900743962e146a82b7077a18c3f39859a19)
0a122b
0a122b
Conflicts:
0a122b
	qmp-commands.hx
0a122b
0a122b
RHEL7 Notes: Conflict is due to 2 things: 1) drive-backup
0a122b
             not present in RHEL7, and 2) the block job
0a122b
             differentiation #ifdefs.
0a122b
---
0a122b
 hmp-commands.hx  |  5 +++++
0a122b
 qapi-schema.json |  7 +++++++
0a122b
 qemu-img.texi    |  7 ++++++-
0a122b
 qmp-commands.hx  | 40 ++++++++++++++++++++++++++++++++++++++++
0a122b
 4 files changed, 58 insertions(+), 1 deletion(-)
0a122b
0a122b
Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>
0a122b
---
0a122b
 hmp-commands.hx  |    5 +++++
0a122b
 qapi-schema.json |    7 +++++++
0a122b
 qemu-img.texi    |    7 ++++++-
0a122b
 qmp-commands.hx  |   40 ++++++++++++++++++++++++++++++++++++++++
0a122b
 4 files changed, 58 insertions(+), 1 deletions(-)
0a122b
0a122b
diff --git a/hmp-commands.hx b/hmp-commands.hx
0a122b
index 8e08ebf..467dd70 100644
0a122b
--- a/hmp-commands.hx
0a122b
+++ b/hmp-commands.hx
0a122b
@@ -35,6 +35,11 @@ STEXI
0a122b
 @item commit
0a122b
 @findex commit
0a122b
 Commit changes to the disk images (if -snapshot is used) or backing files.
0a122b
+If the backing file is smaller than the snapshot, then the backing file will be
0a122b
+resized to be the same size as the snapshot.  If the snapshot is smaller than
0a122b
+the backing file, the backing file will not be truncated.  If you want the
0a122b
+backing file to match the size of the smaller snapshot, you can safely truncate
0a122b
+it yourself once the commit operation successfully completes.
0a122b
 ETEXI
0a122b
 
0a122b
     {
0a122b
diff --git a/qapi-schema.json b/qapi-schema.json
0a122b
index 8b257e2..017b3b7 100644
0a122b
--- a/qapi-schema.json
0a122b
+++ b/qapi-schema.json
0a122b
@@ -1846,6 +1846,13 @@
0a122b
 #                    user needs to complete the job with the block-job-complete
0a122b
 #                    command after getting the ready event. (Since 2.0)
0a122b
 #
0a122b
+#                    If the base image is smaller than top, then the base image
0a122b
+#                    will be resized to be the same size as top.  If top is
0a122b
+#                    smaller than the base image, the base will not be
0a122b
+#                    truncated.  If you want the base image size to match the
0a122b
+#                    size of the smaller top, you can safely truncate it
0a122b
+#                    yourself once the commit operation successfully completes.
0a122b
+#
0a122b
 #
0a122b
 # @speed:  #optional the maximum speed, in bytes per second
0a122b
 #
0a122b
diff --git a/qemu-img.texi b/qemu-img.texi
0a122b
index 1078791..d75a780 100644
0a122b
--- a/qemu-img.texi
0a122b
+++ b/qemu-img.texi
0a122b
@@ -136,7 +136,12 @@ it doesn't need to be specified separately in this case.
0a122b
 
0a122b
 @item commit [-f @var{fmt}] [-t @var{cache}] @var{filename}
0a122b
 
0a122b
-Commit the changes recorded in @var{filename} in its base image.
0a122b
+Commit the changes recorded in @var{filename} in its base image or backing file.
0a122b
+If the backing file is smaller than the snapshot, then the backing file will be
0a122b
+resized to be the same size as the snapshot.  If the snapshot is smaller than
0a122b
+the backing file, the backing file will not be truncated.  If you want the
0a122b
+backing file to match the size of the smaller snapshot, you can safely truncate
0a122b
+it yourself once the commit operation successfully completes.
0a122b
 
0a122b
 @item compare [-f @var{fmt}] [-F @var{fmt}] [-p] [-s] [-q] @var{filename1} @var{filename2}
0a122b
 
0a122b
diff --git a/qmp-commands.hx b/qmp-commands.hx
0a122b
index 7a1bfd4..08a01ee 100644
0a122b
--- a/qmp-commands.hx
0a122b
+++ b/qmp-commands.hx
0a122b
@@ -1008,6 +1008,46 @@ EQMP
0a122b
         .args_type  = "device:B,base:s?,top:s,speed:o?",
0a122b
         .mhandler.cmd_new = qmp_marshal_input_block_commit,
0a122b
     },
0a122b
+
0a122b
+SQMP
0a122b
+block-commit
0a122b
+------------
0a122b
+
0a122b
+Live commit of data from overlay image nodes into backing nodes - i.e., writes
0a122b
+data between 'top' and 'base' into 'base'.
0a122b
+
0a122b
+Arguments:
0a122b
+
0a122b
+- "device": The device's ID, must be unique (json-string)
0a122b
+- "base": The file name of the backing image to write data into.
0a122b
+          If not specified, this is the deepest backing image
0a122b
+          (json-string, optional)
0a122b
+- "top":  The file name of the backing image within the image chain,
0a122b
+          which contains the topmost data to be committed down.
0a122b
+
0a122b
+          If top == base, that is an error.
0a122b
+          If top == active, the job will not be completed by itself,
0a122b
+          user needs to complete the job with the block-job-complete
0a122b
+          command after getting the ready event. (Since 2.0)
0a122b
+
0a122b
+          If the base image is smaller than top, then the base image
0a122b
+          will be resized to be the same size as top.  If top is
0a122b
+          smaller than the base image, the base will not be
0a122b
+          truncated.  If you want the base image size to match the
0a122b
+          size of the smaller top, you can safely truncate it
0a122b
+          yourself once the commit operation successfully completes.
0a122b
+          (json-string)
0a122b
+- "speed":  the maximum speed, in bytes per second (json-int, optional)
0a122b
+
0a122b
+
0a122b
+Example:
0a122b
+
0a122b
+-> { "execute": "block-commit", "arguments": { "device": "virtio0",
0a122b
+                                              "top": "/tmp/snap1.qcow2" } }
0a122b
+<- { "return": {} }
0a122b
+
0a122b
+EQMP
0a122b
+
0a122b
 #endif
0a122b
 
0a122b
     {
0a122b
-- 
0a122b
1.7.1
0a122b