The following changes since commit ca4e667dbf431d4a2a5a619cde79d30dd2ac3eb2:

Merge remote-tracking branch 'remotes/kraxel/tags/usb-20170717-pull-request' into staging (2017-07-17 17:54:17 +0100)

are available in the git repository at:

git://github.com/codyprime/qemu-kvm-jtc.git tags/block-pull-request

for you to fetch changes up to 8508eee740c78d1465e25dad7c3e06137485dfbc:

live-block-ops.txt: Rename, rewrite, and improve it (2017-07-18 00:11:01 -0400)

Block patches (documentation)

Kashyap Chamarthy (2):

bitmaps.md: Convert to rST; move it into 'interop' dir

live-block-ops.txt: Rename, rewrite, and improve it

docs/devel/bitmaps.md | 505 ---------------

docs/interop/bitmaps.rst | 555 ++++++++++++++++

docs/interop/live-block-operations.rst | 1088 ++++++++++++++++++++++++++++++++

docs/live-block-ops.txt | 72 ---

4 files changed, 1643 insertions(+), 577 deletions(-)

delete mode 100644 docs/devel/bitmaps.md

create mode 100644 docs/interop/bitmaps.rst

create mode 100644 docs/interop/live-block-operations.rst

delete mode 100644 docs/live-block-ops.txt

2.9.4

From: Kashyap Chamarthy <kchamart@redhat.com>

This patch documents (including their QMP invocations) all the four

major kinds of live block operations:

- `block-stream`

- `block-commit`

- `drive-mirror` (& `blockdev-mirror`)

- `drive-backup` (& `blockdev-backup`)

Things considered while writing this document:

- Use reStructuredText as markup language (with the goal of generating

the HTML output using the Sphinx Documentation Generator). It is

gentler on the eye, and can be trivially converted to different

formats. (Another reason: upstream QEMU is considering to switch to

Sphinx, which uses reStructuredText as its markup language.)

- Raw QMP JSON output vs. 'qmp-shell'. I debated with myself whether

to only show raw QMP JSON output (as that is the canonical

representation), or use 'qmp-shell', which takes key-value pairs. I

settled on the approach of: for the first occurrence of a command,

use raw JSON; for subsequent occurrences, use 'qmp-shell', with an

occasional exception.

- Usage of `-blockdev` command-line.

- Usage of 'node-name' vs. file path to refer to disks. While we have

`blockdev-{mirror, backup}` as 'node-name'-alternatives for

`drive-{mirror, backup}`, the `block-commit` command still operates

on file names for parameters 'base' and 'top'. So I added a caveat

at the beginning to that effect.

Refer this related thread that I started (where I learnt

`block-stream` was recently reworked to accept 'node-name' for 'top'

and 'base' parameters):

https://lists.nongnu.org/archive/html/qemu-devel/2017-05/msg06466.html

"[RFC] Making 'block-stream', and 'block-commit' accept node-name"

All commands showed in this document were tested while documenting.

Thanks: Eric Blake for the section: "A note on points-in-time vs file

names". This useful bit was originally articulated by Eric in his

KVMForum 2015 presentation, so I included that specific bit in this

document.

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>

Reviewed-by: Eric Blake <eblake@redhat.com>

Message-id: 20170717105205.32639-3-kchamart@redhat.com

Signed-off-by: Jeff Cody <jcody@redhat.com>

---

docs/interop/live-block-operations.rst | 1088 ++++++++++++++++++++++++++++++++

docs/live-block-ops.txt | 72 ---

2 files changed, 1088 insertions(+), 72 deletions(-)

create mode 100644 docs/interop/live-block-operations.rst

delete mode 100644 docs/live-block-ops.txt

diff --git a/docs/interop/live-block-operations.rst b/docs/interop/live-block-operations.rst

+++ b/docs/interop/live-block-operations.rst

+..

+ Copyright (C) 2017 Red Hat Inc.

+

+ This work is licensed under the terms of the GNU GPL, version 2 or

+ later. See the COPYING file in the top-level directory.

+

+============================

+Live Block Device Operations

+============================

+

+QEMU Block Layer currently (as of QEMU 2.9) supports four major kinds of

+live block device jobs -- stream, commit, mirror, and backup. These can

