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

[Programmingkid]

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. Neither does "-usbdevice 
usb-audio".
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> ? 

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.

Signed-off-by: John Arbuckle <address@hidden>

---
 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.
 
address@hidden USB Monitor Commands:
address@hidden @option
address@hidden usb_add <device>
+Adds an usb device.
address@hidden usb_remove <device>
+Removes an usb device.
address@hidden info usb
+Prints info on all connected usb devices.
address@hidden table
 @menu
 * usb_devices::
 * host_usb_devices::
@@ -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:
address@hidden
+usb_add mouse
+-usb -device mouse -device keyboard -device usb-audio
address@hidden example
+*note: the -usb option only needs to be used once.
 
 @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
address@hidden usb-audio
+USB sound card.
 @end table
 
+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
 
-- 
1.7.5.4