]>
Commit | Line | Data |
---|---|---|
94527ead GH |
1 | |
2 | USB 2.0 Quick Start | |
3 | =================== | |
4 | ||
5 | The QEMU EHCI Adapter does *not* support companion controllers. That | |
6 | implies there are two completely separate USB busses: One USB 1.1 bus | |
7 | driven by the UHCI controller and one USB 2.0 bus driven by the EHCI | |
8 | controller. Devices must be attached to the correct controller | |
9 | manually. | |
10 | ||
11 | The '-usb' switch will make qemu create the UHCI controller as part of | |
12 | the PIIX3 chipset. The USB 1.1 bus will carry the name "usb.0". | |
13 | ||
14 | You can use the standard -device switch to add a EHCI controller to | |
15 | your virtual machine. It is strongly recommended to specify an ID for | |
16 | the controller so the USB 2.0 bus gets a individual name, for example | |
17 | '-device usb-ehci,id=ehci". This will give you a USB 2.0 bus named | |
18 | "ehci.0". | |
19 | ||
20 | I strongly recomment to also use -device to attach usb devices because | |
21 | you can specify the bus they should be attached to this way. Here is | |
22 | a complete example: | |
23 | ||
24 | qemu -M pc ${otheroptions} \ | |
25 | -drive if=none,id=usbstick,file=/path/to/image \ | |
26 | -usb \ | |
27 | -device usb-ehci,id=ehci \ | |
28 | -device usb-tablet,bus=usb.0 \ | |
29 | -device usb-storage,bus=ehci.0,drive=usbstick | |
30 | ||
31 | This attaches a usb tablet to the UHCI adapter and a usb mass storage | |
32 | device to the EHCI adapter. | |
33 | ||
f72e502e GH |
34 | |
35 | More USB tips & tricks | |
36 | ====================== | |
37 | ||
38 | Recently the usb pass through driver (also known as usb-host) and the | |
39 | qemu usb subsystem gained a few capabilities which are available only | |
40 | via qdev properties, i,e. when using '-device'. | |
41 | ||
42 | ||
43 | physical port addressing | |
44 | ------------------------ | |
45 | ||
46 | First you can (for all usb devices) specify the physical port where | |
47 | the device will show up in the guest. This can be done using the | |
48 | "port" property. UHCI has two root ports (1,2). EHCI has four root | |
49 | ports (1-4), the emulated (1.1) USB hub has eight ports. | |
50 | ||
51 | Plugging a tablet into UHCI port 1 works like this: | |
52 | ||
53 | -device usb-tablet,bus=usb.0,port=1 | |
54 | ||
55 | Plugging a hub into UHCI port 2 works like this: | |
56 | ||
57 | -device usb-hub,bus=usb.0,port=2 | |
58 | ||
59 | Plugging a virtual usb stick into port 4 of the hub just plugged works | |
60 | this way: | |
61 | ||
62 | -device usb-storage,bus=usb.0,port=2.4,drive=... | |
63 | ||
64 | You can do basically the same in the monitor using the device_add | |
65 | command. If you want to unplug devices too you should specify some | |
66 | unique id which you can use to refer to the device ... | |
67 | ||
68 | (qemu) device_add usb-tablet,bus=usb.0,port=1,id=my-tablet | |
69 | (qemu) device_del my-tablet | |
70 | ||
71 | ... when unplugging it with device_del. | |
72 | ||
73 | ||
74 | USB pass through hints | |
75 | ---------------------- | |
76 | ||
77 | The usb-host driver has a bunch of properties to specify the device | |
78 | which should be passed to the guest: | |
79 | ||
80 | hostbus=<nr> -- Specifies the bus number the device must be attached | |
81 | to. | |
82 | ||
83 | hostaddr=<nr> -- Specifies the device address the device got | |
84 | assigned by the guest os. | |
85 | ||
86 | hostport=<str> -- Specifies the physical port the device is attached | |
87 | to. | |
88 | ||
89 | vendorid=<hexnr> -- Specifies the vendor ID of the device. | |
90 | productid=<hexnr> -- Specifies the product ID of the device. | |
91 | ||
92 | In theory you can combine all these properties as you like. In | |
93 | practice only a few combinations are useful: | |
94 | ||
95 | (1) vendorid+productid -- match for a specific device, pass it to | |
96 | the guest when it shows up somewhere in the host. | |
97 | ||
98 | (2) hostbus+hostport -- match for a specific physical port in the | |
99 | host, any device which is plugged in there gets passed to the | |
100 | guest. | |
101 | ||
102 | (3) hostbus+hostaddr -- most useful for ad-hoc pass through as the | |
103 | hostaddr isn't stable, the next time you plug in the device it | |
104 | gets a new one ... | |
105 | ||
106 | Note that USB 1.1 devices are handled by UHCI/OHCI and USB 2.0 by | |
107 | EHCI. That means a device plugged into the very same physical port | |
108 | may show up on different busses depending on the speed. The port I'm | |
109 | using for testing is bus 1 + port 1 for 2.0 devices and bus 3 + port 1 | |
110 | for 1.1 devices. Passing through any device plugged into that port | |
111 | and also assign them to the correct bus can be done this way: | |
112 | ||
113 | qemu -M pc ${otheroptions} \ | |
114 | -usb \ | |
115 | -device usb-ehci,id=ehci \ | |
116 | -device usb-host,bus=usb.0,hostbus=3,hostport=1 \ | |
117 | -device usb-host,bus=ehci.0,hostbus=1,hostport=1 | |
118 | ||
94527ead GH |
119 | enjoy, |
120 | Gerd | |
121 | ||
122 | -- | |
123 | Gerd Hoffmann <kraxel@redhat.com> |