On Tue, 01/21 11:31, Jeff Cody wrote:
> 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 <jc...@redhat.com>
> ---
> 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..1f83099 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..848f81c 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?,"
> --
> 1.8.3.1
>
Reviewed-by: Fam Zheng <f...@redhat.com>
