1.. _pcsys_005fusb: 2 3USB emulation 4------------- 5 6QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can 7plug virtual USB devices or real host USB devices (only works with 8certain host operating systems). QEMU will automatically create and 9connect virtual USB hubs as necessary to connect multiple USB devices. 10 11.. _Connecting USB devices: 12 13Connecting USB devices 14~~~~~~~~~~~~~~~~~~~~~~ 15 16USB devices can be connected with the ``-device usb-...`` command line 17option 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 89Using host USB devices on a Linux host 90~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 91 92WARNING: this is an experimental feature. QEMU will slow down when using 93it. USB devices requiring real time streaming (i.e. USB Video Cameras) 94are not supported yet. 95 961. 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 1012. 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 1093. 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 1174. 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 1285. 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 1376. Now you can try to use the host USB device in QEMU. 138 139When relaunching QEMU, you may have to unplug and plug again the USB 140device to make it work again (this is a bug). 141