docs: Document how to stream to an intermediate layer (1029641b) · Commits · SUMMER2020 / students / proj-2021291

docs/live-block-ops.txt

+25 −11

Original line number	Diff line number	Diff line
		@@ -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
		===============