USB Quick Start
===============

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

    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) present in the system there is 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 convenient to use
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 buses: 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.

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
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
your virtual machine.  It is strongly recommended to specify an ID for
the controller so the USB 2.0 bus gets an individual name, for example
'-device usb-ehci,id=ehci".  This will give you a USB 2.0 bus named
"ehci.0".

When adding USB devices using the -device switch you can specify the
bus they should be attached to.  Here is a complete example:

    qemu -M pc ${otheroptions}                           \
        -drive if=none,id=usbstick,file=/path/to/image   \
        -usb                                             \
        -device usb-ehci,id=ehci                         \
        -device usb-tablet,bus=usb-bus.0                 \
        -device usb-storage,bus=ehci.0,drive=usbstick

This attaches a USB tablet to the UHCI adapter and a USB mass storage
device to the EHCI adapter.


Companion controller support
----------------------------

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

    qemu -readconfig docs/config/ich9-ehci-uhci.cfg

... then use "bus=ehci.0" to assign your USB devices to that bus.

Using the '-usb' switch for 'q35' machines will create a similar
USB controller configuration.


More USB tips & tricks
======================

Recently the USB pass through driver (also known as usb-host) and the
QEMU USB subsystem gained a few capabilities which are available only
via qdev properties, i,e. when using '-device'.


physical port addressing
------------------------

First you can (for all USB devices) specify the physical port where
the device will show up in the guest.  This can be done using the
"port" property.  UHCI has two root ports (1,2).  EHCI has six root
ports (1-6), the emulated (1.1) USB hub has eight ports.

Plugging a tablet into UHCI port 1 works like this:

        -device usb-tablet,bus=usb-bus.0,port=1

Plugging a hub into UHCI port 2 works like this:

        -device usb-hub,bus=usb-bus.0,port=2

Plugging a virtual USB stick into port 4 of the hub just plugged works
this way:

        -device usb-storage,bus=usb-bus.0,port=2.4,drive=...

You can do basically the same in the monitor using the device_add
command.  If you want to unplug devices too you should specify some
unique id which you can use to refer to the device ...

        (qemu) device_add usb-tablet,bus=usb-bus.0,port=1,id=my-tablet
        (qemu) device_del my-tablet

... when unplugging it with device_del.


USB pass through hints
----------------------

The usb-host driver has a bunch of properties to specify the device
which should be passed to the guest:

  hostbus=<nr> -- Specifies the bus number the device must be attached
  to.

  hostaddr=<nr> -- Specifies the device address the device got
  assigned by the guest os.

  hostport=<str> -- Specifies the physical port the device is attached
  to.

  vendorid=<hexnr> -- Specifies the vendor ID of the device.
  productid=<hexnr> -- Specifies the product ID of the device.

In theory you can combine all these properties as you like.  In
practice only a few combinations are useful:

  (1) vendorid+productid -- match for a specific device, pass it to
      the guest when it shows up somewhere in the host.

  (2) hostbus+hostport -- match for a specific physical port in the
      host, any device which is plugged in there gets passed to the
      guest.

  (3) hostbus+hostaddr -- most useful for ad-hoc pass through as the
      hostaddr isn't stable, the next time you plug in the device it
      gets a new one ...

Note that USB 1.1 devices are handled by UHCI/OHCI and USB 2.0 by
EHCI.  That means a device plugged into the very same physical port
may show up on different buses depending on the speed.  The port I'm
using for testing is bus 1 + port 1 for 2.0 devices and bus 3 + port 1
for 1.1 devices.  Passing through any device plugged into that port
and also assign them to the correct bus can be done this way:

    qemu -M pc ${otheroptions}                               \
        -usb                                                 \
        -device usb-ehci,id=ehci                             \
        -device usb-host,bus=usb-bus.0,hostbus=3,hostport=1  \
        -device usb-host,bus=ehci.0,hostbus=1,hostport=1

enjoy,
  Gerd

--
Gerd Hoffmann <kraxel@redhat.com>