+be used to manipulate disk image chains to accomplish certain tasks,

+namely: live copy data from backing files into overlays; shorten long

+disk image chains by merging data from overlays into backing files; live

+synchronize data from a disk image chain (including current active disk)

+to another target image; and point-in-time (and incremental) backups of

+a block device. Below is a description of the said block (QMP)

+primitives, and some (non-exhaustive list of) examples to illustrate

+their use.

+

+.. note::

+ The file ``qapi/block-core.json`` in the QEMU source tree has the

+ canonical QEMU API (QAPI) schema documentation for the QMP

+ primitives discussed here.

+

+.. todo (kashyapc):: Remove the ".. contents::" directive when Sphinx is

+ integrated.

+

+.. contents::

+

+Disk image backing chain notation

+---------------------------------

+

+A simple disk image chain. (This can be created live using QMP

+``blockdev-snapshot-sync``, or offline via ``qemu-img``)::

+

+ (Live QEMU)

+ |

+ .

+ V

+

+ [A] <----- [B]

+

+ (backing file) (overlay)

+

+The arrow can be read as: Image [A] is the backing file of disk image

+[B]. And live QEMU is currently writing to image [B], consequently, it

+is also referred to as the "active layer".

+

+There are two kinds of terminology that are common when referring to

+files in a disk image backing chain:

+

+(1) Directional: 'base' and 'top'. Given the simple disk image chain

+ above, image [A] can be referred to as 'base', and image [B] as

+ 'top'. (This terminology can be seen in in QAPI schema file,

+ block-core.json.)

+

+(2) Relational: 'backing file' and 'overlay'. Again, taking the same

+ simple disk image chain from the above, disk image [A] is referred

+ to as the backing file, and image [B] as overlay.

+

+ Throughout this document, we will use the relational terminology.

+

+.. important::

+ The overlay files can generally be any format that supports a

+ backing file, although QCOW2 is the preferred format and the one

+ used in this document.

+

+

+Brief overview of live block QMP primitives

+The following are the four different kinds of live block operations that

+QEMU block layer supports.

+

+(1) ``block-stream``: Live copy of data from backing files into overlay

+ files.

+

+ .. note:: Once the 'stream' operation has finished, three things to

+ note:

+

+ (a) QEMU rewrites the backing chain to remove

+ reference to the now-streamed and redundant backing

+ file;

+

+ (b) the streamed file *itself* won't be removed by QEMU,

+ and must be explicitly discarded by the user;

+

+ (c) the streamed file remains valid -- i.e. further

+ overlays can be created based on it. Refer the

+ ``block-stream`` section further below for more

+ details.

+

+(2) ``block-commit``: Live merge of data from overlay files into backing

+ files (with the optional goal of removing the overlay file from the

+ chain). Since QEMU 2.0, this includes "active ``block-commit``"

+ (i.e. merge the current active layer into the base image).

+

+ .. note:: Once the 'commit' operation has finished, there are three

+ things to note here as well:

+

+ (a) QEMU rewrites the backing chain to remove reference

+ to now-redundant overlay images that have been

+ committed into a backing file;

+

+ (b) the committed file *itself* won't be removed by QEMU

+ -- it ought to be manually removed;

+

+ (c) however, unlike in the case of ``block-stream``, the

+ intermediate images will be rendered invalid -- i.e.

+ no more further overlays can be created based on

+ them. Refer the ``block-commit`` section further

+ below for more details.

+

+(3) ``drive-mirror`` (and ``blockdev-mirror``): Synchronize a running

+ disk to another image.

+

+(4) ``drive-backup`` (and ``blockdev-backup``): Point-in-time (live) copy

+ of a block device to a destination.

+

+

+.. _`Interacting with a QEMU instance`:

+

+Interacting with a QEMU instance

+--------------------------------

+

+To show some example invocations of command-line, we will use the

+following invocation of QEMU, with a QMP server running over UNIX

+socket::

+

+ $ ./x86_64-softmmu/qemu-system-x86_64 -display none -nodefconfig \

+ -M q35 -nodefaults -m 512 \

+ -blockdev node-name=node-A,driver=qcow2,file.driver=file,file.node-name=file,file.filename=./a.qcow2 \

+ -device virtio-blk,drive=node-A,id=virtio0 \

