From 1029641bef0899ea95bbdf651c77e7856cdcbe37 Mon Sep 17 00:00:00 2001 From: Alberto Garcia Date: Fri, 28 Oct 2016 10:08:12 +0300 Subject: docs: Document how to stream to an intermediate layer Signed-off-by: Alberto Garcia Reviewed-by: Kevin Wolf Signed-off-by: Kevin Wolf --- docs/live-block-ops.txt | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/live-block-ops.txt b/docs/live-block-ops.txt index a257087..2211d14 100644 --- a/docs/live-block-ops.txt +++ b/docs/live-block-ops.txt @@ -4,15 +4,20 @@ LIVE BLOCK OPERATIONS High level description of live block operations. Note these are not supported for use with the raw format at the moment. +Note also that this document is incomplete and it currently only +covers the 'stream' operation. Other operations supported by QEMU such +as 'commit', 'mirror' and 'backup' are not described here yet. Please +refer to the qapi/block-core.json file for an overview of those. + Snapshot live merge =================== Given a snapshot chain, described in this document in the following format: -[A] -> [B] -> [C] -> [D] +[A] <- [B] <- [C] <- [D] <- [E] -Where the rightmost object ([D] in the example) described is the current +Where the rightmost object ([E] in the example) described is the current image which the guest OS has write access to. To the left of it is its base image, and so on accordingly until the leftmost image, which has no base. @@ -21,11 +26,14 @@ The snapshot live merge operation transforms such a chain into a smaller one with fewer elements, such as this transformation relative to the first example: -[A] -> [D] +[A] <- [E] + +Data is copied in the right direction with destination being the +rightmost image, but any other intermediate image can be specified +instead. In this example data is copied from [C] into [D], so [D] can +be backed by [B]: -Currently only forward merge with target being the active image is -supported, that is, data copy is performed in the right direction with -destination being the rightmost image. +[A] <- [B] <- [D] <- [E] The operation is implemented in QEMU through image streaming facilities. @@ -35,14 +43,20 @@ streaming operation completes it raises a QMP event. 'block_stream' copies data from the backing file(s) into the active image. When finished, it adjusts the backing file pointer. -The 'base' parameter specifies an image which data need not be streamed from. -This image will be used as the backing file for the active image when the -operation is finished. +The 'base' parameter specifies an image which data need not be +streamed from. This image will be used as the backing file for the +destination image when the operation is finished. + +In the first example above, the command would be: + +(qemu) block_stream virtio0 file-A.img -In the example above, the command would be: +In order to specify a destination image different from the active +(rightmost) one we can use its node name instead. -(qemu) block_stream virtio0 A +In the second example above, the command would be: +(qemu) block_stream node-D file-B.img Live block copy =============== -- cgit v1.1 From 312fe09cc8af86c25a0c17162539589121e7d9a9 Mon Sep 17 00:00:00 2001 From: Alberto Garcia Date: Fri, 28 Oct 2016 10:08:19 +0300 Subject: block: Add 'base-node' parameter to the 'block-stream' command The way to specify the node from which to copy data in the block-stream operation is by using the 'base' parameter. This parameter however takes a file name, not a node name. Since we want to be able to perform this operation using only node names, this patch adds a new 'base-node' parameter. Signed-off-by: Alberto Garcia Reviewed-by: Kevin Wolf Signed-off-by: Kevin Wolf --- docs/qmp-commands.txt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt index a4732a5..6afa872 100644 --- a/docs/qmp-commands.txt +++ b/docs/qmp-commands.txt @@ -750,8 +750,11 @@ Arguments: - "job-id": Identifier for the newly-created block job. If omitted, the device name will be used. (json-string, optional) - "device": The device name or node-name of a root node (json-string) -- "base": The file name of the backing image above which copying starts - (json-string, optional) +- "base": The file name of the backing image above which copying starts. + It cannot be set if 'base-node' is also set (json-string, optional) +- "base-node": the node name of the backing image above which copying starts. + It cannot be set if 'base' is also set. + (json-string, optional) (Since 2.8) - "backing-file": The backing file string to write into the active layer. This filename is not validated. -- cgit v1.1