import

qemu/docs/usb2.txt

@@ -0,0 +1,161 @@
+
+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>