[v1] usb: reword -usb command-line option and mention xHCI

[Qemu-devel] [PATCH] usb: reword -usb command-line option and mention xHCI

Posted by Stefan Hajnoczi 6 years, 5 months ago

The -usb section of the man page is not very clear on what exactly -usb
does and fails to mention xHCI as a modern alternative (-device
nec-usb-xhci).

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 qemu-options.hx | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 9621e934c0..7d11c016d1 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1436,12 +1436,15 @@ STEXI
 ETEXI
 
 DEF("usb", 0, QEMU_OPTION_usb,
-    "-usb            enable the USB driver (if it is not used by default yet)\n",
+    "-usb            enable on-board USB host controller (if not enabled by default)\n",
     QEMU_ARCH_ALL)
 STEXI
 @item -usb
 @findex -usb
-Enable the USB driver (if it is not used by default yet).
+Enable USB emulation on machine types with an on-board USB host controller (if
+not enabled by default).  Note that on-board USB host controllers may not
+support USB 3.0.  In this case -device nec-usb-xhci can be used instead on
+machines with PCI.
 ETEXI
 
 DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
-- 
2.21.0

Re: [Qemu-devel] [PATCH] usb: reword -usb command-line option and mention xHCI

Posted by Thomas Huth 6 years, 5 months ago

On 8/13/19 3:30 PM, Stefan Hajnoczi wrote:
> The -usb section of the man page is not very clear on what exactly -usb
> does and fails to mention xHCI as a modern alternative (-device
> nec-usb-xhci).
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  qemu-options.hx | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 9621e934c0..7d11c016d1 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1436,12 +1436,15 @@ STEXI
>  ETEXI
>  
>  DEF("usb", 0, QEMU_OPTION_usb,
> -    "-usb            enable the USB driver (if it is not used by default yet)\n",
> +    "-usb            enable on-board USB host controller (if not enabled by default)\n",
>      QEMU_ARCH_ALL)
>  STEXI
>  @item -usb
>  @findex -usb
> -Enable the USB driver (if it is not used by default yet).
> +Enable USB emulation on machine types with an on-board USB host controller (if
> +not enabled by default).  Note that on-board USB host controllers may not
> +support USB 3.0.  In this case -device nec-usb-xhci can be used instead on

Should we maybe rather recommend qemu-xhci instead?
And please put the @option{} around the "-device *-xhci" here.

With @option:

Reviewed-by: Thomas Huth <thuth@redhat.com>

Re: [Qemu-devel] [PATCH] usb: reword -usb command-line option and mention xHCI

Posted by Stefan Hajnoczi 6 years, 5 months ago

On Tue, Aug 13, 2019 at 07:54:16PM +0200, Thomas Huth wrote:
> On 8/13/19 3:30 PM, Stefan Hajnoczi wrote:
> > The -usb section of the man page is not very clear on what exactly -usb
> > does and fails to mention xHCI as a modern alternative (-device
> > nec-usb-xhci).
> > 
> > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> > ---
> >  qemu-options.hx | 7 +++++--
> >  1 file changed, 5 insertions(+), 2 deletions(-)
> > 
> > diff --git a/qemu-options.hx b/qemu-options.hx
> > index 9621e934c0..7d11c016d1 100644
> > --- a/qemu-options.hx
> > +++ b/qemu-options.hx
> > @@ -1436,12 +1436,15 @@ STEXI
> >  ETEXI
> >  
> >  DEF("usb", 0, QEMU_OPTION_usb,
> > -    "-usb            enable the USB driver (if it is not used by default yet)\n",
> > +    "-usb            enable on-board USB host controller (if not enabled by default)\n",
> >      QEMU_ARCH_ALL)
> >  STEXI
> >  @item -usb
> >  @findex -usb
> > -Enable the USB driver (if it is not used by default yet).
> > +Enable USB emulation on machine types with an on-board USB host controller (if
> > +not enabled by default).  Note that on-board USB host controllers may not
> > +support USB 3.0.  In this case -device nec-usb-xhci can be used instead on
> 
> Should we maybe rather recommend qemu-xhci instead?

