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