docs/usb2.txt

   1
   2 USB 2.0 Quick Start
   3 ===================
   4
   5 The QEMU EHCI Adapter does *not* support companion controllers.  That
   6 implies there are two completely separate USB busses: One USB 1.1 bus
   7 driven by the UHCI controller and one USB 2.0 bus driven by the EHCI
   8 controller.  Devices must be attached to the correct controller
   9 manually.
  10
  11 The '-usb' switch will make qemu create the UHCI controller as part of
  12 the PIIX3 chipset.  The USB 1.1 bus will carry the name "usb.0".
  13
  14 You can use the standard -device switch to add a EHCI controller to
  15 your virtual machine.  It is strongly recommended to specify an ID for
  16 the controller so the USB 2.0 bus gets a individual name, for example
  17 '-device usb-ehci,id=ehci".  This will give you a USB 2.0 bus named
  18 "ehci.0".
  19
  20 I strongly recomment to also use -device to attach usb devices because
  21 you can specify the bus they should be attached to this way.  Here is
  22 a complete example:
  23
  24     qemu -M pc ${otheroptions}                           \
  25         -drive if=none,id=usbstick,file=/path/to/image   \
  26         -usb                                             \
  27         -device usb-ehci,id=ehci                         \
  28         -device usb-tablet,bus=usb.0                     \
  29         -device usb-storage,bus=ehci.0,drive=usbstick
  30
  31 This attaches a usb tablet to the UHCI adapter and a usb mass storage
  32 device to the EHCI adapter.
  33
  34
  35 More USB tips & tricks
  36 ======================
  37
  38 Recently the usb pass through driver (also known as usb-host) and the
  39 qemu usb subsystem gained a few capabilities which are available only
  40 via qdev properties, i,e. when using '-device'.
  41
  42
  43 physical port addressing
  44 ------------------------
  45
  46 First you can (for all usb devices) specify the physical port where
  47 the device will show up in the guest.  This can be done using the
  48 "port" property.  UHCI has two root ports (1,2).  EHCI has four root
  49 ports (1-4), the emulated (1.1) USB hub has eight ports.
  50
  51 Plugging a tablet into UHCI port 1 works like this:
  52
  53         -device usb-tablet,bus=usb.0,port=1
  54
  55 Plugging a hub into UHCI port 2 works like this:
  56
  57         -device usb-hub,bus=usb.0,port=2
  58
  59 Plugging a virtual usb stick into port 4 of the hub just plugged works
  60 this way:
  61
  62         -device usb-storage,bus=usb.0,port=2.4,drive=...
  63
  64 You can do basically the same in the monitor using the device_add
  65 command.  If you want to unplug devices too you should specify some
  66 unique id which you can use to refer to the device ...
  67
  68         (qemu) device_add usb-tablet,bus=usb.0,port=1,id=my-tablet
  69         (qemu) device_del my-tablet
  70
  71 ... when unplugging it with device_del.
  72
  73
  74 USB pass through hints
  75 ----------------------
  76
  77 The usb-host driver has a bunch of properties to specify the device
  78 which should be passed to the guest:
  79
  80   hostbus=<nr> -- Specifies the bus number the device must be attached
  81   to.
  82
  83   hostaddr=<nr> -- Specifies the device address the device got
  84   assigned by the guest os.
  85
  86   hostport=<str> -- Specifies the physical port the device is attached
  87   to.
  88
  89   vendorid=<hexnr> -- Specifies the vendor ID of the device.
  90   productid=<hexnr> -- Specifies the product ID of the device.
  91
  92 In theory you can combine all these properties as you like.  In
  93 practice only a few combinations are useful:
  94
  95   (1) vendorid+productid -- match for a specific device, pass it to
  96       the guest when it shows up somewhere in the host.
  97
  98   (2) hostbus+hostport -- match for a specific physical port in the
  99       host, any device which is plugged in there gets passed to the
 100       guest.
 101
 102   (3) hostbus+hostaddr -- most useful for ad-hoc pass through as the
 103       hostaddr isn't stable, the next time you plug in the device it
 104       gets a new one ...
 105
 106 Note that USB 1.1 devices are handled by UHCI/OHCI and USB 2.0 by
 107 EHCI.  That means a device plugged into the very same physical port
 108 may show up on different busses depending on the speed.  The port I'm
 109 using for testing is bus 1 + port 1 for 2.0 devices and bus 3 + port 1
 110 for 1.1 devices.  Passing through any device plugged into that port
 111 and also assign them to the correct bus can be done this way:
 112
 113     qemu -M pc ${otheroptions}                           \
 114         -usb                                             \
 115         -device usb-ehci,id=ehci                         \
 116         -device usb-host,bus=usb.0,hostbus=3,hostport=1  \
 117         -device usb-host,bus=ehci.0,hostbus=1,hostport=1
 118
 119 enjoy,
 120   Gerd
 121
 122 --
 123 Gerd Hoffmann <kraxel@redhat.com>