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>
