Re: [Qemu-devel] [PATCH] usb: update docs

[Markus Armbruster]

Gerd Hoffmann <address@hidden> writes:

> xhci is rock solid meanwhile.  So move it up in the docs and feature it
> as prefered usb host adapter, instead of the old shy version saying "you
> might want try ...".
>
> Also a minor text update for the companion controller setup.
>
> Signed-off-by: Gerd Hoffmann <address@hidden>
> ---
>  docs/usb2.txt | 44 +++++++++++++++++++++++++-------------------
>  1 file changed, 25 insertions(+), 19 deletions(-)
>
> diff --git a/docs/usb2.txt b/docs/usb2.txt
> index 09df45b5b1..1b0e62d187 100644
> --- a/docs/usb2.txt
> +++ b/docs/usb2.txt
> @@ -1,6 +1,26 @@
>  
> -USB 2.0 Quick Start
> -===================
> +USB Quick Start

Would you like to renamed the file from usb2.txt to usb.txt, too?

> +===============
> +
> +xhci controller support
> +-----------------------
> +
> +Qemu has xhci host adapter support.  The xhci hardware design is much
> +more virtualization-friendly when compared to ehci and uhci, thus xhci
> +emulation uses less resources (especially cpu).  So if your guest
> +supports xhci (which should be the case for any operating system
> +released in recent years) I recommend using it:

I'm afraid "recent years" won't age gracefully.  Perhaps "after 2011 or
so"?

> +
> +    qemu -device qemu-xhci
> +
> +xhci supports USB 1.1, USB 2.0 and USB 3.0 devices, so this is the
> +only controller you need.  With only a single usb controller (and
> +therefore only a single usb bus) being present in the system there is
> +no need to use the bus= parameter when adding usb devices.
> +
> +
> +ehci controller support
> +-----------------------
>  
>  The QEMU EHCI Adapter can be used with and without companion
>  controllers.  See below for the companion controller mode.



> @@ -47,29 +67,15 @@ specifies the first port the controller should attach to, 
> which is
   Companion controller support
   ----------------------------

   Companion controller support has been added recently.  The operational

For a value of "recently" :)  Rephrase the first sentence?

   model described above with two completely separate busses still works
   fine.  Additionally the UHCI and OHCI controllers got the ability to
   attach to a usb bus created by EHCI as companion controllers.  This is
   done by specifying the masterbus and firstport properties.  masterbus
   specifies the bus name the controller should attach to.  firstport
   specifies the first port the controller should attach to, which is
>  needed as usually one ehci controller with six ports has three uhci
>  companion controllers with two ports each.
>  
> -There is a config file in docs which will do all this for you, just
> -try ...
> +Result is a single usb bus which supports both USB 1.1 and USB 2.0
> +devices.  There is a config file in docs which will do all this for
> +you, just try ...
>  
>      qemu -readconfig docs/config/ich9-ehci-uhci.cfg
>  
>  ... then use "bus=ehci.0" to assign your usb devices to that bus.
>  
>  
> -xhci controller support
> ------------------------
> -
> -There is also xhci host controller support available.  It got a lot
> -less testing than ehci and there are a bunch of known limitations, so
> -ehci may work better for you.  On the other hand the xhci hardware
> -design is much more virtualization-friendly, thus xhci emulation uses
> -less resources (especially cpu).  If you want to give xhci a try
> -use this to add the host controller ...
> -
> -    qemu -device nec-usb-xhci,id=xhci
> -
> -... then use "bus=xhci.0" when assigning usb devices.
> -
> -
>  More USB tips & tricks
>  ======================

Even without additional improvements:
Reviewed-by: Markus Armbruster <address@hidden>