Re: [Qemu-devel] [PATCH v4 0/3] qemu-help: improve -device command line help

[Michael S. Tsirkin]

On Tue, Aug 13, 2013 at 11:57:39AM +0200, Markus Armbruster wrote:
> This isn't patch review, just a couple of observations and questions.
> 
> Current use of categories, please correct misunderstandings:
> 
> * A device can have multiple categories.  Most (all?) devices currently
>   have exactly one.
> 
> * -device help shows categories, like this:
> 
>       name "NAME", bus "BUS", categories "CAT1" "CAT2"...
> 
> * -device help is sorted by category
> 
> * -device help shows the device once per category.  If the device has no
>   categories, it's not shown at all.
> 
> Should we require devices to have at least one category?

I think yes - there's a misc category so this shouldn't be a problem.

> Eric, does libvirt still parse -device help?  If yes, can it cope with
> the addition of "categories ..."?
> 
> A possibly better way to group help by category: instead of adding
> categories to each line, add category headlines, like this:
> 
>     Controller/Bridge/Hub devices:
>     name "NAME", bus "BUS"...
>     ...
>     USB devices:
>     name "NAME", bus "BUS"...
>     ...
>     Storage devices:
>     ...
> 
> This way, showing devices with multiple categories once per category
> actually makes sense.

Yes, that's a good next step I think.  Also, if we do hierarchical
layout, how about we actually lay it out in a sane readable way?
name NAME
        bus BUS
        ...



> 
> DEVICE_CATEGORY_STORAGE comprises both storage controller devices
> (providing storage buses such as IDE, SCSI) and storage devices
> (plugging into such buses).  Some of our devices (*-fdc, virtio-blk)
> integrate both in one device model[*].

Let's create two categories and set them for these.

> DEVICE_CATEGORY_USB comprises *only* host controller devices (providing
> USB bus(es)), *not* USB devices (plugging into USB bus).

This sounds sane - this is their function.


>  These are
> categorized by function instead:
> 
> * DEVICE_CATEGORY_BRIDGE: usb-host, usb-hub
> 
> * DEVICE_CATEGORY_STORAGE: usb-bot, usb-uas, usb-storage
> 
> * DEVICE_CATEGORY_NETWORK: usb-bt-dongle, usb-net
> 
> * DEVICE_CATEGORY_INPUT: usb-kbd, usb-ccid, usb-wacom-tablet,
>   usb-braille, usb-mouse, usb-serial
> 
> * DEVICE_CATEGORY_SOUND: usb-audio
> 
> * DEVICE_CATEGORY_MISC: usb-tablet, usb-redir
> 
> Should they additionally be DEVICE_CATEGORY_USB?

I think not - bus info is supplied by the bus field already.
What device provides is what is missing and category is
trying to fill in.

> Why do we have DEVICE_CATEGORY_USB, but no categories for other buses,
> like PCI or ISA?  Devices providing such buses are
> DEVICE_CATEGORY_BRIDGE.  Why is USB different?
> Why is usb-host DEVICE_CATEGORY_BRIDGE?

I agree this is weird. I'd say let's create _PCI, _ISA and _I2C
and get rid of _BRIDGE.

> 
> Why is usb-tablet DEVICE_CATEGORY_MISC, but usb-wacom-tablet
> DEVICE_CATEGORY_INPUT?
> 
> DEVICE_CATEGORY_INPUT is weird.  Some devices in that category are truly
> about input (usb-mouse, usb-kbd), others are at least as often used for
> output (serial devices, PIOs)...

Serial is common enough to have a category of its own.
Suggestions for a good category for PIOs etc?
Maybe MISC is a good fit for these.

> The difference between DEVICE_CATEGORY_INPUT and DEVICE_CATEGORY_MISC
> seems unclear (see usb-tablet vs. usb-wacom-tablet above).

I think MISC should be the last resort.

> 
> 
> [*] I hate that.