[Qemu-devel] RFC v2: blockdev_add & friends, brief rationale, QMP docs

[Markus Armbruster]

v2: Cover protocols
    Split blockdev_change into media_insert and media_remove
    Option syntax
    list TODOs


Rationale: Why new commands for block devices?
==============================================

We want a clean separation between host part and guest part.  Existing
-drive and drive_add don't provide that; they were designed to specify
both parts together.  Moreover, drive_add is limited to adding virtio
drives (with pci_add's help) and SCSI drives.

We already have commands to specify the guest part: -device and
device_add.

Support for defining just a host part for use with -device and
device_add was grafted onto -drive and drive_add (if=none), but it's a
mess.  Some parts are redundant, other parts are broken.

For instance, unit, bus, index, addr are redundant: -device/device_add
don't use them.  They provide their own parameters to specify bus and
bus-specific address.

The checks whether rerror, werror, readonly, cyls, heads, secs are sane
for a particular guest device model are broken.  The checks are in the
-drive code, which used to know what the guest device model supports,
but can't with if=none.

Moreover, -drive/drive_add have several flaws:

* Many parameters set with -drive/drive_add silently revert to defaults
  on media change.

* There are two ways to specify protocol, and both are flawed: you
  either use parameter format (then you can neither specify a
  non-default format, nor supply protocol options), or encode it in
  parameter file (yet another ad hoc mini-language, breaks filenames
  with ':').

* Behavior when format= is missing is insecure.

My proposed solution is a new option -blockdev and monitor command
blockdev_add.  These specify only the host drive.  Guest drive
properties are left to -device/device_add.  We keep -drive for backwards
compatibility and command line convenience.  Except we get rid of
if=none (may need a grace period).

New monitor command blockdev_del works regardless of how the host block
device was created.

New monitor commands media_insert, media_remove provide full control
over the host part, unlike the existing change command.

Summary of the host / guest split:

-drive options                  host or guest?
bus, unit, if, index, addr      guest, already covered by qdev
cyls, heads, secs, trans        guest, new qdev properties
                                  (but defaults depend on image)
media                           guest FIXME
snapshot, cache, aio            host, blockdev_add options
file, format                    host, blockdev_add options
                                  separate option for protocol
                                  format is just that, not protocol
                                  file is just a filename, no protocol
rerror, werror                  host, guest device models will
                                  reject values they don't support
serial                          guest, new qdev properties
readonly                        both host & guest, qdev will refuse to
                                  connect readonly host to read/write
                                  guest


QMP command docs
================

blockdev_add
------------

Add host block device.

Arguments:

- "id": the host block device's ID, must be unique (json-string)
- "format": image format (json-string, optional)
    - Possible values: "raw", "qcow2", ...
- "protocol": image access protocol (json-object, optional)
    - Has a member "type" (json-string), and depending on its value
      additional members
    - For "type" = "file", [...]
      - "file": name of image file (json-string)
    - For "type" = "nbd":
      - "domain": address family (json-string, optional)
          - Possible values: "inet" (default), "unix"
      - "file": name of socket file (json-string), only with "domain" =
        "unix"
      - "host": host name (json-string), only with "domain" = "inet"
      - "port": port (json-int), only with "domain" = "inet"
    - For "type" = "blkdebug":
      - "config": name of config file (json-string)
      - "protocol": image access protocol (json-object), as above
    [...]
- "aio": host AIO (json-string, optional)
    - Possible values: "threads" (default), "native"
- "cache": host cache usage (json-string, optional)
    - Possible values: "writethrough" (default), "writeback", "unsafe",
                       "none"
- "readonly": open image read-only (json-bool, optional, default false)
- "rerror": what to do on read error (json-string, optional)
    - Possible values: "report" (default), "ignore", "stop"
- "werror": what to do on write error (json-string, optional)
    - Possible values: "enospc" (default), "report", "ignore", "stop"
- "snapshot": enable snapshot (json-bool, optional, default false)

Example:

-> { "execute": "blockdev_add",
     "arguments": { "id": "blk1", "format": "raw",
                    "protocol": { "type": "file", "file": "fedora.img" } } }
<- { "return": {} }

-> { "execute": "blockdev_add",
     "arguments": {
       "id": "blk2", "format": "qcow2",
       "protocol": {
         "type": "blkdebug", "config": "test.blkdebug",
         "protocol": { "type": "file", "file": "test.qcow2" }
       }
     }
   }
<- { "return": {} }

Notes:

(1) If argument "protocol" is missing, all other optional arguments must
    be missing as well.  This defines a block device with no media
    inserted.

(2) In theory, the protocols form a tree.  In practice, all protocols
    but blkdebug have no children, and blkdebug has just one.

(3) It's possible to list supported disk formats by running QEMU with
    arguments "-blockdev_add \?".


blockdev_del
------------

Remove a host block device.

Arguments:

- "id": the host block device's ID (json-string)

Example:

-> { "execute": "blockdev_del", "arguments": { "id": "blk1" } }
<- { "return": {} }


media_insert
------------

Insert media into an empty host block device.

Arguments are exactly like blockdev_add, except "protocol" is mandatory.


media_remove
------------

Remove media from a host block device.

Arguments:

- "id": the host block device's ID (json-string)

Example:

-> { "execute": "media_remove", "arguments": { "id": "blk1" } }
<- { "return": {} }


Command line syntax
===================

We want common setups to be simple, and fancy setups to be possible.
"Simple" means use of common QemuOpts syntax, and reasonable defaults.

The trouble are protocols.  QemuOpts provides a list of options.
Protocols stack, so in the general case, we need a tree of lists of
options.

I can see a couple of ways to do this, and each of them sucks in its own
way.

Let me start with QMP snippets for the examples I'm going to use:

* The common case: a single protocol

  {
      "id": "blk1", "format": "raw",
      "protocol": { "type": "file", "file": "fedora.img" }
  }

* blkdebug

  {
      "id": "blk2", "format": "qcow2",
      "protocol": {
          "type": "blkdebug", "config": "test.blkdebug",
          "protocol": { "type": "file", "file": "test.qcow2" }
      }
  }

* Avi's hypothetical mirror protocol

  {
      "id": "blk3", "format": "raw",
      "protocol": {
          "type": "mirror",
          "protocols": [
              { "type": "file", "file": "local.img" }
              { "type": "nbd", "domain": "unix", "socket": "nbd-sock" }
          ]
      }
  }

I think we can all agree that the common case should look as simple as
this:

    -blockdev id=blk1,file=fedora.img                (*)

Here, file=fedora.img has the intuitive meaning "use fedora.img with the
appropriate protocol and a default format".  Since fedora.img is not a
special file, the appropriate protocol is "file".  The default format is
"raw".  Maybe we want to pick default format based on filename,
say. "qcow2" when the file name ends with ".qcow2".

Now let's examine what we can do to provide for the general case.

1. Make QemuOpts recursive, add brackets to its syntax

   This has several serious drawbacks:

   * No matter what kind of bracket we choose, the shell will be unhappy
     with it, unless we quote them.  Angle brackets fail destructively
     (redirection).  Curly braces suffer brace expansion.  Parenthesis
     fail reliably.  Square brackets suffer filename expansion.
     However, since actual match is unlikely, they're likely to just
     work.  Except with shopt failglob they fail reliably.  I guess
     they're the least bad choice.

   * We need a way to escape the brackets, or else we can't do filenames
     containing brackets.

     We better choose an escape syntax that doesn't interfere with the
     shell's.

     If we make brackets special characters in all option values, then
     no matter what escape syntax we choose, we'll break existing usage.
     In particular, brackets in filenames would need escaping.

     The one exception is to use ',' as escape character, but that's
     just too ugly.

     If we make brackets special characters only in values of structured
     options like protocol, our syntax becomes context-sensitive.  Ugh.

   * Our config file format is in INI syntax.  QemuOpts correspond to
     INI sections.  Sections can't be nested, so recursive QemuOpts
     don't translate.

   Examples:

   * Single protocol:

     -blockdev id=blk1,format=raw,protocol=[file,file=fedora.img]

     Requires suitable syntactic sugar to get the simple form (*).

   * blkdebug

     -blockdev id=blk2,format=qcow2,\
     protocol=[blkdebug,config=test.blkdebug,\
     protocol=[file,file=test.qcow2]]

   * Avi's mirror:

     -blockdev id=blk3,format=raw,\
     protocol=[mirror,\
     [file,file=local.img],\
     [nbd,domain=unix,sockert=nbd-sock]]

2. We already have a syntax to specify trees, namely JSON, so use it

   If -blockdev's argument starts with '{', it's a JSON object suitable
   as argument of blockdev_add in QMP.

   We still provide ordinary QemuOpts syntax for the cases that can be
   expressed with it, i.e. single protocol.

   I figure we'd want syntactic sugar for blkdebug, to permit its use
   from the command line without having to resort to JSON.

3. Stack protocols through named references

   The first protocol is "inlined" into -blockdev.  Any further
   protocols need to be referenced by name.

   Best explained by example:

   * Single protocol:

     -blockdev id=blk1,format=raw,protocol=file,file=fedora.img

     To get the simple form (*), make protocol optional with a suitable
     default.

   * blkdebug

     -blockdev id=blk2,format=qcow2,protocol=blkdebug,config=test.blkdebug,\
     base=blk2-base
     -blockproto id=blk2-base,protocol=file,file=test.qcow2

   * Avi's mirror:

     -blockdev id=blk3,format=raw,protocol=mirror,\
     base=blk3-base1,base=blk3=base2
     -blockproto id=blk3-base1,protocol=file,file=local.img
     -blockproto id=blk3-base2,protocol=nbd,domain=unix,sockert=nbd-sock

   Anything but a single protocol becomes pretty verbose.  Syntactic
   sugar for the blkdebug case would be possible; not sure it's worth
   it.

   No QemuOpts syntax changes.  INI can handle this just fine.


TODO
====

* Pick a command line syntax

* Human monitor syntax