-USB 2.0 Quick Start
-===================
+USB Quick Start
+===============
-The QEMU EHCI Adapter does *not* support companion controllers. That
-implies 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.
+XHCI controller support
+-----------------------
-The '-usb' switch will make qemu create the UHCI controller as part of
-the PIIX3 chipset. The USB 1.1 bus will carry the name "usb.0".
+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 a individual name, for example
+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".
-I strongly recomment to also use -device to attach usb devices because
-you can specify the bus they should be attached to this way. Here is
-a complete example:
+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.0 \
+ -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
+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
+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
+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 four root
-ports (1-4), the emulated (1.1) USB hub has eight ports.
+"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.0,port=1
+ -device usb-tablet,bus=usb-bus.0,port=1
Plugging a hub into UHCI port 2 works like this:
- -device usb-hub,bus=usb.0,port=2
+ -device usb-hub,bus=usb-bus.0,port=2
-Plugging a virtual usb stick into port 4 of the hub just plugged works
+Plugging a virtual USB stick into port 4 of the hub just plugged works
this way:
- -device usb-storage,bus=usb.0,port=2.4,drive=...
+ -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.0,port=1,id=my-tablet
+ (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.
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 busses depending on the speed. The port I'm
+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.0,hostbus=3,hostport=1 \
+ 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,
projects / mirror_qemu.git / blobdiff