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