root / docs / usb2.txt @ 2542bfd5
History | View | Annotate | Download (5.2 kB)
1 |
|
---|---|
2 |
USB 2.0 Quick Start |
3 |
=================== |
4 |
|
5 |
The QEMU EHCI Adapter can be used with and without companion |
6 |
controllers. See below for the companion controller mode. |
7 |
|
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. |
12 |
|
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". |
15 |
|
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 |
20 |
"ehci.0". |
21 |
|
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 |
24 |
a complete example: |
25 |
|
26 |
qemu -M pc ${otheroptions} \ |
27 |
-drive if=none,id=usbstick,file=/path/to/image \ |
28 |
-usb \ |
29 |
-device usb-ehci,id=ehci \ |
30 |
-device usb-tablet,bus=usb.0 \ |
31 |
-device usb-storage,bus=ehci.0,drive=usbstick |
32 |
|
33 |
This attaches a usb tablet to the UHCI adapter and a usb mass storage |
34 |
device to the EHCI adapter. |
35 |
|
36 |
|
37 |
Companion controller support |
38 |
---------------------------- |
39 |
|
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. |
49 |
|
50 |
There is a config file in docs which will do all this for you, just |
51 |
try ... |
52 |
|
53 |
qemu -readconfig docs/ich9-ehci-uhci.cfg |
54 |
|
55 |
... then use "bus=ehci.0" to assign your usb devices to that bus. |
56 |
|
57 |
|
58 |
More USB tips & tricks |
59 |
====================== |
60 |
|
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'. |
64 |
|
65 |
|
66 |
physical port addressing |
67 |
------------------------ |
68 |
|
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. |
73 |
|
74 |
Plugging a tablet into UHCI port 1 works like this: |
75 |
|
76 |
-device usb-tablet,bus=usb.0,port=1 |
77 |
|
78 |
Plugging a hub into UHCI port 2 works like this: |
79 |
|
80 |
-device usb-hub,bus=usb.0,port=2 |
81 |
|
82 |
Plugging a virtual usb stick into port 4 of the hub just plugged works |
83 |
this way: |
84 |
|
85 |
-device usb-storage,bus=usb.0,port=2.4,drive=... |
86 |
|
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 ... |
90 |
|
91 |
(qemu) device_add usb-tablet,bus=usb.0,port=1,id=my-tablet |
92 |
(qemu) device_del my-tablet |
93 |
|
94 |
... when unplugging it with device_del. |
95 |
|
96 |
|
97 |
USB pass through hints |
98 |
---------------------- |
99 |
|
100 |
The usb-host driver has a bunch of properties to specify the device |
101 |
which should be passed to the guest: |
102 |
|
103 |
hostbus=<nr> -- Specifies the bus number the device must be attached |
104 |
to. |
105 |
|
106 |
hostaddr=<nr> -- Specifies the device address the device got |
107 |
assigned by the guest os. |
108 |
|
109 |
hostport=<str> -- Specifies the physical port the device is attached |
110 |
to. |
111 |
|
112 |
vendorid=<hexnr> -- Specifies the vendor ID of the device. |
113 |
productid=<hexnr> -- Specifies the product ID of the device. |
114 |
|
115 |
In theory you can combine all these properties as you like. In |
116 |
practice only a few combinations are useful: |
117 |
|
118 |
(1) vendorid+productid -- match for a specific device, pass it to |
119 |
the guest when it shows up somewhere in the host. |
120 |
|
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 |
123 |
guest. |
124 |
|
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 |
127 |
gets a new one ... |
128 |
|
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: |
135 |
|
136 |
qemu -M pc ${otheroptions} \ |
137 |
-usb \ |
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 |
141 |
|
142 |
enjoy, |
143 |
Gerd |
144 |
|
145 |
-- |
146 |
Gerd Hoffmann <kraxel@redhat.com> |