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

[Peter Maydell <peter.maydell@linaro.org>]

On 5 June 2018 at 13:52, Gerd Hoffmann <kraxel@redhat.com> wrote:
> 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 ...".
>
> While being at it rework the text on ehci and companion controllers too.
>
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  docs/usb2.txt | 80 ++++++++++++++++++++++++++++++++++-------------------------
>  1 file changed, 46 insertions(+), 34 deletions(-)


This is good; I did a quick pass-through for typos and the like.

> diff --git a/docs/usb2.txt b/docs/usb2.txt
> index 09df45b5b1..30055a2258 100644
> --- a/docs/usb2.txt
> +++ b/docs/usb2.txt
> @@ -1,16 +1,42 @@
>
> -USB 2.0 Quick Start
> -===================
> +USB Quick Start
> +===============
>
> -The QEMU EHCI Adapter can be used with and without companion
> -controllers.  See below for the companion controller mode.
> +xhci controller support
> +-----------------------
>
> -When not running in companion controller mode there are two completely
> -separate USB busses: One USB 1.1 bus driven by the UHCI controller and
> -one USB 2.0 bus driven by the EHCI controller.  Devices must be
> -attached to the correct controller manually.
> +Qemu has xhci host adapter support.  The xhci hardware design is much

"QEMU" should be all upper-case.

We also seem to be inconsistent about whether to uppercase UHCI,
EHCI and XHCI. I'd suggest using all-upper-case (except obviously
in QEMU device names like 'qemu-xhci').

> +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 around 2010 or later) I recommend using it:

I think we should phrase our documentation from a project point
of view, so "we recommend" rather than "I".

>
> -The '-usb' switch will make qemu create the UHCI controller as part of
> +    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

s/being//

> +no need to use the bus= parameter when adding usb devices.
> +
> +
> +ehci controller support
> +-----------------------
> +
> +The QEMU EHCI Adapter supports USB 2.0 devices.  It can be used either
> +standalone or with companion controllers (UHCI, OHCI) for USB 1.1
> +devices.  The companion controller setup is more convinient to use

"convenient".

> +because it provides a single usb bus supporting both USB 2.0 and USB
> +1.1 devices.  See next section for details.
> +
> +When running EHCI in standalone mode you can add UHCI or OHCI
> +controllers for USB 1.1 devices too.  Each controller creates its own
> +bus though, so there are two completely separate USB busses: One USB

"buses". (the double-s spelling is a valid but less-used variant;
our docs mostly use the single-s spelling though, so we should
go with that for consistency.)

> +1.1 bus driven by the UHCI controller and one USB 2.0 bus driven by
> +the EHCI controller.  Devices must be attached to the correct
> +controller manually.
> +
> +The easiest way to add a UHCI controller to a 'pc' machine is the
> +'-usb' switch, qemu will create the UHCI controller as function of

s/, qemu/. QEMU/.

>  the PIIX3 chipset.  The USB 1.1 bus will carry the name "usb-bus.0".
>
>  You can use the standard -device switch to add a EHCI controller to
> @@ -37,37 +63,23 @@ device to the EHCI adapter.
>  Companion controller support
>  ----------------------------
>
> -Companion controller support has been added recently.  The operational
> -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.
> +The UHCI and OHCI controllers can 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 ...
> +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.
> +Using the '-usb' switch for 'q35' machines will create a simliar

"similar".

> +usb controller configuration.
>

thanks
-- PMM