qemu-doc.texi: Improve USB documentation... and maybe even QEMU also

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 <programmingkidx@gmail.com>

---
 qemu-doc.texi |   34 ++++++++++++++++++++++++++++++----
 1 files changed, 30 insertions(+), 4 deletions(-)

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

On Aug 24, 2015, at 5:45 AM, Markus Armbruster wrote:

> 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?

It does. Thank you for this information. 

> 
>>                                                   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?

Ok. usb_remove isn't needed. Why is it that "device_add usb-kbd" works, but
"device_del usb-kbd" doesn't work? I am given this error message: "Device 'usb-kbd' not found".

Programmingkid <programmingkidx@gmail.com> writes:

> On Aug 24, 2015, at 5:45 AM, Markus Armbruster wrote:
>
>> 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?
>
> It does. Thank you for this information. 

My pleasure.

>>>                                                   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?
>
> Ok. usb_remove isn't needed. Why is it that "device_add usb-kbd" works, but
> "device_del usb-kbd" doesn't work? I am given this error message:
> "Device 'usb-kbd' not found".

device_del's argument isn't a driver, it's a device ID.  Try this:

    (qemu) device_add usb-mouse,id=mouse0
    (qemu) info usb
      Device 0.0, Port 1, Speed 12 Mb/s, Product QEMU USB Mouse
    (qemu) device_del mouse0
    (qemu) info usb
    (qemu)

On Aug 24, 2015, at 12:38 PM, Markus Armbruster wrote:

> Programmingkid <programmingkidx@gmail.com> writes:
> 
>> On Aug 24, 2015, at 5:45 AM, Markus Armbruster wrote:
>> 
>>> 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?
>> 
>> It does. Thank you for this information. 
> 
> My pleasure.
> 
>>>>                                                  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?
>> 
>> Ok. usb_remove isn't needed. Why is it that "device_add usb-kbd" works, but
>> "device_del usb-kbd" doesn't work? I am given this error message:
>> "Device 'usb-kbd' not found".
> 
> device_del's argument isn't a driver, it's a device ID.  Try this:
> 
>    (qemu) device_add usb-mouse,id=mouse0
>    (qemu) info usb
>      Device 0.0, Port 1, Speed 12 Mb/s, Product QEMU USB Mouse
>    (qemu) device_del mouse0
>    (qemu) info usb
>    (qemu) 

The problem is with "info usb". It doesn't print the id you gave it. I will make a patch that
will print the id's.

Programmingkid <programmingkidx@gmail.com> writes:

> On Aug 24, 2015, at 12:38 PM, Markus Armbruster wrote:
>
>> Programmingkid <programmingkidx@gmail.com> writes:
>> 
>>> On Aug 24, 2015, at 5:45 AM, Markus Armbruster wrote:
>>> 
>>>> 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?
>>> 
>>> It does. Thank you for this information. 
>> 
>> My pleasure.
>> 
>>>>>                                                  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?
>>> 
>>> Ok. usb_remove isn't needed. Why is it that "device_add usb-kbd" works, but
>>> "device_del usb-kbd" doesn't work? I am given this error message:
>>> "Device 'usb-kbd' not found".
>> 
>> device_del's argument isn't a driver, it's a device ID.  Try this:
>> 
>>    (qemu) device_add usb-mouse,id=mouse0
>>    (qemu) info usb
>>      Device 0.0, Port 1, Speed 12 Mb/s, Product QEMU USB Mouse
>>    (qemu) device_del mouse0
>>    (qemu) info usb
>>    (qemu) 
>
> The problem is with "info usb". It doesn't print the id you gave it. I
> will make a patch that
> will print the id's. 

Yes, "info usb" doesn't show the qdev ID.  Neither does "info pci".
"info qom" and "info qtree" do.

On Aug 25, 2015, at 3:43 AM, Markus Armbruster wrote:

> Programmingkid <programmingkidx@gmail.com> writes:
> 
>> On Aug 24, 2015, at 12:38 PM, Markus Armbruster wrote:
>> 
>>> Programmingkid <programmingkidx@gmail.com> writes:
>>> 
>>>> On Aug 24, 2015, at 5:45 AM, Markus Armbruster wrote:
>>>> 
>>>>> 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?
>>>> 
>>>> It does. Thank you for this information. 
>>> 
>>> My pleasure.
>>> 
>>>>>>                                                 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?
>>>> 
>>>> Ok. usb_remove isn't needed. Why is it that "device_add usb-kbd" works, but
>>>> "device_del usb-kbd" doesn't work? I am given this error message:
>>>> "Device 'usb-kbd' not found".
>>> 
>>> device_del's argument isn't a driver, it's a device ID.  Try this:
>>> 
>>>   (qemu) device_add usb-mouse,id=mouse0
>>>   (qemu) info usb
>>>     Device 0.0, Port 1, Speed 12 Mb/s, Product QEMU USB Mouse
>>>   (qemu) device_del mouse0
>>>   (qemu) info usb
>>>   (qemu) 
>> 
>> The problem is with "info usb". It doesn't print the id you gave it. I
>> will make a patch that
>> will print the id's. 
> 
> Yes, "info usb" doesn't show the qdev ID.  Neither does "info pci".
> "info qom" and "info qtree" do.

It sounds like these info's could use some improving...