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

[Markus Armbruster]

Discussion with Christoph and Kevin uncovered yet another issue:
protocols.  I find it pretty confusing, but let me try to describe it
anyway; Christoph and Kevin, please correct my errors.

A host block device has a format.  A format has a name.

Below the format, it has a stack of protocols.  A protocol has a name
(with one exception), and may have protocol-specific arguments.

The most basic (and most commonly used) protocol is for accessing a
file.  Its argument is a file name.  It doesn't have a name.  Which
makes for ugly prose, so I'll call it "file".

Stacking protocols is somewhat exotic.  Think of stacking blkdebug on
top of another protocol, say nbd.

Our abstraction for formats is struct BlockDriver.

Our abstraction for protocols is also struct BlockDriver.  Except for
the special protocol "file", but that's detail.

Examples:

-drive file=foo.qcow2,format=qcow2

 Format "qcow2", protocol "file" with argument filename "foo.img"

-drive file=nbd:unix:/tmp/my_socket,format=raw

 Format "raw", protocol "nbd" with arguments domain "unix", filename
 "/tmp/my_socket"

-drive blkdebug:/tmp/blkdebug.cfg:fat:floppy:rw:/tmp/dir

 Format not specified (system guesses one), protocol "blkdebug" with
 argument filename "/tmp/blkdebug.cfg" stacked onto protocol "fat" with
 arguments floppy true, dirname "/tmp/dir"

You see that -drive has a separate option for format, but has protocols
encoded in option file, in their own mini-language.  Doesn't work for
arbitrary filenames.  Besides, mini-languages to encode options in
strings are quite inappropriate for QMP.

So we need something cleaner for QMP.  Here's a sketch.  Instead of

- "file": the disk image file to use (json-string, optional)
- "format": disk format (json-string, optional)
    - Possible values: "raw", "qcow2", ...

have

- "format": disk format (json-string, optional)
    - Possible values: "raw", "qcow2", ...
- "protocol": json-array of json-object
  Each element object has a member "name"
    - Possible values: "file", "nbd", ...
  Additional members depend on the value of "name".
  For "name" = "file":
    - "file": file name (json-string)
  For "name" = "nbd":
    - "domain": address family (json-string, optional)
        - Possible values: "inet" (default), "unix"
    - "file": file name (json-string), only with "domain" = "unix"
    - "host": host name (json-string), only with "domain" = "inet"
    - "port": port (json-int), only with "domain" = "inet"
  ...

You get the idea.

Comments?