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

[Markus Armbruster]

Stefan Hajnoczi <address@hidden> writes:

> On Wed, Jun 16, 2010 at 6:27 PM, Markus Armbruster <address@hidden> wrote:
>> 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", ...
>
> What is the default when unset?  (I expect we'll auto-detect the
> format but this should be documented.)

For command line and human monitor, we definitely want a sensible
default.  I sketched one in section "Command line syntax".  I'll quote
it for your convenience a few lines down.

>> - "protocol": image access protocol (json-string, optional)
>>    - Possible values: "auto", "file", "nbd", ...
>
> The semantics of "auto" are not documented here.

Uh, that slipped in here.  It means "guess protocol from image file
type".

Again, for command line and human monitor, we definitely want a sensible
default, and I sketched one in section "Command line syntax".

We may want the same defaults in QMP, although more for consistency than
for usability.  But I didn't want to complicate the QMP section with all
that defaults business, so I moved discussion of defaults down to the
command line section.  Hope I didn't cause even more confusion that way.

Anyway, here's what I wrote on default format:

   * The default format is derived from the image file name: if it ends
     with .F, where F is a format name, that format is the default, else
     "raw".

To let users ask for this explicitely, we could have pseudo-format
"auto".

We also need a pseudo-format "probe", which guesses the format from the
image contents.  Can't be made the default, because it's insecure.

On protocol "auto":

   * The default protocol depends on the image file type: if it is a
     special file, it defaults to the protocol appropriate for that special
     file ("host_cdrom" for CD-ROM, ...).  Else it defaults to "file".

   This permits shortening the first two examples:

       -blockdev id=blk1,file=fedora.img

       -blockdev id=blk2,blkdebug=test.blkdebug,file=test.qcow2

And for completeness, let me quote the unshortened examples, too:

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

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

>> 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.
>
> Perhaps this is what "auto" means?
>
>> (2) It's possible to list supported disk formats and protocols by
>>    running QEMU with arguments "-blockdev_add \?".
>
> Is there an query-block-driver command or something in QMP to
> enumerate supported formats and protocols?  Not sure how useful this
> would be to the management stack - blockdev_add will probably return
> an error if an attempt is made to open an unsupported file.

QMP should be "self-documenting": a client should be able to list
commands, their arguments, and possible argument values.  Listing
supported formats then becomes "list possible values of command
blockdev_add's argument format".

>> 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": {} }
>
> What about an attached guest device?  Will this fail if the virtio-blk
> PCI device is still present?  For SCSI I imagine we can usually just
> remove the host block device.  For IDE there isn't hotplug support
> AFAIK, what happens?

Command fails.  You have to device_del the device first.  Which is only
possible if its bus supports hot-plug.

Thanks!