.. _pcsys_005fusb: USB emulation ------------- QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can plug virtual USB devices or real host USB devices (only works with certain host operating systems). QEMU will automatically create and connect virtual USB hubs as necessary to connect multiple USB devices. .. _Connecting USB devices: Connecting USB devices ~~~~~~~~~~~~~~~~~~~~~~ USB devices can be connected with the ``-device usb-...`` command line option or the ``device_add`` monitor command. Available devices are: ``usb-mouse`` Virtual Mouse. This will override the PS/2 mouse emulation when activated. ``usb-tablet`` Pointer device that uses absolute coordinates (like a touchscreen). This means QEMU is able to report the mouse position without having to grab the mouse. Also overrides the PS/2 mouse emulation when activated. ``usb-storage,drive=drive_id`` Mass storage device backed by drive_id (see the :ref:`disk images` chapter in the System Emulation Users Guide). This is the classic bulk-only transport protocol used by 99% of USB sticks. This example shows it connected to an XHCI USB controller and with a drive backed by a raw format disk image: .. parsed-literal:: |qemu_system| [...] \\ -drive if=none,id=stick,format=raw,file=/path/to/file.img \\ -device nec-usb-xhci,id=xhci \\ -device usb-storage,bus=xhci.0,drive=stick ``usb-uas`` USB attached SCSI device. This does not create a SCSI disk, so you need to explicitly create a ``scsi-hd`` or ``scsi-cd`` device on the command line, as well as using the ``-drive`` option to specify what those disks are backed by. One ``usb-uas`` device can handle multiple logical units (disks). This example creates three logical units: two disks and one cdrom drive: .. parsed-literal:: |qemu_system| [...] \\ -drive if=none,id=uas-disk1,format=raw,file=/path/to/file1.img \\ -drive if=none,id=uas-disk2,format=raw,file=/path/to/file2.img \\ -drive if=none,id=uas-cdrom,media=cdrom,format=raw,file=/path/to/image.iso \\ -device nec-usb-xhci,id=xhci \\ -device usb-uas,id=uas,bus=xhci.0 \\ -device scsi-hd,bus=uas.0,scsi-id=0,lun=0,drive=uas-disk1 \\ -device scsi-hd,bus=uas.0,scsi-id=0,lun=1,drive=uas-disk2 \\ -device scsi-cd,bus=uas.0,scsi-id=0,lun=5,drive=uas-cdrom ``usb-bot`` Bulk-only transport storage device. This presents the guest with the same USB bulk-only transport protocol interface as ``usb-storage``, but the QEMU command line option works like ``usb-uas`` and does not automatically create SCSI disks for you. ``usb-bot`` supports up to 16 LUNs. Unlike ``usb-uas``, the LUN numbers must be continuous, i.e. for three devices you must use 0+1+2. The 0+1+5 numbering from the ``usb-uas`` example above won't work with ``usb-bot``. ``usb-mtp,rootdir=dir`` Media transfer protocol device, using dir as root of the file tree that is presented to the guest. ``usb-host,hostbus=bus,hostaddr=addr`` Pass through the host device identified by bus and addr ``usb-host,vendorid=vendor,productid=product`` Pass through the host device identified by vendor and product ID ``usb-wacom-tablet`` Virtual Wacom PenPartner tablet. This device is similar to the ``tablet`` above but it can be used with the tslib library because in addition to touch coordinates it reports touch pressure. ``usb-kbd`` Standard USB keyboard. Will override the PS/2 keyboard (if present). ``usb-serial,chardev=id`` Serial converter. This emulates an FTDI FT232BM chip connected to host character device id. ``usb-braille,chardev=id`` Braille device. This will use BrlAPI to display the braille output on a real or fake device referenced by id. ``usb-net[,netdev=id]`` Network adapter that supports CDC ethernet and RNDIS protocols. id specifies a netdev defined with ``-netdev …,id=id``. For instance, user-mode networking can be used with .. parsed-literal:: |qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0 ``usb-ccid`` Smartcard reader device ``usb-audio`` USB audio device ``u2f-{emulated,passthru}`` Universal Second Factor device Hotplugging USB storage ~~~~~~~~~~~~~~~~~~~~~~~ The ``usb-bot`` and ``usb-uas`` devices can be hotplugged. In the hotplug case they are added with ``attached = false`` so the guest will not see the device until the ``attached`` property is explicitly set to true. That allows you to attach one or more scsi devices before making the device visible to the guest. The workflow looks like this: #. ``device-add usb-bot,id=foo`` #. ``device-add scsi-{hd,cd},bus=foo.0,lun=0`` #. optionally add more devices (luns 1 ... 15) #. ``scripts/qmp/qom-set foo.attached = true`` .. _host_005fusb_005fdevices: Using host USB devices on a Linux host ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ WARNING: this is an experimental feature. QEMU will slow down when using it. USB devices requiring real time streaming (i.e. USB Video Cameras) are not supported yet. 1. If you use an early Linux 2.4 kernel, verify that no Linux driver is actually using the USB device. A simple way to do that is simply to disable the corresponding kernel module by renaming it from ``mydriver.o`` to ``mydriver.o.disabled``. 2. Verify that ``/proc/bus/usb`` is working (most Linux distributions should enable it by default). You should see something like that: :: ls /proc/bus/usb 001 devices drivers 3. 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: :: chown -R myuid /proc/bus/usb 4. Launch QEMU and do in the monitor: :: info usbhost Device 1.2, speed 480 Mb/s Class 00: USB device 1234:5678, USB DISK You should see the list of the devices you can use (Never try to use hubs, it won't work). 5. Add the device in QEMU by using: :: device_add usb-host,vendorid=0x1234,productid=0x5678 Normally the guest OS should report that a new USB device is plugged. You can use the option ``-device usb-host,...`` to do the same. 6. Now you can try to use the host USB device in QEMU. When relaunching QEMU, you may have to unplug and plug again the USB device to make it work again (this is a bug).