5
The QEMU EHCI Adapter can be used with and without companion
6
controllers. See below for the companion controller mode.
8
When not running in companion controller mode there are two completely
9
separate USB busses: One USB 1.1 bus driven by the UHCI controller and
10
one USB 2.0 bus driven by the EHCI controller. Devices must be
11
attached to the correct controller manually.
13
The '-usb' switch will make qemu create the UHCI controller as part of
14
the PIIX3 chipset. The USB 1.1 bus will carry the name "usb.0".
16
You can use the standard -device switch to add a EHCI controller to
17
your virtual machine. It is strongly recommended to specify an ID for
18
the controller so the USB 2.0 bus gets a individual name, for example
19
'-device usb-ehci,id=ehci". This will give you a USB 2.0 bus named
22
I strongly recomment to also use -device to attach usb devices because
23
you can specify the bus they should be attached to this way. Here is
26
qemu -M pc ${otheroptions} \
27
-drive if=none,id=usbstick,file=/path/to/image \
29
-device usb-ehci,id=ehci \
30
-device usb-tablet,bus=usb.0 \
31
-device usb-storage,bus=ehci.0,drive=usbstick
33
This attaches a usb tablet to the UHCI adapter and a usb mass storage
34
device to the EHCI adapter.
37
Companion controller support
38
----------------------------
40
Companion controller support has been added recently. The operational
41
model described above with two completely separate busses still works
42
fine. Additionally the UHCI and OHCI controllers got the ability to
43
attach to a usb bus created by EHCI as companion controllers. This is
44
done by specifying the masterbus and firstport properties. masterbus
45
specifies the bus name the controller should attach to. firstport
46
specifies the first port the controller should attach to, which is
47
needed as usually one ehci controller with six ports has three uhci
48
companion controllers with two ports each.
50
There is a config file in docs which will do all this for you, just
53
qemu -readconfig docs/ich9-ehci-uhci.cfg
55
... then use "bus=ehci.0" to assign your usb devices to that bus.
58
More USB tips & tricks
59
======================
61
Recently the usb pass through driver (also known as usb-host) and the
62
qemu usb subsystem gained a few capabilities which are available only
63
via qdev properties, i,e. when using '-device'.
66
physical port addressing
67
------------------------
69
First you can (for all usb devices) specify the physical port where
70
the device will show up in the guest. This can be done using the
71
"port" property. UHCI has two root ports (1,2). EHCI has four root
72
ports (1-4), the emulated (1.1) USB hub has eight ports.
74
Plugging a tablet into UHCI port 1 works like this:
76
-device usb-tablet,bus=usb.0,port=1
78
Plugging a hub into UHCI port 2 works like this:
80
-device usb-hub,bus=usb.0,port=2
82
Plugging a virtual usb stick into port 4 of the hub just plugged works
85
-device usb-storage,bus=usb.0,port=2.4,drive=...
87
You can do basically the same in the monitor using the device_add
88
command. If you want to unplug devices too you should specify some
89
unique id which you can use to refer to the device ...
91
(qemu) device_add usb-tablet,bus=usb.0,port=1,id=my-tablet
92
(qemu) device_del my-tablet
94
... when unplugging it with device_del.
97
USB pass through hints
98
----------------------
100
The usb-host driver has a bunch of properties to specify the device
101
which should be passed to the guest:
103
hostbus=<nr> -- Specifies the bus number the device must be attached
106
hostaddr=<nr> -- Specifies the device address the device got
107
assigned by the guest os.
109
hostport=<str> -- Specifies the physical port the device is attached
112
vendorid=<hexnr> -- Specifies the vendor ID of the device.
113
productid=<hexnr> -- Specifies the product ID of the device.
115
In theory you can combine all these properties as you like. In
116
practice only a few combinations are useful:
118
(1) vendorid+productid -- match for a specific device, pass it to
119
the guest when it shows up somewhere in the host.
121
(2) hostbus+hostport -- match for a specific physical port in the
122
host, any device which is plugged in there gets passed to the
125
(3) hostbus+hostaddr -- most useful for ad-hoc pass through as the
126
hostaddr isn't stable, the next time you plug in the device it
129
Note that USB 1.1 devices are handled by UHCI/OHCI and USB 2.0 by
130
EHCI. That means a device plugged into the very same physical port
131
may show up on different busses depending on the speed. The port I'm
132
using for testing is bus 1 + port 1 for 2.0 devices and bus 3 + port 1
133
for 1.1 devices. Passing through any device plugged into that port
134
and also assign them to the correct bus can be done this way:
136
qemu -M pc ${otheroptions} \
138
-device usb-ehci,id=ehci \
139
-device usb-host,bus=usb.0,hostbus=3,hostport=1 \
140
-device usb-host,bus=ehci.0,hostbus=1,hostport=1
146
Gerd Hoffmann <kraxel@redhat.com>
added
removed
docs/usb2.txt