+ -monitor stdio -qmp unix:/tmp/qmp-sock,server,nowait

+

+The ``-blockdev`` command-line option, used above, is available from

+QEMU 2.9 onwards. In the above invocation, notice the ``node-name``

+parameter that is used to refer to the disk image a.qcow2 ('node-A') --

+this is a cleaner way to refer to a disk image (as opposed to referring

+to it by spelling out file paths). So, we will continue to designate a

+``node-name`` to each further disk image created (either via

+``blockdev-snapshot-sync``, or ``blockdev-add``) as part of the disk

+image chain, and continue to refer to the disks using their

+``node-name`` (where possible, because ``block-commit`` does not yet, as

+of QEMU 2.9, accept ``node-name`` parameter) when performing various

+block operations.

+

+To interact with the QEMU instance launched above, we will use the

+``qmp-shell`` utility (located at: ``qemu/scripts/qmp``, as part of the

+QEMU source directory), which takes key-value pairs for QMP commands.

+Invoke it as below (which will also print out the complete raw JSON

+syntax for reference -- examples in the following sections)::

+

+ $ ./qmp-shell -v -p /tmp/qmp-sock

+ (QEMU)

+

+.. note::

+ In the event we have to repeat a certain QMP command, we will: for

+ the first occurrence of it, show the ``qmp-shell`` invocation, *and*

+ the corresponding raw JSON QMP syntax; but for subsequent

+ invocations, present just the ``qmp-shell`` syntax, and omit the

+ equivalent JSON output.

+

+

+Example disk image chain

+------------------------

+

+We will use the below disk image chain (and occasionally spelling it

+out where appropriate) when discussing various primitives::

+

+ [A] <-- [B] <-- [C] <-- [D]

+

+Where [A] is the original base image; [B] and [C] are intermediate

+overlay images; image [D] is the active layer -- i.e. live QEMU is

+writing to it. (The rule of thumb is: live QEMU will always be pointing

+to the rightmost image in a disk image chain.)

+

+The above image chain can be created by invoking

+``blockdev-snapshot-sync`` commands as following (which shows the

+creation of overlay image [B]) using the ``qmp-shell`` (our invocation

+also prints the raw JSON invocation of it)::

+

+ (QEMU) blockdev-snapshot-sync node-name=node-A snapshot-file=b.qcow2 snapshot-node-name=node-B format=qcow2

+ {

+ "execute": "blockdev-snapshot-sync",

+ "arguments": {

+ "node-name": "node-A",

+ "snapshot-file": "b.qcow2",

+ "format": "qcow2",

+ "snapshot-node-name": "node-B"

+ }

+ }

+

+Here, "node-A" is the name QEMU internally uses to refer to the base

+image [A] -- it is the backing file, based on which the overlay image,

+[B], is created.

+

+To create the rest of the overlay images, [C], and [D] (omitting the raw

+JSON output for brevity)::

+

+ (QEMU) blockdev-snapshot-sync node-name=node-B snapshot-file=c.qcow2 snapshot-node-name=node-C format=qcow2

+ (QEMU) blockdev-snapshot-sync node-name=node-C snapshot-file=d.qcow2 snapshot-node-name=node-D format=qcow2

+

+

+A note on points-in-time vs file names

+--------------------------------------

+

+In our disk image chain::

+

+ [A] <-- [B] <-- [C] <-- [D]

+

+We have *three* points in time and an active layer:

+

+- Point 1: Guest state when [B] was created is contained in file [A]

+- Point 2: Guest state when [C] was created is contained in [A] + [B]

+- Point 3: Guest state when [D] was created is contained in

+ [A] + [B] + [C]

+- Active layer: Current guest state is contained in [A] + [B] + [C] +

+ [D]

+

+Therefore, be aware with naming choices:

+

+- Naming a file after the time it is created is misleading -- the

+ guest data for that point in time is *not* contained in that file

+ (as explained earlier)

+- Rather, think of files as a *delta* from the backing file

+

+

+Live block streaming --- ``block-stream``

+-----------------------------------------

+

+The ``block-stream`` command allows you to do live copy data from backing

+files into overlay images.

+

+Given our original example disk image chain from earlier::

+

+ [A] <-- [B] <-- [C] <-- [D]

