Re: [Qemu-devel] qemu-doc.texi: Improve USB documentation... and maybe even QEMU also

[Markus Armbruster <armbru@redhat.com>]

Copying the USB maintainer.

Programmingkid <programmingkidx@gmail.com> writes:

> On Aug 8, 2015, at 8:48 AM, Programmingkid wrote:
>
>> 
>> On Aug 8, 2015, at 2:04 AM, Markus Armbruster wrote:
>>>> 
>>>> USB devices can be connected with the @option{-usbdevice} commandline option
>>>> -or the @code{usb_add} monitor command.  Available devices are:
>>>> +or the @code{usb_add} monitor command. Note: some devices may only work if
>>>> +added like this: -usb -device <usb device>. Available devices are:
>>> 
>>> I'm afraid "may only work" is a bit misleading.  All of them work with
>>> -device.  Old ones are also supported by -usbdevice for backward
>>> compatibility.  The whole section should be rewritten to point to
>>> -device instead of legacy -usbdevice, but that's no reason to hold up
>>> your patch.
>> 
>> I did not know -usbdevice was considered legacy. If that is the
>> case, then it should probably
>> be removed from the documentation in favor for -usb -device <device name>. 
>
> Right now using "-usb -device mouse" doesn't work.

You need to say -device usb-mouse.  See docs/qdev-device-use.txt.  Does
it work for you when you do that?

>                                                    Neither does
> "-usbdevice usb-audio".

Yes.  Legacy -usbdevice only supports the devices that predate -device.

> I think we can all agree that consistency among all the USB devices is
> a good thing.
> Should all USB devices be added like this: -usb -device <device name> ? 

"Should" is perhaps a bit strong.  While -device is the recommended way
to add a USB device, -usbdevice is still a supported (if legacy) way to
do it.

Of course, "supported, but legacy" interfaces such as -usbdevice may
become deprecated, and then you should really move to newer interfaces,
because deprecated ones may go away.  Doesn't look terribly probable to
me for -usbdevice, though.

> This is an experimental patch of not how QEMU currently works, but how
> I think it should work.
>
> This documentation adds an "usb_remove" monitor command. This isn't
> available right now,
> but a patch could be made to change this. Any suggestions or additions
> are welcomed.

Why do you think we need usb_remove in addition to device_del?

> Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
>
> ---
>  qemu-doc.texi |   34 ++++++++++++++++++++++++++++++----
>  1 files changed, 30 insertions(+), 4 deletions(-)
>
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 94af8c0..e265d72 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -1316,10 +1316,19 @@ monitor (@pxref{pcsys_keys}).
>  @section USB emulation
>  
>  QEMU emulates a PCI UHCI USB controller. You can virtually plug
> -virtual USB devices or real host USB devices (experimental, works only
> -on Linux hosts).  QEMU will automatically create and connect virtual USB hubs
> +virtual USB devices or real host USB devices. QEMU will automatically
> +create and connect virtual USB hubs
>  as necessary to connect multiple USB devices.

This part drops the "experimental, works only on Linux" parenthesis.
Assuming that's appropriate: separate patch, please.  Okay to do it
together with other corrections and improvements to USB documentation.

>  
> +@subsection USB Monitor Commands:
> +@table @option
> +@item usb_add <device>
> +Adds an usb device.
> +@item usb_remove <device>
> +Removes an usb device.
> +@item info usb
> +Prints info on all connected usb devices.
> +@end table
>  @menu
>  * usb_devices::
>  * host_usb_devices::

Please limit a patch adding a new feature (here: usb_remove) to just
adding the new feature.  If you want to change the structure of the
manual (here: mention usb monitor commands in yet another place), do it
in a separate patch.

> @@ -1327,8 +1336,19 @@ as necessary to connect multiple USB devices.
>  @node usb_devices
>  @subsection Connecting USB devices
>  
> -USB devices can be connected with the @option{-usbdevice} commandline option
> -or the @code{usb_add} monitor command.  Available devices are:
> +
> +To add an USB device from the command-line:
> +-usb -device <device name>
> +
> +To add an USB device from the monitor:
> +usb_add <device name>
> +
> +Examples:
> +@example
> +usb_add mouse
> +-usb -device mouse -device keyboard -device usb-audio
> +@end example
> +*note: the -usb option only needs to be used once.

Likewise: do not mix up your new feature with proposed improvements of
documention for existing stuff.

>  
>  @table @code
>  @item mouse
> @@ -1381,8 +1401,14 @@ usage:
>  @example
>  qemu-system-i386 [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt
> device:keyboard,vlan=3
>  @end example
> +@item usb-audio
> +USB sound card.
>  @end table

Here, you add documentation on usb-audio in addition to adding your new
command.  I'm not even reviewing this in its current state, sorry.

>  
> +Legacy note:
> +USB devices use to be connected with the @option{-usbdevice}
> command-line option.
> +Not all usb devices work with this option now.
> +
>  @node host_usb_devices
>  @subsection Using host USB devices on a Linux host