diff options
Diffstat (limited to 'qemu/docs/usb2.txt')
| -rw-r--r-- | qemu/docs/usb2.txt | 161 |
1 files changed, 0 insertions, 161 deletions
diff --git a/qemu/docs/usb2.txt b/qemu/docs/usb2.txt deleted file mode 100644 index c7a445afc..000000000 --- a/qemu/docs/usb2.txt +++ /dev/null @@ -1,161 +0,0 @@ - -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-bus.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-bus.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. - - -xhci controller support ------------------------ - -There is also xhci host controller support available. It got a lot -less testing than ehci and there are a bunch of known limitations, so -ehci may work better for you. On the other hand the xhci hardware -design is much more virtualization-friendly, thus xhci emulation uses -less resources (especially cpu). If you want to give xhci a try -use this to add the host controller ... - - qemu -device nec-usb-xhci,id=xhci - -... then use "bus=xhci.0" when assigning usb devices. - - -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-bus.0,port=1 - -Plugging a hub into UHCI port 2 works like this: - - -device usb-hub,bus=usb-bus.0,port=2 - -Plugging a virtual usb stick into port 4 of the hub just plugged works -this way: - - -device usb-storage,bus=usb-bus.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-bus.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-bus.0,hostbus=3,hostport=1 \ - -device usb-host,bus=ehci.0,hostbus=1,hostport=1 - -enjoy, - Gerd - --- -Gerd Hoffmann <kraxel@redhat.com> |