+

+The disk image chain can be shortened in one of the following different

+ways (not an exhaustive list).

+

+.. _`Case-1`:

+

+(1) Merge everything into the active layer: I.e. copy all contents from

+ the base image, [A], and overlay images, [B] and [C], into [D],

+ *while* the guest is running. The resulting chain will be a

+ standalone image, [D] -- with contents from [A], [B] and [C] merged

+ into it (where live QEMU writes go to)::

+

+ [D]

+

+.. _`Case-2`:

+

+(2) Taking the same example disk image chain mentioned earlier, merge

+ only images [B] and [C] into [D], the active layer. The result will

+ be contents of images [B] and [C] will be copied into [D], and the

+ backing file pointer of image [D] will be adjusted to point to image

+ [A]. The resulting chain will be::

+

+ [A] <-- [D]

+

+.. _`Case-3`:

+

+(3) Intermediate streaming (available since QEMU 2.8): Starting afresh

+ with the original example disk image chain, with a total of four

+ images, it is possible to copy contents from image [B] into image

+ [C]. Once the copy is finished, image [B] can now be (optionally)

+ discarded; and the backing file pointer of image [C] will be

+ adjusted to point to [A]. I.e. after performing "intermediate

+ streaming" of [B] into [C], the resulting image chain will be (where

+ live QEMU is writing to [D])::

+

+ [A] <-- [C] <-- [D]

+

+

+QMP invocation for ``block-stream``

+For `Case-1`_, to merge contents of all the backing files into the

+active layer, where 'node-D' is the current active image (by default

+``block-stream`` will flatten the entire chain); ``qmp-shell`` (and its

+corresponding JSON output)::

+

+ (QEMU) block-stream device=node-D job-id=job0

+ {

+ "execute": "block-stream",

+ "arguments": {

+ "device": "node-D",

+ "job-id": "job0"

+ }

+ }

+

+For `Case-2`_, merge contents of the images [B] and [C] into [D], where

+image [D] ends up referring to image [A] as its backing file::

+

+ (QEMU) block-stream device=node-D base-node=node-A job-id=job0

+

+And for `Case-3`_, of "intermediate" streaming", merge contents of

+images [B] into [C], where [C] ends up referring to [A] as its backing

+image::

+

+ (QEMU) block-stream device=node-C base-node=node-A job-id=job0

+

+Progress of a ``block-stream`` operation can be monitored via the QMP

+command::

+

+ (QEMU) query-block-jobs

+ {

+ "execute": "query-block-jobs",

+ "arguments": {}

+ }

+

+

+Once the ``block-stream`` operation has completed, QEMU will emit an

+event, ``BLOCK_JOB_COMPLETED``. The intermediate overlays remain valid,

+and can now be (optionally) discarded, or retained to create further

+overlays based on them. Finally, the ``block-stream`` jobs can be

+restarted at anytime.

+

+

+Live block commit --- ``block-commit``

+--------------------------------------

+

+The ``block-commit`` command lets you merge live data from overlay

+images into backing file(s). Since QEMU 2.0, this includes "live active

+commit" (i.e. it is possible to merge the "active layer", the right-most

+image in a disk image chain where live QEMU will be writing to, into the

+base image). This is analogous to ``block-stream``, but in the opposite

+direction.

+

+Again, starting afresh with our example disk image chain, where live

+QEMU is writing to the right-most image in the chain, [D]::

+

+ [A] <-- [B] <-- [C] <-- [D]

+

+The disk image chain can be shortened in one of the following ways:

+

+.. _`block-commit_Case-1`:

+

+(1) Commit content from only image [B] into image [A]. The resulting

+ chain is the following, where image [C] is adjusted to point at [A]

+ as its new backing file::

+

+ [A] <-- [C] <-- [D]

+

+(2) Commit content from images [B] and [C] into image [A]. The

+ resulting chain, where image [D] is adjusted to point to image [A]

+ as its new backing file::

+

+ [A] <-- [D]

+

+.. _`block-commit_Case-3`:

+

+(3) Commit content from images [B], [C], and the active layer [D] into

+ image [A]. The resulting chain (in this case, a consolidated single

+ image)::

+

+ [A]

+

+(4) Commit content from image only image [C] into image [B]. The

