Update version for v3.1.0-rc5 release
[qemu.git] / docs / usb2.txt
1
2 USB Quick Start
3 ===============
4
5 XHCI controller support
6 -----------------------
7
8 QEMU has XHCI host adapter support.  The XHCI hardware design is much
9 more virtualization-friendly when compared to EHCI and UHCI, thus XHCI
10 emulation uses less resources (especially cpu).  So if your guest
11 supports XHCI (which should be the case for any operating system
12 released around 2010 or later) we recommend using it:
13
14     qemu -device qemu-xhci
15
16 XHCI supports USB 1.1, USB 2.0 and USB 3.0 devices, so this is the
17 only controller you need.  With only a single USB controller (and
18 therefore only a single USB bus) present in the system there is no
19 need to use the bus= parameter when adding USB devices.
20
21
22 EHCI controller support
23 -----------------------
24
25 The QEMU EHCI Adapter supports USB 2.0 devices.  It can be used either
26 standalone or with companion controllers (UHCI, OHCI) for USB 1.1
27 devices.  The companion controller setup is more convenient to use
28 because it provides a single USB bus supporting both USB 2.0 and USB
29 1.1 devices.  See next section for details.
30
31 When running EHCI in standalone mode you can add UHCI or OHCI
32 controllers for USB 1.1 devices too.  Each controller creates its own
33 bus though, so there are two completely separate USB buses: One USB
34 1.1 bus driven by the UHCI controller and one USB 2.0 bus driven by
35 the EHCI controller.  Devices must be attached to the correct
36 controller manually.
37
38 The easiest way to add a UHCI controller to a 'pc' machine is the
39 '-usb' switch.  QEMU will create the UHCI controller as function of
40 the PIIX3 chipset.  The USB 1.1 bus will carry the name "usb-bus.0".
41
42 You can use the standard -device switch to add a EHCI controller to
43 your virtual machine.  It is strongly recommended to specify an ID for
44 the controller so the USB 2.0 bus gets an individual name, for example
45 '-device usb-ehci,id=ehci".  This will give you a USB 2.0 bus named
46 "ehci.0".
47
48 When adding USB devices using the -device switch you can specify the
49 bus they should be attached to.  Here is a complete example:
50
51     qemu -M pc ${otheroptions}                           \
52         -drive if=none,id=usbstick,file=/path/to/image   \
53         -usb                                             \
54         -device usb-ehci,id=ehci                         \
55         -device usb-tablet,bus=usb-bus.0                 \
56         -device usb-storage,bus=ehci.0,drive=usbstick
57
58 This attaches a USB tablet to the UHCI adapter and a USB mass storage
59 device to the EHCI adapter.
60
61
62 Companion controller support
63 ----------------------------
64
65 The UHCI and OHCI controllers can attach to a USB bus created by EHCI
66 as companion controllers.  This is done by specifying the masterbus
67 and firstport properties.  masterbus specifies the bus name the
68 controller should attach to.  firstport specifies the first port the
69 controller should attach to, which is needed as usually one EHCI
70 controller with six ports has three UHCI companion controllers with
71 two ports each.
72
73 There is a config file in docs which will do all this for
74 you, just try ...
75
76     qemu -readconfig docs/config/ich9-ehci-uhci.cfg
77
78 ... then use "bus=ehci.0" to assign your USB devices to that bus.
79
80 Using the '-usb' switch for 'q35' machines will create a similar
81 USB controller configuration.
82
83
84 More USB tips & tricks
85 ======================
86
87 Recently the USB pass through driver (also known as usb-host) and the
88 QEMU USB subsystem gained a few capabilities which are available only
89 via qdev properties, i,e. when using '-device'.
90
91
92 physical port addressing
93 ------------------------
94
95 First you can (for all USB devices) specify the physical port where
96 the device will show up in the guest.  This can be done using the
97 "port" property.  UHCI has two root ports (1,2).  EHCI has six root
98 ports (1-6), the emulated (1.1) USB hub has eight ports.
99
100 Plugging a tablet into UHCI port 1 works like this:
101
102         -device usb-tablet,bus=usb-bus.0,port=1
103
104 Plugging a hub into UHCI port 2 works like this:
105
106         -device usb-hub,bus=usb-bus.0,port=2
107
108 Plugging a virtual USB stick into port 4 of the hub just plugged works
109 this way:
110
111         -device usb-storage,bus=usb-bus.0,port=2.4,drive=...
112
113 You can do basically the same in the monitor using the device_add
114 command.  If you want to unplug devices too you should specify some
115 unique id which you can use to refer to the device ...
116
117         (qemu) device_add usb-tablet,bus=usb-bus.0,port=1,id=my-tablet
118         (qemu) device_del my-tablet
119
120 ... when unplugging it with device_del.
121
122
123 USB pass through hints
124 ----------------------
125
126 The usb-host driver has a bunch of properties to specify the device
127 which should be passed to the guest:
128
129   hostbus=<nr> -- Specifies the bus number the device must be attached
130   to.
131
132   hostaddr=<nr> -- Specifies the device address the device got
133   assigned by the guest os.
134
135   hostport=<str> -- Specifies the physical port the device is attached
136   to.
137
138   vendorid=<hexnr> -- Specifies the vendor ID of the device.
139   productid=<hexnr> -- Specifies the product ID of the device.
140
141 In theory you can combine all these properties as you like.  In
142 practice only a few combinations are useful:
143
144   (1) vendorid+productid -- match for a specific device, pass it to
145       the guest when it shows up somewhere in the host.
146
147   (2) hostbus+hostport -- match for a specific physical port in the
148       host, any device which is plugged in there gets passed to the
149       guest.
150
151   (3) hostbus+hostaddr -- most useful for ad-hoc pass through as the
152       hostaddr isn't stable, the next time you plug in the device it
153       gets a new one ...
154
155 Note that USB 1.1 devices are handled by UHCI/OHCI and USB 2.0 by
156 EHCI.  That means a device plugged into the very same physical port
157 may show up on different buses depending on the speed.  The port I'm
158 using for testing is bus 1 + port 1 for 2.0 devices and bus 3 + port 1
159 for 1.1 devices.  Passing through any device plugged into that port
160 and also assign them to the correct bus can be done this way:
161
162     qemu -M pc ${otheroptions}                               \
163         -usb                                                 \
164         -device usb-ehci,id=ehci                             \
165         -device usb-host,bus=usb-bus.0,hostbus=3,hostport=1  \
166         -device usb-host,bus=ehci.0,hostbus=1,hostport=1
167
168 enjoy,
169   Gerd
170
171 --
172 Gerd Hoffmann <kraxel@redhat.com>