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

[Markus Armbruster <armbru@redhat.com>]

Avi Kivity <avi@redhat.com> writes:

> On 06/10/2010 08:45 PM, Markus Armbruster wrote:
>> 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": {} }
>>
>>    
>
> media_insert/remove seem to duplicate blockdev_add/del.  Perhaps we
> don't need them?
>
> To change media, tell the guest device to eject, blockdev_del,
> blockdev_add, reassociate the guest and host parts.

Device model code is not prepared to have host parts go away and come
back during operation.  The device model driver attaches to the host
part on initialization, and detaches only when the device gets destroyed
(hot unplug).

If we yank out the host part during operation as you propose, then the
device model driver's pointer to the host part becomes null.  I don't
see that ending happily.

> To pretend you're a media changer, blockdev_add all your cds at once
> and just change the guest/host association when you want to hear a new
> band.
>
> For a fake a multipath setup, blockdev_add one device, associate it
> with multiple guest interfaces.
>
> Otherwise, looks good.

Any preference on the command line option syntax?