qemu-e2k/docs
Kashyap Chamarthy 8508eee740 live-block-ops.txt: Rename, rewrite, and improve it
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>
2017-07-18 00:11:01 -04:00
..
config docs: create config/, devel/ and spin/ subdirectories 2017-06-07 18:22:03 +02:00
devel bitmaps.md: Convert to rST; move it into 'interop' dir 2017-07-18 00:11:01 -04:00
interop live-block-ops.txt: Rename, rewrite, and improve it 2017-07-18 00:11:01 -04:00
specs docs: create interop/ subdirectory 2017-06-15 11:18:39 +02:00
spin docs: create config/, devel/ and spin/ subdirectories 2017-06-07 18:22:03 +02:00
block-replication.txt docs: block replication's description 2016-09-13 11:00:56 +01:00
bootindex.txt docs qemu-doc: Avoid ide-drive, it's deprecated 2017-06-04 18:42:55 +03:00
ccid.txt
COLO-FT.txt docs: fix COLO architecture diagram 2016-11-15 15:36:21 +08:00
colo-proxy.txt docs: Fix description of the sentence 2017-01-20 10:36:38 +08:00
generic-loader.txt docs/generic-loader: Update the document 2016-10-17 19:22:16 +01:00
igd-assign.txt
image-fuzzer.txt
memory-hotplug.txt
multi-thread-compression.txt
multiseat.txt
nvdimm.txt docs: add document to explain the usage of vNVDIMM 2017-02-17 21:52:30 +02:00
pci_expander_bridge.txt
pcie.txt doc/pcie: correct command line examples 2017-01-10 07:02:52 +02:00
qcow2-cache.txt docs: Specify that cache-clean-interval is only supported in Linux 2016-11-25 13:51:31 +01:00
qdev-device-use.txt docs/qdev-device-use.txt: update section Default Devices 2017-06-04 18:42:55 +03:00
qemu_logo.pdf docs: add qemu logo to pdf 2017-01-16 10:11:43 +01:00
qemupciserial.inf
rdma.txt
replay.txt replay: add record/replay for audio passthrough 2017-03-01 15:11:44 +01:00
spice-port-fqdn.txt
throttle.txt docs: Fix description of the leaky bucket algorithm in throttle.txt 2016-09-13 18:12:34 +03:00
usb2.txt doc/usb2: fix typo 2017-01-24 23:26:53 +03:00
usb-storage.txt usb: Fix typo in documentation 2017-01-24 23:26:52 +03:00
virtio-balloon-stats.txt
xbzrle.txt docs/xbzrle: correction 2016-10-13 17:23:53 +02:00
xen-save-devices-state.txt docs: Belatedly update for move of qmp-commands.txt 2016-10-07 19:22:11 +02:00