docs/usb2.txt

   1
   2 USB Quick Start
   3 ===============
   4
   5 XHCI controller support
   6 -----------------------
   7
   8 QEMU has XHCI host adapter support.  The XHCI hardware design is much
   9 more virtualization-friendly when compared to EHCI and UHCI, thus XHCI
  10 emulation uses less resources (especially cpu).  So if your guest
  11 supports XHCI (which should be the case for any operating system
  12 released around 2010 or later) we recommend using it:
  13
  14     qemu -device qemu-xhci
  15
  16 XHCI supports USB 1.1, USB 2.0 and USB 3.0 devices, so this is the
  17 only controller you need.  With only a single USB controller (and
  18 therefore only a single USB bus) present in the system there is no
  19 need to use the bus= parameter when adding USB devices.
  20
  21
  22 EHCI controller support
  23 -----------------------
  24
  25 The QEMU EHCI Adapter supports USB 2.0 devices.  It can be used either
  26 standalone or with companion controllers (UHCI, OHCI) for USB 1.1
  27 devices.  The companion controller setup is more convenient to use
  28 because it provides a single USB bus supporting both USB 2.0 and USB
  29 1.1 devices.  See next section for details.
  30
  31 When running EHCI in standalone mode you can add UHCI or OHCI
  32 controllers for USB 1.1 devices too.  Each controller creates its own
  33 bus though, so there are two completely separate USB buses: One USB
  34 1.1 bus driven by the UHCI controller and one USB 2.0 bus driven by
  35 the EHCI controller.  Devices must be attached to the correct
  36 controller manually.
  37
  38 The easiest way to add a UHCI controller to a 'pc' machine is the
  39 '-usb' switch.  QEMU will create the UHCI controller as function of
  40 the PIIX3 chipset.  The USB 1.1 bus will carry the name "usb-bus.0".
  41
  42 You can use the standard -device switch to add a EHCI controller to
  43 your virtual machine.  It is strongly recommended to specify an ID for
  44 the controller so the USB 2.0 bus gets an individual name, for example
  45 '-device usb-ehci,id=ehci".  This will give you a USB 2.0 bus named
  46 "ehci.0".
  47
  48 When adding USB devices using the -device switch you can specify the
  49 bus they should be attached to.  Here is a complete example:
  50
  51     qemu -M pc ${otheroptions}                           \
  52         -drive if=none,id=usbstick,file=/path/to/image   \
  53         -usb                                             \
  54         -device usb-ehci,id=ehci                         \
  55         -device usb-tablet,bus=usb-bus.0                 \
  56         -device usb-storage,bus=ehci.0,drive=usbstick
  57
  58 This attaches a USB tablet to the UHCI adapter and a USB mass storage
  59 device to the EHCI adapter.
  60
  61
  62 Companion controller support
  63 ----------------------------
  64
  65 The UHCI and OHCI controllers can attach to a USB bus created by EHCI
  66 as companion controllers.  This is done by specifying the masterbus
  67 and firstport properties.  masterbus specifies the bus name the
  68 controller should attach to.  firstport specifies the first port the
  69 controller should attach to, which is needed as usually one EHCI
  70 controller with six ports has three UHCI companion controllers with
  71 two ports each.
  72
  73 There is a config file in docs which will do all this for
  74 you, just try ...
  75
  76     qemu -readconfig docs/config/ich9-ehci-uhci.cfg
  77
  78 ... then use "bus=ehci.0" to assign your USB devices to that bus.
  79
  80 Using the '-usb' switch for 'q35' machines will create a similar
  81 USB controller configuration.
  82
  83
  84 More USB tips & tricks
  85 ======================
  86
  87 Recently the USB pass through driver (also known as usb-host) and the
  88 QEMU USB subsystem gained a few capabilities which are available only
  89 via qdev properties, i,e. when using '-device'.
  90
  91
  92 physical port addressing
  93 ------------------------
  94
  95 First you can (for all USB devices) specify the physical port where
  96 the device will show up in the guest.  This can be done using the
  97 "port" property.  UHCI has two root ports (1,2).  EHCI has six root
  98 ports (1-6), the emulated (1.1) USB hub has eight ports.
  99
 100 Plugging a tablet into UHCI port 1 works like this:
 101
 102         -device usb-tablet,bus=usb-bus.0,port=1
 103
 104 Plugging a hub into UHCI port 2 works like this:
 105
 106         -device usb-hub,bus=usb-bus.0,port=2
 107
 108 Plugging a virtual USB stick into port 4 of the hub just plugged works
 109 this way:
 110
 111         -device usb-storage,bus=usb-bus.0,port=2.4,drive=...
 112
 113 You can do basically the same in the monitor using the device_add
 114 command.  If you want to unplug devices too you should specify some
 115 unique id which you can use to refer to the device ...
 116
 117         (qemu) device_add usb-tablet,bus=usb-bus.0,port=1,id=my-tablet
 118         (qemu) device_del my-tablet
 119
 120 ... when unplugging it with device_del.
 121
 122
 123 USB pass through hints
 124 ----------------------
 125
 126 The usb-host driver has a bunch of properties to specify the device
 127 which should be passed to the guest:
 128
 129   hostbus=<nr> -- Specifies the bus number the device must be attached
 130   to.
 131
 132   hostaddr=<nr> -- Specifies the device address the device got
 133   assigned by the guest os.
 134
 135   hostport=<str> -- Specifies the physical port the device is attached
 136   to.
 137
 138   vendorid=<hexnr> -- Specifies the vendor ID of the device.
 139   productid=<hexnr> -- Specifies the product ID of the device.
 140
 141 In theory you can combine all these properties as you like.  In
 142 practice only a few combinations are useful:
 143
 144   (1) vendorid+productid -- match for a specific device, pass it to
 145       the guest when it shows up somewhere in the host.
 146
 147   (2) hostbus+hostport -- match for a specific physical port in the
 148       host, any device which is plugged in there gets passed to the
 149       guest.
 150
 151   (3) hostbus+hostaddr -- most useful for ad-hoc pass through as the
 152       hostaddr isn't stable, the next time you plug in the device it
 153       gets a new one ...
 154
 155 Note that USB 1.1 devices are handled by UHCI/OHCI and USB 2.0 by
 156 EHCI.  That means a device plugged into the very same physical port
 157 may show up on different buses depending on the speed.  The port I'm
 158 using for testing is bus 1 + port 1 for 2.0 devices and bus 3 + port 1
 159 for 1.1 devices.  Passing through any device plugged into that port
 160 and also assign them to the correct bus can be done this way:
 161
 162     qemu -M pc ${otheroptions}                               \
 163         -usb                                                 \
 164         -device usb-ehci,id=ehci                             \
 165         -device usb-host,bus=usb-bus.0,hostbus=3,hostport=1  \
 166         -device usb-host,bus=ehci.0,hostbus=1,hostport=1
 167
 168 enjoy,
 169   Gerd
 170
 171 --
 172 Gerd Hoffmann <kraxel@redhat.com>