diff options
Diffstat (limited to 'qapi')
| -rw-r--r-- | qapi/block-core.json | 58 |
1 files changed, 34 insertions, 24 deletions
diff --git a/qapi/block-core.json b/qapi/block-core.json index c5ac22d246..2d94873ca0 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1569,6 +1569,18 @@ # Live commit of data from overlay image nodes into backing nodes - i.e., # writes data between 'top' and 'base' into 'base'. # +# If top == base, that is an error. +# If top has no overlays on top of it, or if it is in use by a writer, +# the job will not be completed by itself. The 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. +# # @job-id: identifier for the newly-created block job. If # omitted, the device name will be used. (Since 2.7) # @@ -1593,14 +1605,15 @@ # accepted # # @backing-file: The backing file string to write into the overlay -# image of 'top'. If 'top' is the active layer, -# specifying a backing file string is an error. This -# filename is not validated. +# image of 'top'. If 'top' does not have an overlay +# image, or if 'top' is in use by a writer, specifying +# a backing file string is an error. # -# If a pathname string is such that it cannot be -# resolved by QEMU, that means that subsequent QMP or -# HMP commands must use node-names for the image in -# question, as filename lookup methods will fail. +# This filename is not validated. If a pathname string +# is such that it cannot be resolved by QEMU, that +# means that subsequent QMP or HMP commands must use +# node-names for the image in question, as filename +# lookup methods will fail. # # If not specified, QEMU will automatically determine # the backing file string to use, or error out if @@ -1609,18 +1622,6 @@ # filename or protocol. # (Since 2.1) # -# 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. -# # @speed: the maximum speed, in bytes per second # # @on-error: the action to take on an error. 'ignore' means that the request @@ -1948,7 +1949,8 @@ # # @replaces: with sync=full graph node name to be replaced by the new # image when a whole image copy is done. This can be used to repair -# broken Quorum files. (Since 2.1) +# broken Quorum files. By default, @device is replaced, although +# implicitly created filters on it are kept. (Since 2.1) # # @mode: whether and how QEMU should create a new image, default is # 'absolute-paths'. @@ -2259,7 +2261,8 @@ # # @replaces: with sync=full graph node name to be replaced by the new # image when a whole image copy is done. This can be used to repair -# broken Quorum files. +# broken Quorum files. By default, @device is replaced, although +# implicitly created filters on it are kept. # # @speed: the maximum speed, in bytes per second # @@ -2484,13 +2487,20 @@ # of 'device'. # # If a base file is specified then sectors are not copied from that base file and -# its backing chain. When streaming completes the image file will have the base -# file as its backing file. This can be used to stream a subset of the backing -# file chain instead of flattening the entire image. +# its backing chain. This can be used to stream a subset of the backing file +# chain instead of flattening the entire image. +# When streaming completes the image file will have the base file as its backing +# file, unless that node was changed while the job was running. In that case, +# base's parent's backing (or filtered, whichever exists) child (i.e., base at +# the beginning of the job) will be the new backing file. # # On successful completion the image file is updated to drop the backing file # and the BLOCK_JOB_COMPLETED event is emitted. # +# In case @device is a filter node, block-stream modifies the first non-filter +# overlay node below it to point to the new backing node instead of modifying +# @device itself. +# # @job-id: identifier for the newly-created block job. If # omitted, the device name will be used. (Since 2.7) # |