Feature functional description

This feature is about providing virtual USB devices to guests. For passing through real USB hardware from the host, see UsbPassthrough.

qemu provides three different USB controllers that can be used:

PIIX3 UHCI controller (called piix3-usb-uhci, default on PC)
PIIX4 UHCI controller (called piix4-usb-uhci)
Apple OHCI controller (called pci-ohci)

It provides a bunch of virtual USB devices. To see all of the devices built into your qemu binary, run qemu -device ? and look for entries with a "bus USB" on them. The most interesting ones are probably:

USB tablet (called usb-tablet): Provides an absolute pointer device which often helps with getting a consistent mouse cursor position in VNC.
USB disk (called usb-storage)
Keyboard (usb-kbd) and mouse (usb-mouse)

Detailed

Building

When building qemu for x86_64-softmmu with default options, you get all of the mentioned devices with the expection of OHCI. To build it, add the following line to x86_64-softmmu/config-devices.mak before running make:

CONFIG_USB_OHCI = y

Running

To be able to use USB at all, you need to start qemu with a USB controller. If you use the legacy -usb and -usbdevice options, you will automatically get a piix3-usb-uhci for PCs unless you specify something else. The new method works like this:

qemu-system-x86_64 -device piix3-usb-uhci ...

Do the same for any USB devices that you want to be present from start. Some of them need some more options, like in the following example for a USB disk:

qemu-system-x86_64 -device piix3-usb-uhci \
    -drive id=my_usb_disk,file=usbdisk.img,if=none \
    -device usb-storage,drive=my_usb_disk

Hotplugging

Just like in real hardware, USB allows hotplugging. You can use the monitor commands device_add and device_del to attach a new device or remove a previously attached one. For device_add, use the same format as for -device. Attaching a new USB disk would look like this:

(qemu) drive_add 0 id=my_usb_disk,if=none,file=usbdisk.img
OK
(qemu) device_add usb-storage,id=my_usb_disk,drive=my_usb_disk

For removing the disk you need the ID that you have assigned in the device_add call:

(qemu) device_del my_usb_disk

Test cases

The following sections describe test cases to verify correct function of the USB emulation in qemu. Each of the test cases should be run with multiple guest OSes. Consider variation of the USB host controller, though piix3-usb-uhci is the most important one for PCs.

Basic usage

This sections contains test cases which only consider coldplugged USB devices.

Input devices

Keyboard: Type a few lines to see if there is any unexpected behaviour like missing or additional characters, or if the keymap is wrong. This can be tested both in different OSes with a proper USB HID driver and in DOS or bootloaders like GRUB (testing the PS/2 keyboard emulation).
Pointer devices (usb-mouse, usb-tablet and usb-wacom-tablet): Can the mouse cursor be moved? Do all three buttons work? Does the mouse wheel work?

USB disks

Attach a raw image as a USB disk to the VM (no filesystem needed on it). Write some data to it and get the md5sum in the guest. Compare it to the md5sum of the image on the host.

Hotplugging devices

Basic hotplugging

Attach a USB disk during runtime and check if it's accessible by the OS. You can run the same test as for coldplugged USB disks.
Detach the USB disk and check if the OS correctly detects this.

Unusual numbers of input devices

What happens if the keyboard is unplugged and you type some text? Expected result is that nothing happens. After re-attaching an usb-kbd, it should be possible again to enter text.
Same test with unplugging and re-attaching the pointer device.
What happens with multiple keyboards or pointer devices attached? Expected result is that inputs are passed to one of the attached device (e.g. no duplicate characters). After removing the first keyboard, inputs should be directed to the keyboard that was attached later (i.e. you should still be able to input text as long as at least one keyboard is attached).

Repeated hotplug/unplug

Attach 15 USB devices to the VM. USB hubs should automatically be added (check with info qtree in the monitor)
Attach a USB device and detach it. Repeat this for a large number of iterations (probably best to do using a shell script). Check if no devices are left in the end and if the OS's USB driver is still fine (check dmesg, for example)
Attach 15 USB devices and detach them again. Repeat this. Are automatically created hubs reused or are new hubs created each time?