system/devices/usb.rst

2 -------------
5 plug virtual USB devices or real host USB devices (only works with
6 certain host operating systems). QEMU will automatically create and
15 QEMU has XHCI host adapter support.  The XHCI hardware design is much
16 more virtualization-friendly when compared to EHCI and UHCI, thus XHCI
21     |qemu_system| -device qemu-xhci
46 ``-usb`` switch.  QEMU will create the UHCI controller as function of
47 the PIIX3 chipset.  The USB 1.1 bus will carry the name ``usb-bus.0``.
49 You can use the standard ``-device`` switch to add a EHCI controller to
50 your virtual machine.  It is strongly recommended to specify an ID for
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
58 .. parsed-literal::
60     |qemu_system| -M pc ${otheroptions}                        \\
61         -drive if=none,id=usbstick,format=raw,file=/path/to/image   \\
62         -usb                                                        \\
63         -device usb-ehci,id=ehci                                    \\
64         -device usb-tablet,bus=usb-bus.0                            \\
65         -device usb-storage,bus=ehci.0,drive=usbstick
85 .. parsed-literal::
87    |qemu_system| -readconfig docs/config/ich9-ehci-uhci.cfg
91 Using the ``-usb`` switch for ``q35`` machines will create a similar
100 USB devices can be connected with the ``-device usb-...`` command line
103 ``usb-mouse``
107 ``usb-tablet``
113 ``usb-storage,drive=drive_id``
116    bulk-only transport protocol used by 99% of USB sticks. This
120    .. parsed-literal::
123         -drive if=none,id=stick,format=raw,file=/path/to/file.img \\
124         -device nec-usb-xhci,id=xhci                              \\
125         -device usb-storage,bus=xhci.0,drive=stick
127 ``usb-uas``
129    you need to explicitly create a ``scsi-hd`` or ``scsi-cd`` device
130    on the command line, as well as using the ``-drive`` option to
131    specify what those disks are backed by. One ``usb-uas`` device can
135    .. parsed-literal::
138        -drive if=none,id=uas-disk1,format=raw,file=/path/to/file1.img  \\
139        -drive if=none,id=uas-disk2,format=raw,file=/path/to/file2.img  \\
140        -drive if=none,id=uas-cdrom,media=cdrom,format=raw,file=/path/to/image.iso \\
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
147 ``usb-bot``
148    Bulk-only transport storage device. This presents the guest with the
149    same USB bulk-only transport protocol interface as ``usb-storage``, but
150    the QEMU command line option works like ``usb-uas`` and does not
151    automatically create SCSI disks for you. ``usb-bot`` supports up to
152    16 LUNs. Unlike ``usb-uas``, the LUN numbers must be continuous,
154    ``usb-uas`` example above won't work with ``usb-bot``.
156 ``usb-mtp,rootdir=dir``
160 ``usb-host,hostbus=bus,hostaddr=addr``
161    Pass through the host device identified by bus and addr
163 ``usb-host,vendorid=vendor,productid=product``
164    Pass through the host device identified by vendor and product ID
166 ``usb-wacom-tablet``
171 ``usb-kbd``
174 ``usb-serial,chardev=id``
176    host character device id.
178 ``usb-braille,chardev=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
181    normally use BrlAPI to display the braille output on a BRLTTY-supported
184    .. parsed-literal::
186       |qemu_system| [...] -chardev braille,id=brl -device usb-braille,chardev=brl
190    .. parsed-literal::
192       |qemu_system| [...] -usbdevice braille
194 ``usb-net[,netdev=id]``
195    Network adapter that supports CDC ethernet and RNDIS protocols. id
196    specifies a netdev defined with ``-netdev …,id=id``. For instance,
197    user-mode networking can be used with
199    .. parsed-literal::
201       |qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0
203 ``usb-ccid``
206 ``usb-audio``
209 ``u2f-{emulated,passthru}``
210    :doc:`usb-u2f`
213    An Open-source Secure Key implementing FIDO2, OpenPGP, PIV and more.
225 ports (1-6), and the emulated (1.1) USB hub has eight ports.
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.
246         (qemu) device_add usb-tablet,bus=usb-bus.0,port=1,id=my-tablet
247         (qemu) device_del my-tablet
252 The ``usb-bot`` and ``usb-uas`` devices can be hotplugged.  In the hotplug
258 #. ``device-add usb-bot,id=foo``
259 #. ``device-add scsi-{hd,cd},bus=foo.0,lun=0``
261 #. ``scripts/qmp/qom-set foo.attached = true``
265 Using host USB devices on a Linux host
291       chown -R myuid /proc/bus/usb
308       device_add usb-host,vendorid=0x1234,productid=0x5678
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.
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
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
341   the guest when it shows up somewhere in the host.
343 - ``hostbus`` and ``hostport`` -- match for a specific physical port in the
344   host, any device which is plugged in there gets passed to the
347 - ``hostbus`` and ``hostaddr`` -- most useful for ad-hoc pass through as the
348   hostaddr isn't stable. The next time you plug the device into the host it
351 Note that on the host USB 1.1 devices are handled by UHCI/OHCI and USB
353 same physical port on the host may show up on different host buses
359 .. parsed-literal::
361    |qemu_system| -M pc [...]                            \\
362         -usb                                                 \\
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
367 ``usb-host`` properties for reset behavior
370 The ``guest-reset`` and ``guest-reset-all`` properties control
372 host.  There are three cases:
374 ``guest-reset=false``
377 ``guest-reset=true,guest-resets-all=false``
382 ``guest-reset=true,guest-resets-all=true``
386 should be able to reset (and re-initialize) usb devices at any time.
388 the device not responding any more until you power-cycle (aka un-plug
389 and re-plug) it.
392 usb device at hand, so it's a trial-and-error game.  If the default
402 ``-device usb-mouse,pcap=mouse.pcap``