I think nec-usb-xhci is preferred because there are Windows drivers.
IIRC qemu-xhci works under Linux but not under Windows (just because the
PCI Vendor/Device ID aren't covered by any driver).

Gerd: Can you confirm this?

Stefan

Re: [Qemu-devel] [PATCH] usb: reword -usb command-line option and mention xHCI

Posted by Gerd Hoffmann 6 years, 5 months ago

  Hi,

> > > -Enable the USB driver (if it is not used by default yet).
> > > +Enable USB emulation on machine types with an on-board USB host controller (if
> > > +not enabled by default).  Note that on-board USB host controllers may not
> > > +support USB 3.0.  In this case -device nec-usb-xhci can be used instead on
> > 
> > Should we maybe rather recommend qemu-xhci instead?
> 
> I think nec-usb-xhci is preferred because there are Windows drivers.
> IIRC qemu-xhci works under Linux but not under Windows (just because the
> PCI Vendor/Device ID aren't covered by any driver).
> 
> Gerd: Can you confirm this?

That applies to windows 7 only, which is EOL next year.

win7 doesn't ship with xhci drivers, but you can download and use
nec/renesas drivers which require nec-usb-xhci.

win8+ ships with generic xhci drivers which works with all xhci
hardware, including qemu-xhci.

So it indeed makes sense to refer to qemu-xhci.

cheers,
  Gerd

Re: [Qemu-devel] [PATCH] usb: reword -usb command-line option and mention xHCI

Posted by Stefan Hajnoczi 6 years, 5 months ago

On Thu, Aug 15, 2019 at 08:13:40AM +0200, Gerd Hoffmann wrote:
>   Hi,
> 
> > > > -Enable the USB driver (if it is not used by default yet).
> > > > +Enable USB emulation on machine types with an on-board USB host controller (if
> > > > +not enabled by default).  Note that on-board USB host controllers may not
> > > > +support USB 3.0.  In this case -device nec-usb-xhci can be used instead on
> > > 
> > > Should we maybe rather recommend qemu-xhci instead?
> > 
> > I think nec-usb-xhci is preferred because there are Windows drivers.
> > IIRC qemu-xhci works under Linux but not under Windows (just because the
> > PCI Vendor/Device ID aren't covered by any driver).
> > 
> > Gerd: Can you confirm this?
> 
> That applies to windows 7 only, which is EOL next year.
> 
> win7 doesn't ship with xhci drivers, but you can download and use
> nec/renesas drivers which require nec-usb-xhci.
> 
> win8+ ships with generic xhci drivers which works with all xhci
> hardware, including qemu-xhci.
> 
> So it indeed makes sense to refer to qemu-xhci.

Thanks, will fix in v2!

Stefan

Re: [Qemu-devel] [PATCH] usb: reword -usb command-line option and mention xHCI

Posted by Dr. David Alan Gilbert 6 years, 5 months ago

* Stefan Hajnoczi (stefanha@redhat.com) wrote:
> The -usb section of the man page is not very clear on what exactly -usb
> does and fails to mention xHCI as a modern alternative (-device
> nec-usb-xhci).

Isn't 'qemu-xhci' the current favoured device?

Dave

> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  qemu-options.hx | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 9621e934c0..7d11c016d1 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1436,12 +1436,15 @@ STEXI
>  ETEXI
>  
>  DEF("usb", 0, QEMU_OPTION_usb,
> -    "-usb            enable the USB driver (if it is not used by default yet)\n",
> +    "-usb            enable on-board USB host controller (if not enabled by default)\n",
>      QEMU_ARCH_ALL)
>  STEXI
>  @item -usb
>  @findex -usb
> -Enable the USB driver (if it is not used by default yet).
> +Enable USB emulation on machine types with an on-board USB host controller (if
> +not enabled by default).  Note that on-board USB host controllers may not
> +support USB 3.0.  In this case -device nec-usb-xhci can be used instead on
> +machines with PCI.
>  ETEXI
>  
>  DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
> -- 
> 2.21.0
> 
> 
--
Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK