]>
Commit | Line | Data |
---|---|---|
94527ead GH |
1 | |
2 | USB 2.0 Quick Start | |
3 | =================== | |
4 | ||
76f30473 GH |
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. | |
94527ead GH |
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 | ||
f72e502e | 36 | |
76f30473 GH |
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 | ||
f72e502e GH |
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 | ||
94527ead GH |
142 | enjoy, |
143 | Gerd | |
144 | ||
145 | -- | |
146 | Gerd Hoffmann <kraxel@redhat.com> |