+ resulting chain::

+

+    [A] <-- [B] <-- [D]

+

+(5) Commit content from image [C] and the active layer [D] into image

+ [B]. The resulting chain::

+

+    [A] <-- [B]

+

+

+QMP invocation for ``block-commit``

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+For :ref:`Case-1 <block-commit_Case-1>`, to merge contents only from

+image [B] into image [A], the invocation is as follows::

+

+ (QEMU) block-commit device=node-D base=a.qcow2 top=b.qcow2 job-id=job0

+ {

+ "execute": "block-commit",

+ "arguments": {

+ "device": "node-D",

+ "job-id": "job0",

+ "top": "b.qcow2",

+ "base": "a.qcow2"

+ }

+ }

+

+Once the above ``block-commit`` operation has completed, a

+``BLOCK_JOB_COMPLETED`` event will be issued, and no further action is

+required. As the end result, the backing file of image [C] is adjusted

+to point to image [A], and the original 4-image chain will end up being

+transformed to::

+

+ [A] <-- [C] <-- [D]

+

+.. note::

+ The intermediate image [B] is invalid (as in: no more further

+ overlays based on it can be created).

+

+ Reasoning: An intermediate image after a 'stream' operation still

+ represents that old point-in-time, and may be valid in that context.

+ However, an intermediate image after a 'commit' operation no longer

+ represents any point-in-time, and is invalid in any context.

+

+

+However, :ref:`Case-3 <block-commit_Case-3>` (also called: "active

+``block-commit``") is a *two-phase* operation: In the first phase, the

+content from the active overlay, along with the intermediate overlays,

+is copied into the backing file (also called the base image). In the

+second phase, adjust the said backing file as the current active image

+-- possible via issuing the command ``block-job-complete``. Optionally,

+the ``block-commit`` operation can be cancelled by issuing the command

+``block-job-cancel``, but be careful when doing this.

+

+Once the ``block-commit`` operation has completed, the event

+``BLOCK_JOB_READY`` will be emitted, signalling that the synchronization

+has finished. Now the job can be gracefully completed by issuing the

+command ``block-job-complete`` -- until such a command is issued, the

+'commit' operation remains active.

+

+The following is the flow for :ref:`Case-3 <block-commit_Case-3>` to

+convert a disk image chain such as this::

+

+ [A] <-- [B] <-- [C] <-- [D]

+

+Into::

+

+ [A]

+

+Where content from all the subsequent overlays, [B], and [C], including

+the active layer, [D], is committed back to [A] -- which is where live

+QEMU is performing all its current writes).

+

+Start the "active ``block-commit``" operation::

+

+ (QEMU) block-commit device=node-D base=a.qcow2 top=d.qcow2 job-id=job0

+ {

+ "execute": "block-commit",

+ "arguments": {

+ "device": "node-D",

+ "job-id": "job0",

+ "top": "d.qcow2",

+ "base": "a.qcow2"

+ }

+ }

+

+

+Once the synchronization has completed, the event ``BLOCK_JOB_READY`` will

+be emitted.

+

+Then, optionally query for the status of the active block operations.

+We can see the 'commit' job is now ready to be completed, as indicated

+by the line *"ready": true*::

+

+ (QEMU) query-block-jobs

+ {

+ "execute": "query-block-jobs",

+ "arguments": {}

+ }

+ {

+ "return": [

+ {

+ "busy": false,

+ "type": "commit",

+ "len": 1376256,

+ "paused": false,

+ "ready": true,

+ "io-status": "ok",

+ "offset": 1376256,

+ "device": "job0",

+ "speed": 0

+ }

+ ]

+ }

+

+Gracefully complete the 'commit' block device job::

+

+ (QEMU) block-job-complete device=job0

+ {

+ "execute": "block-job-complete",

+ "arguments": {

+ "device": "job0"

+ }

+ }

+ {

+ "return": {}

+ }

+

+Finally, once the above job is completed, an event

+``BLOCK_JOB_COMPLETED`` will be emitted.

+

+.. note::

+ The invocation for rest of the cases (2, 4, and 5), discussed in the

+ previous section, is omitted for brevity.

+

+

+Live disk synchronization --- ``drive-mirror`` and ``blockdev-mirror``

