docs/system/usb.texi

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