[Qemu-commits] [qemu/qemu] 7746cf: bitmaps.md: Convert to rST; move it into 'interop'...

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/qemu/qemu
  Commit: 7746cf8aab6887bf5d0e12d53506a4a374c6b5f4
      
https://github.com/qemu/qemu/commit/7746cf8aab6887bf5d0e12d53506a4a374c6b5f4
  Author: Kashyap Chamarthy <address@hidden>
  Date:   2017-07-18 (Tue, 18 Jul 2017)

  Changed paths:
    R docs/devel/bitmaps.md
    A docs/interop/bitmaps.rst

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

This is part of the on-going effort to convert QEMU upstream
documentation syntax to reStructuredText (rST).

The conversion to rST was done using:

    $ pandoc -f markdown -t rst bitmaps.md -o bitmaps.rst

Then, make a couple of small syntactical adjustments.  While at it,
reword a statement to avoid ambiguity.  Addressing the feedback from
this thread:

    https://lists.nongnu.org/archive/html/qemu-devel/2017-06/msg05428.html

Signed-off-by: Kashyap Chamarthy <address@hidden>
Reviewed-by: John Snow <address@hidden>
Reviewed-by: Eric Blake <address@hidden>
Message-id: address@hidden
Signed-off-by: Jeff Cody <address@hidden>


  Commit: 8508eee740c78d1465e25dad7c3e06137485dfbc
      
https://github.com/qemu/qemu/commit/8508eee740c78d1465e25dad7c3e06137485dfbc
  Author: Kashyap Chamarthy <address@hidden>
  Date:   2017-07-18 (Tue, 18 Jul 2017)

  Changed paths:
    A docs/interop/live-block-operations.rst
    R docs/live-block-ops.txt

  Log Message:
  -----------
  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 <address@hidden>
Reviewed-by: Eric Blake <address@hidden>
Message-id: address@hidden
Signed-off-by: Jeff Cody <address@hidden>


  Commit: f9dada2baabb639feb988b3a564df7a06d214e18
      
https://github.com/qemu/qemu/commit/f9dada2baabb639feb988b3a564df7a06d214e18
  Author: Peter Maydell <address@hidden>
  Date:   2017-07-18 (Tue, 18 Jul 2017)

  Changed paths:
    R docs/devel/bitmaps.md
    A docs/interop/bitmaps.rst
    A docs/interop/live-block-operations.rst
    R docs/live-block-ops.txt

  Log Message:
  -----------
  Merge remote-tracking branch 'remotes/cody/tags/block-pull-request' into 
staging

# gpg: Signature made Tue 18 Jul 2017 05:15:03 BST
# gpg:                using RSA key 0xBDBE7B27C0DE3057
# gpg: Good signature from "Jeffrey Cody <address@hidden>"
# gpg:                 aka "Jeffrey Cody <address@hidden>"
# gpg:                 aka "Jeffrey Cody <address@hidden>"
# Primary key fingerprint: 9957 4B4D 3474 90E7 9D98  D624 BDBE 7B27 C0DE 3057

* remotes/cody/tags/block-pull-request:
  live-block-ops.txt: Rename, rewrite, and improve it
  bitmaps.md: Convert to rST; move it into 'interop' dir

Signed-off-by: Peter Maydell <address@hidden>


Compare: https://github.com/qemu/qemu/compare/20df6c7689eb...f9dada2baabb