[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PULL 63/93] block: update block commit documentation regar
From: |
Kevin Wolf |
Subject: |
[Qemu-devel] [PULL 63/93] block: update block commit documentation regarding image truncation |
Date: |
Fri, 24 Jan 2014 18:21:46 +0100 |
From: Jeff Cody <address@hidden>
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 <address@hidden>
Reviewed-by: Fam Zheng <address@hidden>
Reviewed-by: Eric Blake <address@hidden>
Signed-off-by: Kevin Wolf <address@hidden>
---
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 e04949d..1ff607a 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1994,6 +1994,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 f86a86d..526d56a 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -142,7 +142,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 4f28250..cce6b81 100644
--- a/qmp-commands.hx
+++ b/qmp-commands.hx
@@ -966,6 +966,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?,"
--
1.8.1.4
- [Qemu-devel] [PULL 49/93] sheepdog: fix 'qemu-img map', (continued)
- [Qemu-devel] [PULL 49/93] sheepdog: fix 'qemu-img map', Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 48/93] Documentation: qemu-img: Mention SIGUSR1 progress report, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 51/93] vmdk: Fix format specific information (create type) for streamOptimized, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 50/93] drive mirror:fix memory leak, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 52/93] qapi: Add "backing" to BlockStats, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 54/93] block: Allow the user to define "node-name" option both on command line and QMP., Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 53/93] block: Add bs->node_name to hold the name of a bs node of the bs graph., Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 61/93] block: resize backing file image during offline commit, if necessary, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 62/93] block: resize backing image during active layer commit, if needed, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 64/93] block: Fix bdrv_commit return value, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 63/93] block: update block commit documentation regarding image truncation,
Kevin Wolf <=
- [Qemu-devel] [PULL 65/93] block: Move initialisation of BlockLimits to bdrv_refresh_limits(), Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 66/93] block: Inherit opt_transfer_length, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 68/93] qemu_memalign: Allow small alignments, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 67/93] block: Update BlockLimits when they might have changed, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 69/93] block: Detect unaligned length in bdrv_qiov_is_aligned(), Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 70/93] block: Don't use guest sector size for qemu_blockalign(), Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 71/93] block: rename buffer_alignment to guest_block_size, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 72/93] raw: Probe required direct I/O alignment, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 76/93] block: write: Handle COR dependency after I/O throttling, Kevin Wolf, 2014/01/24
- [Qemu-devel] [PULL 77/93] block: Introduce bdrv_co_do_pwritev(), Kevin Wolf, 2014/01/24