docs/system/usb.rst

   1 .. _pcsys_005fusb:
   2
   3 USB emulation
   4 -------------
   5
   6 QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
   7 plug virtual USB devices or real host USB devices (only works with
   8 certain host operating systems). QEMU will automatically create and
   9 connect virtual USB hubs as necessary to connect multiple USB devices.
  10
  11 .. _Connecting USB devices:
  12
  13 Connecting USB devices
  14 ~~~~~~~~~~~~~~~~~~~~~~
  15
  16 USB devices can be connected with the ``-device usb-...`` command line
  17 option or the ``device_add`` monitor command. Available devices are:
  18
  19 ``usb-mouse``
  20    Virtual Mouse. This will override the PS/2 mouse emulation when
  21    activated.
  22
  23 ``usb-tablet``
  24    Pointer device that uses absolute coordinates (like a touchscreen).
  25    This means QEMU is able to report the mouse position without having
  26    to grab the mouse. Also overrides the PS/2 mouse emulation when
  27    activated.
  28
  29 ``usb-storage,drive=drive_id``
  30    Mass storage device backed by drive_id (see the :ref:`disk images`
  31    chapter in the System Emulation Users Guide)
  32
  33 ``usb-uas``
  34    USB attached SCSI device, see
  35    `usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
  36    for details
  37
  38 ``usb-bot``
  39    Bulk-only transport storage device, see
  40    `usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
  41    for details here, too
  42
  43 ``usb-mtp,rootdir=dir``
  44    Media transfer protocol device, using dir as root of the file tree
  45    that is presented to the guest.
  46
  47 ``usb-host,hostbus=bus,hostaddr=addr``
  48    Pass through the host device identified by bus and addr
  49
  50 ``usb-host,vendorid=vendor,productid=product``
  51    Pass through the host device identified by vendor and product ID
  52
  53 ``usb-wacom-tablet``
  54    Virtual Wacom PenPartner tablet. This device is similar to the
  55    ``tablet`` above but it can be used with the tslib library because in
  56    addition to touch coordinates it reports touch pressure.
  57
  58 ``usb-kbd``
  59    Standard USB keyboard. Will override the PS/2 keyboard (if present).
  60
  61 ``usb-serial,chardev=id``
  62    Serial converter. This emulates an FTDI FT232BM chip connected to
  63    host character device id.
  64
  65 ``usb-braille,chardev=id``
  66    Braille device. This will use BrlAPI to display the braille output on
  67    a real or fake device referenced by id.
  68
  69 ``usb-net[,netdev=id]``
  70    Network adapter that supports CDC ethernet and RNDIS protocols. id
  71    specifies a netdev defined with ``-netdev …,id=id``. For instance,
  72    user-mode networking can be used with
  73
  74    .. parsed-literal::
  75
  76       |qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0
  77
  78 ``usb-ccid``
  79    Smartcard reader device
  80
  81 ``usb-audio``
  82    USB audio device
  83
  84 ``u2f-{emulated,passthru}``
  85    Universal Second Factor device
  86
  87 .. _host_005fusb_005fdevices:
  88
  89 Using host USB devices on a Linux host
  90 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  91
  92 WARNING: this is an experimental feature. QEMU will slow down when using
  93 it. USB devices requiring real time streaming (i.e. USB Video Cameras)
  94 are not supported yet.
  95
  96 1. If you use an early Linux 2.4 kernel, verify that no Linux driver is
  97    actually using the USB device. A simple way to do that is simply to
  98    disable the corresponding kernel module by renaming it from
  99    ``mydriver.o`` to ``mydriver.o.disabled``.
 100
 101 2. Verify that ``/proc/bus/usb`` is working (most Linux distributions
 102    should enable it by default). You should see something like that:
 103
 104    ::
 105
 106       ls /proc/bus/usb
 107       001  devices  drivers
 108
 109 3. Since only root can access to the USB devices directly, you can
 110    either launch QEMU as root or change the permissions of the USB
 111    devices you want to use. For testing, the following suffices:
 112
 113    ::
 114
 115       chown -R myuid /proc/bus/usb
 116
 117 4. Launch QEMU and do in the monitor:
 118
 119    ::
 120
 121       info usbhost
 122         Device 1.2, speed 480 Mb/s
 123           Class 00: USB device 1234:5678, USB DISK
 124
 125    You should see the list of the devices you can use (Never try to use
 126    hubs, it won't work).
 127
 128 5. Add the device in QEMU by using:
 129
 130    ::
 131
 132       device_add usb-host,vendorid=0x1234,productid=0x5678
 133
 134    Normally the guest OS should report that a new USB device is plugged.
 135    You can use the option ``-device usb-host,...`` to do the same.
 136
 137 6. Now you can try to use the host USB device in QEMU.
 138
 139 When relaunching QEMU, you may have to unplug and plug again the USB
 140 device to make it work again (this is a bug).