USB emulation in QENU Project

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-system-x86_64 -M pc ${otheroptions}                        \
    -drive if=none,id=usbstick,format=raw,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, which you can use like this:

qemu-system-x86_64 -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.

Physical port addressing

For all the above USB devices, by default QEMU will plug the device into the next available port on the specified USB bus, or onto some available USB bus if you didn’t specify one explicitly. If you need to, you can also 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), and 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=...

In the monitor, the device_add` command also accepts a ``port property specification. If you want to unplug devices too you should specify some unique id which you can use to refer to the device. You can then use device_del to unplug the device later. For example:

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

usb-host properties for specifying the host device

The example above uses the vendorid and productid to specify which host device to pass through, but this is not the only way to specify the host device. usb-host supports the following properties:

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:

• vendorid and productid – match for a specific device, pass it to the guest when it shows up somewhere in the host.
• hostbus and hostport – match for a specific physical port in the host, any device which is plugged in there gets passed to the guest.
• hostbus and hostaddr – most useful for ad-hoc pass through as the hostaddr isn’t stable. The next time you plug the device into the host it will get a new hostaddr.

Note that on the host USB 1.1 devices are handled by UHCI/OHCI and USB 2.0 by EHCI. That means different USB devices plugged into the very same physical port on the host may show up on different host buses depending on the speed. Supposing that devices plugged into a given physical port appear as bus 1 + port 1 for 2.0 devices and bus 3 + port 1 for 1.1 devices, you can pass through any device plugged into that port and also assign it to the correct USB bus in QEMU like this:

qemu-system-x86_64 -M pc [...]                            \
     -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

usb-host properties for reset behavior

The guest-reset and guest-reset-all properties control whenever the guest is allowed to reset the physical usb device on the host. There are three cases:

guest-reset=false

The guest is not allowed to reset the (physical) usb device.

guest-reset=true,guest-resets-all=false

The guest is allowed to reset the device when it is not yet initialized (aka no usb bus address assigned). Usually this results in one guest reset being allowed. This is the default behavior.

guest-reset=true,guest-resets-all=true

The guest is allowed to reset the device as it pleases.

The reason for this existing are broken usb devices. In theory one should be able to reset (and re-initialize) usb devices at any time. In practice that may result in shitty usb device firmware crashing and the device not responding any more until you power-cycle (aka un-plug and re-plug) it.

What works best pretty much depends on the behavior of the specific usb device at hand, so it’s a trial-and-error game. If the default doesn’t work, try another option and see whenever the situation improves.

record usb transfers

All usb devices have support for recording the usb traffic. This can be enabled using the pcap=<file> property, for example:

-device usb-mouse,pcap=mouse.pcap

The pcap files are compatible with the linux kernels usbmon. Many tools, including wireshark, can decode and inspect these trace files.