+----------------------------------------------------------------------

+

+Synchronize a running disk image chain (all or part of it) to a target

+image.

+

+Again, given our familiar disk image chain::

+

+ [A] <-- [B] <-- [C] <-- [D]

+

+The ``drive-mirror`` (and its newer equivalent ``blockdev-mirror``) allows

+you to copy data from the entire chain into a single target image (which

+can be located on a different host).

+

+Once a 'mirror' job has started, there are two possible actions while a

+``drive-mirror`` job is active:

+

+(1) Issuing the command ``block-job-cancel`` after it emits the event

+ ``BLOCK_JOB_CANCELLED``: will (after completing synchronization of

+ the content from the disk image chain to the target image, [E])

+ create a point-in-time (which is at the time of *triggering* the

+ cancel command) copy, contained in image [E], of the the entire disk

+ image chain (or only the top-most image, depending on the ``sync``

+ mode).

+

+(2) Issuing the command ``block-job-complete`` after it emits the event

+ ``BLOCK_JOB_COMPLETED``: will, after completing synchronization of

+ the content, adjust the guest device (i.e. live QEMU) to point to

+ the target image, and, causing all the new writes from this point on

+ to happen there. One use case for this is live storage migration.

+

+About synchronization modes: The synchronization mode determines

+*which* part of the disk image chain will be copied to the target.

+Currently, there are four different kinds:

+

+(1) ``full`` -- Synchronize the content of entire disk image chain to

+ the target

+

+(2) ``top`` -- Synchronize only the contents of the top-most disk image

+ in the chain to the target

+

+(3) ``none`` -- Synchronize only the new writes from this point on.

+

+ .. note:: In the case of ``drive-backup`` (or ``blockdev-backup``),

+ the behavior of ``none`` synchronization mode is different.

+ Normally, a ``backup`` job consists of two parts: Anything

+ that is overwritten by the guest is first copied out to

+ the backup, and in the background the whole image is

+ copied from start to end. With ``sync=none``, it's only

+ the first part.

+

+(4) ``incremental`` -- Synchronize content that is described by the

+ dirty bitmap

+

+.. note::

+ Refer to the :doc:`bitmaps` document in the QEMU source

+ tree to learn about the detailed workings of the ``incremental``

+ synchronization mode.

+

+

+QMP invocation for ``drive-mirror``

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+To copy the contents of the entire disk image chain, from [A] all the

+way to [D], to a new target (``drive-mirror`` will create the destination

+file, if it doesn't already exist), call it [E]::

+

+ (QEMU) drive-mirror device=node-D target=e.qcow2 sync=full job-id=job0

+ {

+ "execute": "drive-mirror",

+ "arguments": {

+ "device": "node-D",

+ "job-id": "job0",

+ "target": "e.qcow2",

+ "sync": "full"

+ }

+ }

+

+The ``"sync": "full"``, from the above, means: copy the *entire* chain

+to the destination.

+

+Following the above, querying for active block jobs will show that a

+'mirror' job is "ready" to be completed (and QEMU will also emit an

+event, ``BLOCK_JOB_READY``)::

+

+ (QEMU) query-block-jobs

+ {

+ "execute": "query-block-jobs",

+ "arguments": {}

+ }

+ {

+ "return": [

+ {

+ "busy": false,

+ "type": "mirror",

+ "len": 21757952,

+ "paused": false,

+ "ready": true,

+ "io-status": "ok",

+ "offset": 21757952,

+ "device": "job0",

+ "speed": 0

+ }

+ ]

+ }

+

+And, as noted in the previous section, there are two possible actions

+at this point:

+

+(a) Create a point-in-time snapshot by ending the synchronization. The

+ point-in-time is at the time of *ending* the sync. (The result of

+ the following being: the target image, [E], will be populated with

+ content from the entire chain, [A] to [D])::

+

+ (QEMU) block-job-cancel device=job0

+ {

+ "execute": "block-job-cancel",

+ "arguments": {

+ "device": "job0"

+ }

+ }

+

+(b) Or, complete the operation and pivot the live QEMU to the target

+ copy::

+

+ (QEMU) block-job-complete device=job0

+

+In either of the above cases, if you once again run the

+`query-block-jobs` command, there should not be any active block

+operation.