Re: [Qemu-devel] [PATCH v2 3/3] block: update block commit documentation regarding image truncation

[Fam Zheng <famz@redhat.com>]

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 <jcody@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 <famz@redhat.com>