Copying the USB maintainer. Programmingkid <programmingk...@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 <programmingk...@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