| |
| USB 2.0 Quick Start |
| =================== |
| |
| The QEMU EHCI Adapter can be used with and without companion |
| controllers. See below for the companion controller mode. |
| |
| When not running in companion controller mode there are two completely |
| separate USB busses: One USB 1.1 bus driven by the UHCI controller and |
| one USB 2.0 bus driven by the EHCI controller. Devices must be |
| attached to the correct controller manually. |
| |
| The '-usb' switch will make qemu create the UHCI controller as part of |
| the PIIX3 chipset. The USB 1.1 bus will carry the name "usb.0". |
| |
| You can use the standard -device switch to add a EHCI controller to |
| your virtual machine. It is strongly recommended to specify an ID for |
| the controller so the USB 2.0 bus gets a individual name, for example |
| '-device usb-ehci,id=ehci". This will give you a USB 2.0 bus named |
| "ehci.0". |
| |
| I strongly recomment to also use -device to attach usb devices because |
| you can specify the bus they should be attached to this way. Here is |
| a complete example: |
| |
| qemu -M pc ${otheroptions} \ |
| -drive if=none,id=usbstick,file=/path/to/image \ |
| -usb \ |
| -device usb-ehci,id=ehci \ |
| -device usb-tablet,bus=usb.0 \ |
| -device usb-storage,bus=ehci.0,drive=usbstick |
| |
| This attaches a usb tablet to the UHCI adapter and a usb mass storage |
| device to the EHCI adapter. |
| |
| |
| Companion controller support |
| ---------------------------- |
| |
| Companion controller support has been added recently. The operational |
| model described above with two completely separate busses still works |
| fine. Additionally the UHCI and OHCI controllers got the ability to |
| attach to a usb bus created by EHCI as companion controllers. This is |
| done by specifying the masterbus and firstport properties. masterbus |
| specifies the bus name the controller should attach to. firstport |
| specifies the first port the controller should attach to, which is |
| needed as usually one ehci controller with six ports has three uhci |
| companion controllers with two ports each. |
| |
| There is a config file in docs which will do all this for you, just |
| try ... |
| |
| qemu -readconfig docs/ich9-ehci-uhci.cfg |
| |
| ... then use "bus=ehci.0" to assign your usb devices to that bus. |
| |
| |
| More USB tips & tricks |
| ====================== |
| |
| Recently the usb pass through driver (also known as usb-host) and the |
| qemu usb subsystem gained a few capabilities which are available only |
| via qdev properties, i,e. when using '-device'. |
| |
| |
| physical port addressing |
| ------------------------ |
| |
| First you can (for all usb devices) specify the physical port where |
| the device will show up in the guest. This can be done using the |
| "port" property. UHCI has two root ports (1,2). EHCI has four root |
| ports (1-4), the emulated (1.1) USB hub has eight ports. |
| |
| Plugging a tablet into UHCI port 1 works like this: |
| |
| -device usb-tablet,bus=usb.0,port=1 |
| |
| Plugging a hub into UHCI port 2 works like this: |
| |
| -device usb-hub,bus=usb.0,port=2 |
| |
| Plugging a virtual usb stick into port 4 of the hub just plugged works |
| this way: |
| |
| -device usb-storage,bus=usb.0,port=2.4,drive=... |
| |
| You can do basically the same in the monitor using the device_add |
| command. If you want to unplug devices too you should specify some |
| unique id which you can use to refer to the device ... |
| |
| (qemu) device_add usb-tablet,bus=usb.0,port=1,id=my-tablet |
| (qemu) device_del my-tablet |
| |
| ... when unplugging it with device_del. |
| |
| |
| USB pass through hints |
| ---------------------- |
| |
| The usb-host driver has a bunch of properties to specify the device |
| which should be passed to the guest: |
| |
| hostbus=<nr> -- Specifies the bus number the device must be attached |
| to. |
| |
| hostaddr=<nr> -- Specifies the device address the device got |
| assigned by the guest os. |
| |
| hostport=<str> -- Specifies the physical port the device is attached |
| to. |
| |
| vendorid=<hexnr> -- Specifies the vendor ID of the device. |
| productid=<hexnr> -- Specifies the product ID of the device. |
| |
| In theory you can combine all these properties as you like. In |
| practice only a few combinations are useful: |
| |
| (1) vendorid+productid -- match for a specific device, pass it to |
| the guest when it shows up somewhere in the host. |
| |
| (2) hostbus+hostport -- match for a specific physical port in the |
| host, any device which is plugged in there gets passed to the |
| guest. |
| |
| (3) hostbus+hostaddr -- most useful for ad-hoc pass through as the |
| hostaddr isn't stable, the next time you plug in the device it |
| gets a new one ... |
| |
| Note that USB 1.1 devices are handled by UHCI/OHCI and USB 2.0 by |
| EHCI. That means a device plugged into the very same physical port |
| may show up on different busses depending on the speed. The port I'm |
| using for testing is bus 1 + port 1 for 2.0 devices and bus 3 + port 1 |
| for 1.1 devices. Passing through any device plugged into that port |
| and also assign them to the correct bus can be done this way: |
| |
| qemu -M pc ${otheroptions} \ |
| -usb \ |
| -device usb-ehci,id=ehci \ |
| -device usb-host,bus=usb.0,hostbus=3,hostport=1 \ |
| -device usb-host,bus=ehci.0,hostbus=1,hostport=1 |
| |
| enjoy, |
| Gerd |
| |
| -- |
| Gerd Hoffmann <kraxel@redhat.com> |
