docs/usb2.txt

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