system/devices/usb.rst

21     |qemu_system| -device qemu-xhci
49 You can use the standard ``-device`` switch to add a EHCI controller to
52 ``-device usb-ehci,id=ehci``.  This will give you a USB 2.0 bus named
55 When adding USB devices using the ``-device`` switch you can specify the
63         -device usb-ehci,id=ehci                                    \\
64         -device usb-tablet,bus=usb-bus.0                            \\
65         -device usb-storage,bus=ehci.0,drive=usbstick
68 device to the EHCI adapter.
100 USB devices can be connected with the ``-device usb-...`` command line
108    Pointer device that uses absolute coordinates (like a touchscreen).
114    Mass storage device backed by drive_id (see the :ref:`disk images`
124         -device nec-usb-xhci,id=xhci                              \\
125         -device usb-storage,bus=xhci.0,drive=stick
128    USB attached SCSI device. This does not create a SCSI disk, so
129    you need to explicitly create a ``scsi-hd`` or ``scsi-cd`` device
131    specify what those disks are backed by. One ``usb-uas`` device can
141        -device nec-usb-xhci,id=xhci                                    \\
142        -device usb-uas,id=uas,bus=xhci.0                               \\
143        -device scsi-hd,bus=uas.0,scsi-id=0,lun=0,drive=uas-disk1       \\
144        -device scsi-hd,bus=uas.0,scsi-id=0,lun=1,drive=uas-disk2       \\
145        -device scsi-cd,bus=uas.0,scsi-id=0,lun=5,drive=uas-cdrom
148    Bulk-only transport storage device. This presents the guest with the
157    Media transfer protocol device, using dir as root of the file tree
161    Pass through the host device identified by bus and addr
164    Pass through the host device identified by vendor and product ID
167    Virtual Wacom PenPartner tablet. This device is similar to the
176    host character device id.
179    Braille device. This emulates a Baum Braille device USB port. id has to
180    specify a character device defined with ``-chardev …,id=id``.  One will
182    device with
186       |qemu_system| [...] -chardev braille,id=brl -device usb-braille,chardev=brl
201       |qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0
204    Smartcard reader device
207    USB audio device
219 For all the above USB devices, by default QEMU will plug the device
223 the device will show up in the guest.  This can be done using the
229         -device usb-tablet,bus=usb-bus.0,port=1
233         -device usb-hub,bus=usb-bus.0,port=2
238         -device usb-storage,bus=usb-bus.0,port=2.4,drive=...
242 specify some unique id which you can use to refer to the device.
243 You can then use ``device_del`` to unplug the device later.
254 the device until the ``attached`` property is explicitly set to true.
256 device visible to the guest. The workflow looks like this:
258 #. ``device-add usb-bot,id=foo``
259 #. ``device-add scsi-{hd,cd},bus=foo.0,lun=0``
273    actually using the USB device. A simple way to do that is simply to
298         Device 1.2, speed 480 Mb/s
299           Class 00: USB device 1234:5678, USB DISK
304 5. Add the device in QEMU by using:
310    Normally the guest OS should report that a new USB device is plugged.
311    You can use the option ``-device usb-host,...`` to do the same.
313 6. Now you can try to use the host USB device in QEMU.
316 device to make it work again (this is a bug).
318 ``usb-host`` properties for specifying the host device
322 specify which host device to pass through, but this is not
323 the only way to specify the host device. ``usb-host`` supports
327   Specifies the bus number the device must be attached to
329   Specifies the device address the device got assigned by the guest os
331   Specifies the physical port the device is attached to
333   Specifies the vendor ID of the device
335   Specifies the product ID of the device.
340 - ``vendorid`` and ``productid`` -- match for a specific device, pass it to
344   host, any device which is plugged in there gets passed to the
348   hostaddr isn't stable. The next time you plug the device into the host it
356 for 1.1 devices, you can pass through any device plugged into that port
363         -device usb-ehci,id=ehci                             \\
364         -device usb-host,bus=usb-bus.0,hostbus=3,hostport=1  \\
365         -device usb-host,bus=ehci.0,hostbus=1,hostport=1
371 whenever the guest is allowed to reset the physical usb device on the
375   The guest is not allowed to reset the (physical) usb device.
378   The guest is allowed to reset the device when it is not yet
383   The guest is allowed to reset the device as it pleases.
387 In practice that may result in shitty usb device firmware crashing and
388 the device not responding any more until you power-cycle (aka un-plug
392 usb device at hand, so it's a trial-and-error game.  If the default
402 ``-device usb-mouse,pcap=mouse.pcap``