[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] qemu-doc.texi: Improve USB documentation... and maybe e
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] qemu-doc.texi: Improve USB documentation... and maybe even QEMU also |
Date: |
Mon, 24 Aug 2015 11:45:21 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) |
Copying the USB maintainer.
Programmingkid <address@hidden> 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 <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.
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.
>
> 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::
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:
> 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.
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
> address@hidden 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
- [Qemu-devel] [PATCH v2] qemu-doc.texi: Add usb sound card info, Programmingkid, 2015/08/06
- Re: [Qemu-devel] [PATCH v2] qemu-doc.texi: Add usb sound card info, Markus Armbruster, 2015/08/08
- Re: [Qemu-devel] [PATCH v2] qemu-doc.texi: Add usb sound card info, Programmingkid, 2015/08/08
- [Qemu-devel] qemu-doc.texi: Improve USB documentation... and maybe even QEMU also, Programmingkid, 2015/08/17
- Re: [Qemu-devel] qemu-doc.texi: Improve USB documentation... and maybe even QEMU also,
Markus Armbruster <=
- Re: [Qemu-devel] qemu-doc.texi: Improve USB documentation... and maybe even QEMU also, Programmingkid, 2015/08/24
- Re: [Qemu-devel] qemu-doc.texi: Improve USB documentation... and maybe even QEMU also, Markus Armbruster, 2015/08/24
- Re: [Qemu-devel] qemu-doc.texi: Improve USB documentation... and maybe even QEMU also, Programmingkid, 2015/08/24
- Re: [Qemu-devel] qemu-doc.texi: Improve USB documentation... and maybe even QEMU also, Markus Armbruster, 2015/08/25
- Re: [Qemu-devel] qemu-doc.texi: Improve USB documentation... and maybe even QEMU also, Programmingkid, 2015/08/25