1189c099fSAlex BennéeUSB emulation 2189c099fSAlex Bennée------------- 3189c099fSAlex Bennée 4189c099fSAlex BennéeQEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can 5189c099fSAlex Bennéeplug virtual USB devices or real host USB devices (only works with 6189c099fSAlex Bennéecertain host operating systems). QEMU will automatically create and 7189c099fSAlex Bennéeconnect virtual USB hubs as necessary to connect multiple USB devices. 8189c099fSAlex Bennée 978da86dcSPeter MaydellUSB controllers 1078da86dcSPeter Maydell~~~~~~~~~~~~~~~ 1178da86dcSPeter Maydell 1278da86dcSPeter MaydellXHCI controller support 1378da86dcSPeter Maydell^^^^^^^^^^^^^^^^^^^^^^^ 1478da86dcSPeter Maydell 1578da86dcSPeter MaydellQEMU has XHCI host adapter support. The XHCI hardware design is much 1678da86dcSPeter Maydellmore virtualization-friendly when compared to EHCI and UHCI, thus XHCI 1778da86dcSPeter Maydellemulation uses less resources (especially CPU). So if your guest 1878da86dcSPeter Maydellsupports XHCI (which should be the case for any operating system 1978da86dcSPeter Maydellreleased around 2010 or later) we recommend using it: 2078da86dcSPeter Maydell 21*875b2fabSThomas Huth |qemu_system| -device qemu-xhci 2278da86dcSPeter Maydell 2378da86dcSPeter MaydellXHCI supports USB 1.1, USB 2.0 and USB 3.0 devices, so this is the 2478da86dcSPeter Maydellonly controller you need. With only a single USB controller (and 2578da86dcSPeter Maydelltherefore only a single USB bus) present in the system there is no 2678da86dcSPeter Maydellneed to use the bus= parameter when adding USB devices. 2778da86dcSPeter Maydell 2878da86dcSPeter Maydell 2978da86dcSPeter MaydellEHCI controller support 3078da86dcSPeter Maydell^^^^^^^^^^^^^^^^^^^^^^^ 3178da86dcSPeter Maydell 3278da86dcSPeter MaydellThe QEMU EHCI Adapter supports USB 2.0 devices. It can be used either 3378da86dcSPeter Maydellstandalone or with companion controllers (UHCI, OHCI) for USB 1.1 3478da86dcSPeter Maydelldevices. The companion controller setup is more convenient to use 3578da86dcSPeter Maydellbecause it provides a single USB bus supporting both USB 2.0 and USB 3678da86dcSPeter Maydell1.1 devices. See next section for details. 3778da86dcSPeter Maydell 3878da86dcSPeter MaydellWhen running EHCI in standalone mode you can add UHCI or OHCI 3978da86dcSPeter Maydellcontrollers for USB 1.1 devices too. Each controller creates its own 4078da86dcSPeter Maydellbus though, so there are two completely separate USB buses: One USB 4178da86dcSPeter Maydell1.1 bus driven by the UHCI controller and one USB 2.0 bus driven by 4278da86dcSPeter Maydellthe EHCI controller. Devices must be attached to the correct 4378da86dcSPeter Maydellcontroller manually. 4478da86dcSPeter Maydell 4578da86dcSPeter MaydellThe easiest way to add a UHCI controller to a ``pc`` machine is the 4678da86dcSPeter Maydell``-usb`` switch. QEMU will create the UHCI controller as function of 4778da86dcSPeter Maydellthe PIIX3 chipset. The USB 1.1 bus will carry the name ``usb-bus.0``. 4878da86dcSPeter Maydell 4978da86dcSPeter MaydellYou can use the standard ``-device`` switch to add a EHCI controller to 5078da86dcSPeter Maydellyour virtual machine. It is strongly recommended to specify an ID for 5178da86dcSPeter Maydellthe controller so the USB 2.0 bus gets an individual name, for example 5278da86dcSPeter Maydell``-device usb-ehci,id=ehci``. This will give you a USB 2.0 bus named 5378da86dcSPeter Maydell``ehci.0``. 5478da86dcSPeter Maydell 5578da86dcSPeter MaydellWhen adding USB devices using the ``-device`` switch you can specify the 5678da86dcSPeter Maydellbus they should be attached to. Here is a complete example: 5778da86dcSPeter Maydell 5878da86dcSPeter Maydell.. parsed-literal:: 5978da86dcSPeter Maydell 6078da86dcSPeter Maydell |qemu_system| -M pc ${otheroptions} \\ 6178da86dcSPeter Maydell -drive if=none,id=usbstick,format=raw,file=/path/to/image \\ 6278da86dcSPeter Maydell -usb \\ 6378da86dcSPeter Maydell -device usb-ehci,id=ehci \\ 6478da86dcSPeter Maydell -device usb-tablet,bus=usb-bus.0 \\ 6578da86dcSPeter Maydell -device usb-storage,bus=ehci.0,drive=usbstick 6678da86dcSPeter Maydell 6778da86dcSPeter MaydellThis attaches a USB tablet to the UHCI adapter and a USB mass storage 6878da86dcSPeter Maydelldevice to the EHCI adapter. 6978da86dcSPeter Maydell 7078da86dcSPeter Maydell 7178da86dcSPeter MaydellCompanion controller support 7278da86dcSPeter Maydell^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 7378da86dcSPeter Maydell 7478da86dcSPeter MaydellThe UHCI and OHCI controllers can attach to a USB bus created by EHCI 7578da86dcSPeter Maydellas companion controllers. This is done by specifying the ``masterbus`` 7678da86dcSPeter Maydelland ``firstport`` properties. ``masterbus`` specifies the bus name the 7778da86dcSPeter Maydellcontroller should attach to. ``firstport`` specifies the first port the 7878da86dcSPeter Maydellcontroller should attach to, which is needed as usually one EHCI 7978da86dcSPeter Maydellcontroller with six ports has three UHCI companion controllers with 8078da86dcSPeter Maydelltwo ports each. 8178da86dcSPeter Maydell 8278da86dcSPeter MaydellThere is a config file in docs which will do all this for 8378da86dcSPeter Maydellyou, which you can use like this: 8478da86dcSPeter Maydell 8578da86dcSPeter Maydell.. parsed-literal:: 8678da86dcSPeter Maydell 8778da86dcSPeter Maydell |qemu_system| -readconfig docs/config/ich9-ehci-uhci.cfg 8878da86dcSPeter Maydell 8978da86dcSPeter MaydellThen use ``bus=ehci.0`` to assign your USB devices to that bus. 9078da86dcSPeter Maydell 9178da86dcSPeter MaydellUsing the ``-usb`` switch for ``q35`` machines will create a similar 9278da86dcSPeter MaydellUSB controller configuration. 9378da86dcSPeter Maydell 9478da86dcSPeter Maydell 95189c099fSAlex Bennée.. _Connecting USB devices: 96189c099fSAlex Bennée 97189c099fSAlex BennéeConnecting USB devices 98189c099fSAlex Bennée~~~~~~~~~~~~~~~~~~~~~~ 99189c099fSAlex Bennée 100189c099fSAlex BennéeUSB devices can be connected with the ``-device usb-...`` command line 101189c099fSAlex Bennéeoption or the ``device_add`` monitor command. Available devices are: 102189c099fSAlex Bennée 103189c099fSAlex Bennée``usb-mouse`` 104189c099fSAlex Bennée Virtual Mouse. This will override the PS/2 mouse emulation when 105189c099fSAlex Bennée activated. 106189c099fSAlex Bennée 107189c099fSAlex Bennée``usb-tablet`` 108189c099fSAlex Bennée Pointer device that uses absolute coordinates (like a touchscreen). 109189c099fSAlex Bennée This means QEMU is able to report the mouse position without having 110189c099fSAlex Bennée to grab the mouse. Also overrides the PS/2 mouse emulation when 111189c099fSAlex Bennée activated. 112189c099fSAlex Bennée 113189c099fSAlex Bennée``usb-storage,drive=drive_id`` 114189c099fSAlex Bennée Mass storage device backed by drive_id (see the :ref:`disk images` 1152a49e4e9SPeter Maydell chapter in the System Emulation Users Guide). This is the classic 1162a49e4e9SPeter Maydell bulk-only transport protocol used by 99% of USB sticks. This 1172a49e4e9SPeter Maydell example shows it connected to an XHCI USB controller and with 1182a49e4e9SPeter Maydell a drive backed by a raw format disk image: 1192a49e4e9SPeter Maydell 1202a49e4e9SPeter Maydell .. parsed-literal:: 1212a49e4e9SPeter Maydell 1222a49e4e9SPeter Maydell |qemu_system| [...] \\ 1232a49e4e9SPeter Maydell -drive if=none,id=stick,format=raw,file=/path/to/file.img \\ 1242a49e4e9SPeter Maydell -device nec-usb-xhci,id=xhci \\ 1252a49e4e9SPeter Maydell -device usb-storage,bus=xhci.0,drive=stick 126189c099fSAlex Bennée 127189c099fSAlex Bennée``usb-uas`` 1282a49e4e9SPeter Maydell USB attached SCSI device. This does not create a SCSI disk, so 1292a49e4e9SPeter Maydell you need to explicitly create a ``scsi-hd`` or ``scsi-cd`` device 1302a49e4e9SPeter Maydell on the command line, as well as using the ``-drive`` option to 1312a49e4e9SPeter Maydell specify what those disks are backed by. One ``usb-uas`` device can 1322a49e4e9SPeter Maydell handle multiple logical units (disks). This example creates three 1332a49e4e9SPeter Maydell logical units: two disks and one cdrom drive: 1342a49e4e9SPeter Maydell 1352a49e4e9SPeter Maydell .. parsed-literal:: 1362a49e4e9SPeter Maydell 1372a49e4e9SPeter Maydell |qemu_system| [...] \\ 1382a49e4e9SPeter Maydell -drive if=none,id=uas-disk1,format=raw,file=/path/to/file1.img \\ 1392a49e4e9SPeter Maydell -drive if=none,id=uas-disk2,format=raw,file=/path/to/file2.img \\ 1402a49e4e9SPeter Maydell -drive if=none,id=uas-cdrom,media=cdrom,format=raw,file=/path/to/image.iso \\ 1412a49e4e9SPeter Maydell -device nec-usb-xhci,id=xhci \\ 1422a49e4e9SPeter Maydell -device usb-uas,id=uas,bus=xhci.0 \\ 1432a49e4e9SPeter Maydell -device scsi-hd,bus=uas.0,scsi-id=0,lun=0,drive=uas-disk1 \\ 1442a49e4e9SPeter Maydell -device scsi-hd,bus=uas.0,scsi-id=0,lun=1,drive=uas-disk2 \\ 1452a49e4e9SPeter Maydell -device scsi-cd,bus=uas.0,scsi-id=0,lun=5,drive=uas-cdrom 146189c099fSAlex Bennée 147189c099fSAlex Bennée``usb-bot`` 1482a49e4e9SPeter Maydell Bulk-only transport storage device. This presents the guest with the 1492a49e4e9SPeter Maydell same USB bulk-only transport protocol interface as ``usb-storage``, but 1502a49e4e9SPeter Maydell the QEMU command line option works like ``usb-uas`` and does not 1512a49e4e9SPeter Maydell automatically create SCSI disks for you. ``usb-bot`` supports up to 1522a49e4e9SPeter Maydell 16 LUNs. Unlike ``usb-uas``, the LUN numbers must be continuous, 1532a49e4e9SPeter Maydell i.e. for three devices you must use 0+1+2. The 0+1+5 numbering from the 1542a49e4e9SPeter Maydell ``usb-uas`` example above won't work with ``usb-bot``. 155189c099fSAlex Bennée 156189c099fSAlex Bennée``usb-mtp,rootdir=dir`` 157189c099fSAlex Bennée Media transfer protocol device, using dir as root of the file tree 158189c099fSAlex Bennée that is presented to the guest. 159189c099fSAlex Bennée 160189c099fSAlex Bennée``usb-host,hostbus=bus,hostaddr=addr`` 161189c099fSAlex Bennée Pass through the host device identified by bus and addr 162189c099fSAlex Bennée 163189c099fSAlex Bennée``usb-host,vendorid=vendor,productid=product`` 164189c099fSAlex Bennée Pass through the host device identified by vendor and product ID 165189c099fSAlex Bennée 166189c099fSAlex Bennée``usb-wacom-tablet`` 167189c099fSAlex Bennée Virtual Wacom PenPartner tablet. This device is similar to the 168189c099fSAlex Bennée ``tablet`` above but it can be used with the tslib library because in 169189c099fSAlex Bennée addition to touch coordinates it reports touch pressure. 170189c099fSAlex Bennée 171189c099fSAlex Bennée``usb-kbd`` 172189c099fSAlex Bennée Standard USB keyboard. Will override the PS/2 keyboard (if present). 173189c099fSAlex Bennée 174189c099fSAlex Bennée``usb-serial,chardev=id`` 175189c099fSAlex Bennée Serial converter. This emulates an FTDI FT232BM chip connected to 176189c099fSAlex Bennée host character device id. 177189c099fSAlex Bennée 178189c099fSAlex Bennée``usb-braille,chardev=id`` 1793e01455eSSamuel Thibault Braille device. This emulates a Baum Braille device USB port. id has to 1803e01455eSSamuel Thibault specify a character device defined with ``-chardev …,id=id``. One will 1813e01455eSSamuel Thibault normally use BrlAPI to display the braille output on a BRLTTY-supported 1823e01455eSSamuel Thibault device with 1833e01455eSSamuel Thibault 1843e01455eSSamuel Thibault .. parsed-literal:: 1853e01455eSSamuel Thibault 1863e01455eSSamuel Thibault |qemu_system| [...] -chardev braille,id=brl -device usb-braille,chardev=brl 1873e01455eSSamuel Thibault 1883e01455eSSamuel Thibault or alternatively, use the following equivalent shortcut: 1893e01455eSSamuel Thibault 1903e01455eSSamuel Thibault .. parsed-literal:: 1913e01455eSSamuel Thibault 1923e01455eSSamuel Thibault |qemu_system| [...] -usbdevice braille 193189c099fSAlex Bennée 194189c099fSAlex Bennée``usb-net[,netdev=id]`` 195189c099fSAlex Bennée Network adapter that supports CDC ethernet and RNDIS protocols. id 196189c099fSAlex Bennée specifies a netdev defined with ``-netdev …,id=id``. For instance, 197189c099fSAlex Bennée user-mode networking can be used with 198189c099fSAlex Bennée 199189c099fSAlex Bennée .. parsed-literal:: 200189c099fSAlex Bennée 201189c099fSAlex Bennée |qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0 202189c099fSAlex Bennée 203189c099fSAlex Bennée``usb-ccid`` 204189c099fSAlex Bennée Smartcard reader device 205189c099fSAlex Bennée 206189c099fSAlex Bennée``usb-audio`` 207189c099fSAlex Bennée USB audio device 208189c099fSAlex Bennée 209189c099fSAlex Bennée``u2f-{emulated,passthru}`` 21091608e2aSPeter Maydell :doc:`usb-u2f` 211189c099fSAlex Bennée 212adaf4d2eSHongren (Zenithal) Zheng``canokey`` 213adaf4d2eSHongren (Zenithal) Zheng An Open-source Secure Key implementing FIDO2, OpenPGP, PIV and more. 214adaf4d2eSHongren (Zenithal) Zheng For more information, see :ref:`canokey`. 215adaf4d2eSHongren (Zenithal) Zheng 216557ae976SPeter MaydellPhysical port addressing 217557ae976SPeter Maydell^^^^^^^^^^^^^^^^^^^^^^^^ 218557ae976SPeter Maydell 219557ae976SPeter MaydellFor all the above USB devices, by default QEMU will plug the device 220557ae976SPeter Maydellinto the next available port on the specified USB bus, or onto 221557ae976SPeter Maydellsome available USB bus if you didn't specify one explicitly. 222557ae976SPeter MaydellIf you need to, you can also specify the physical port where 223557ae976SPeter Maydellthe device will show up in the guest. This can be done using the 224557ae976SPeter Maydell``port`` property. UHCI has two root ports (1,2). EHCI has six root 225557ae976SPeter Maydellports (1-6), and the emulated (1.1) USB hub has eight ports. 226557ae976SPeter Maydell 227557ae976SPeter MaydellPlugging a tablet into UHCI port 1 works like this:: 228557ae976SPeter Maydell 229557ae976SPeter Maydell -device usb-tablet,bus=usb-bus.0,port=1 230557ae976SPeter Maydell 231557ae976SPeter MaydellPlugging a hub into UHCI port 2 works like this:: 232557ae976SPeter Maydell 233557ae976SPeter Maydell -device usb-hub,bus=usb-bus.0,port=2 234557ae976SPeter Maydell 235557ae976SPeter MaydellPlugging a virtual USB stick into port 4 of the hub just plugged works 236557ae976SPeter Maydellthis way:: 237557ae976SPeter Maydell 238557ae976SPeter Maydell -device usb-storage,bus=usb-bus.0,port=2.4,drive=... 239557ae976SPeter Maydell 240557ae976SPeter MaydellIn the monitor, the ``device_add` command also accepts a ``port`` 241557ae976SPeter Maydellproperty specification. If you want to unplug devices too you should 242557ae976SPeter Maydellspecify some unique id which you can use to refer to the device. 243557ae976SPeter MaydellYou can then use ``device_del`` to unplug the device later. 244557ae976SPeter MaydellFor example:: 245557ae976SPeter Maydell 246557ae976SPeter Maydell (qemu) device_add usb-tablet,bus=usb-bus.0,port=1,id=my-tablet 247557ae976SPeter Maydell (qemu) device_del my-tablet 248557ae976SPeter Maydell 2492a49e4e9SPeter MaydellHotplugging USB storage 2502a49e4e9SPeter Maydell~~~~~~~~~~~~~~~~~~~~~~~ 2512a49e4e9SPeter Maydell 2522a49e4e9SPeter MaydellThe ``usb-bot`` and ``usb-uas`` devices can be hotplugged. In the hotplug 2532a49e4e9SPeter Maydellcase they are added with ``attached = false`` so the guest will not see 2542a49e4e9SPeter Maydellthe device until the ``attached`` property is explicitly set to true. 2552a49e4e9SPeter MaydellThat allows you to attach one or more scsi devices before making the 2562a49e4e9SPeter Maydelldevice visible to the guest. The workflow looks like this: 2572a49e4e9SPeter Maydell 2582a49e4e9SPeter Maydell#. ``device-add usb-bot,id=foo`` 2592a49e4e9SPeter Maydell#. ``device-add scsi-{hd,cd},bus=foo.0,lun=0`` 2602a49e4e9SPeter Maydell#. optionally add more devices (luns 1 ... 15) 2612a49e4e9SPeter Maydell#. ``scripts/qmp/qom-set foo.attached = true`` 2622a49e4e9SPeter Maydell 263189c099fSAlex Bennée.. _host_005fusb_005fdevices: 264189c099fSAlex Bennée 265189c099fSAlex BennéeUsing host USB devices on a Linux host 266189c099fSAlex Bennée~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 267189c099fSAlex Bennée 268189c099fSAlex BennéeWARNING: this is an experimental feature. QEMU will slow down when using 269189c099fSAlex Bennéeit. USB devices requiring real time streaming (i.e. USB Video Cameras) 270189c099fSAlex Bennéeare not supported yet. 271189c099fSAlex Bennée 272189c099fSAlex Bennée1. If you use an early Linux 2.4 kernel, verify that no Linux driver is 273189c099fSAlex Bennée actually using the USB device. A simple way to do that is simply to 274189c099fSAlex Bennée disable the corresponding kernel module by renaming it from 275189c099fSAlex Bennée ``mydriver.o`` to ``mydriver.o.disabled``. 276189c099fSAlex Bennée 277189c099fSAlex Bennée2. Verify that ``/proc/bus/usb`` is working (most Linux distributions 278189c099fSAlex Bennée should enable it by default). You should see something like that: 279189c099fSAlex Bennée 280189c099fSAlex Bennée :: 281189c099fSAlex Bennée 282189c099fSAlex Bennée ls /proc/bus/usb 283189c099fSAlex Bennée 001 devices drivers 284189c099fSAlex Bennée 285189c099fSAlex Bennée3. Since only root can access to the USB devices directly, you can 286189c099fSAlex Bennée either launch QEMU as root or change the permissions of the USB 287189c099fSAlex Bennée devices you want to use. For testing, the following suffices: 288189c099fSAlex Bennée 289189c099fSAlex Bennée :: 290189c099fSAlex Bennée 291189c099fSAlex Bennée chown -R myuid /proc/bus/usb 292189c099fSAlex Bennée 293189c099fSAlex Bennée4. Launch QEMU and do in the monitor: 294189c099fSAlex Bennée 295189c099fSAlex Bennée :: 296189c099fSAlex Bennée 297189c099fSAlex Bennée info usbhost 298189c099fSAlex Bennée Device 1.2, speed 480 Mb/s 299189c099fSAlex Bennée Class 00: USB device 1234:5678, USB DISK 300189c099fSAlex Bennée 301189c099fSAlex Bennée You should see the list of the devices you can use (Never try to use 302189c099fSAlex Bennée hubs, it won't work). 303189c099fSAlex Bennée 304189c099fSAlex Bennée5. Add the device in QEMU by using: 305189c099fSAlex Bennée 306189c099fSAlex Bennée :: 307189c099fSAlex Bennée 308189c099fSAlex Bennée device_add usb-host,vendorid=0x1234,productid=0x5678 309189c099fSAlex Bennée 310189c099fSAlex Bennée Normally the guest OS should report that a new USB device is plugged. 311189c099fSAlex Bennée You can use the option ``-device usb-host,...`` to do the same. 312189c099fSAlex Bennée 313189c099fSAlex Bennée6. Now you can try to use the host USB device in QEMU. 314189c099fSAlex Bennée 315189c099fSAlex BennéeWhen relaunching QEMU, you may have to unplug and plug again the USB 316189c099fSAlex Bennéedevice to make it work again (this is a bug). 31730a20f2cSPeter Maydell 31830a20f2cSPeter Maydell``usb-host`` properties for specifying the host device 31930a20f2cSPeter Maydell^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 32030a20f2cSPeter Maydell 32130a20f2cSPeter MaydellThe example above uses the ``vendorid`` and ``productid`` to 32230a20f2cSPeter Maydellspecify which host device to pass through, but this is not 32330a20f2cSPeter Maydellthe only way to specify the host device. ``usb-host`` supports 32430a20f2cSPeter Maydellthe following properties: 32530a20f2cSPeter Maydell 32630a20f2cSPeter Maydell``hostbus=<nr>`` 32730a20f2cSPeter Maydell Specifies the bus number the device must be attached to 32830a20f2cSPeter Maydell``hostaddr=<nr>`` 32930a20f2cSPeter Maydell Specifies the device address the device got assigned by the guest os 33030a20f2cSPeter Maydell``hostport=<str>`` 33130a20f2cSPeter Maydell Specifies the physical port the device is attached to 33230a20f2cSPeter Maydell``vendorid=<hexnr>`` 33330a20f2cSPeter Maydell Specifies the vendor ID of the device 33430a20f2cSPeter Maydell``productid=<hexnr>`` 33530a20f2cSPeter Maydell Specifies the product ID of the device. 33630a20f2cSPeter Maydell 33730a20f2cSPeter MaydellIn theory you can combine all these properties as you like. In 33830a20f2cSPeter Maydellpractice only a few combinations are useful: 33930a20f2cSPeter Maydell 34030a20f2cSPeter Maydell- ``vendorid`` and ``productid`` -- match for a specific device, pass it to 34130a20f2cSPeter Maydell the guest when it shows up somewhere in the host. 34230a20f2cSPeter Maydell 34330a20f2cSPeter Maydell- ``hostbus`` and ``hostport`` -- match for a specific physical port in the 34430a20f2cSPeter Maydell host, any device which is plugged in there gets passed to the 34530a20f2cSPeter Maydell guest. 34630a20f2cSPeter Maydell 34730a20f2cSPeter Maydell- ``hostbus`` and ``hostaddr`` -- most useful for ad-hoc pass through as the 34830a20f2cSPeter Maydell hostaddr isn't stable. The next time you plug the device into the host it 34930a20f2cSPeter Maydell will get a new hostaddr. 35030a20f2cSPeter Maydell 35130a20f2cSPeter MaydellNote that on the host USB 1.1 devices are handled by UHCI/OHCI and USB 35230a20f2cSPeter Maydell2.0 by EHCI. That means different USB devices plugged into the very 35330a20f2cSPeter Maydellsame physical port on the host may show up on different host buses 35430a20f2cSPeter Maydelldepending on the speed. Supposing that devices plugged into a given 35530a20f2cSPeter Maydellphysical port appear as bus 1 + port 1 for 2.0 devices and bus 3 + port 1 35630a20f2cSPeter Maydellfor 1.1 devices, you can pass through any device plugged into that port 35730a20f2cSPeter Maydelland also assign it to the correct USB bus in QEMU like this: 35830a20f2cSPeter Maydell 35930a20f2cSPeter Maydell.. parsed-literal:: 36030a20f2cSPeter Maydell 36130a20f2cSPeter Maydell |qemu_system| -M pc [...] \\ 36230a20f2cSPeter Maydell -usb \\ 36330a20f2cSPeter Maydell -device usb-ehci,id=ehci \\ 36430a20f2cSPeter Maydell -device usb-host,bus=usb-bus.0,hostbus=3,hostport=1 \\ 36530a20f2cSPeter Maydell -device usb-host,bus=ehci.0,hostbus=1,hostport=1 366f3a445b6SGerd Hoffmann 367f3a445b6SGerd Hoffmann``usb-host`` properties for reset behavior 368f3a445b6SGerd Hoffmann^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 369f3a445b6SGerd Hoffmann 370f3a445b6SGerd HoffmannThe ``guest-reset`` and ``guest-reset-all`` properties control 371f3a445b6SGerd Hoffmannwhenever the guest is allowed to reset the physical usb device on the 372f3a445b6SGerd Hoffmannhost. There are three cases: 373f3a445b6SGerd Hoffmann 374f3a445b6SGerd Hoffmann``guest-reset=false`` 375f3a445b6SGerd Hoffmann The guest is not allowed to reset the (physical) usb device. 376f3a445b6SGerd Hoffmann 377f3a445b6SGerd Hoffmann``guest-reset=true,guest-resets-all=false`` 378f3a445b6SGerd Hoffmann The guest is allowed to reset the device when it is not yet 379f3a445b6SGerd Hoffmann initialized (aka no usb bus address assigned). Usually this results 380f3a445b6SGerd Hoffmann in one guest reset being allowed. This is the default behavior. 381f3a445b6SGerd Hoffmann 382f3a445b6SGerd Hoffmann``guest-reset=true,guest-resets-all=true`` 383f3a445b6SGerd Hoffmann The guest is allowed to reset the device as it pleases. 384f3a445b6SGerd Hoffmann 385f3a445b6SGerd HoffmannThe reason for this existing are broken usb devices. In theory one 386f3a445b6SGerd Hoffmannshould be able to reset (and re-initialize) usb devices at any time. 387f3a445b6SGerd HoffmannIn practice that may result in shitty usb device firmware crashing and 388f3a445b6SGerd Hoffmannthe device not responding any more until you power-cycle (aka un-plug 389f3a445b6SGerd Hoffmannand re-plug) it. 390f3a445b6SGerd Hoffmann 391f3a445b6SGerd HoffmannWhat works best pretty much depends on the behavior of the specific 392f3a445b6SGerd Hoffmannusb device at hand, so it's a trial-and-error game. If the default 393f3a445b6SGerd Hoffmanndoesn't work, try another option and see whenever the situation 394f3a445b6SGerd Hoffmannimproves. 39504fcb215SGerd Hoffmann 39604fcb215SGerd Hoffmannrecord usb transfers 39704fcb215SGerd Hoffmann^^^^^^^^^^^^^^^^^^^^ 39804fcb215SGerd Hoffmann 39904fcb215SGerd HoffmannAll usb devices have support for recording the usb traffic. This can 40004fcb215SGerd Hoffmannbe enabled using the ``pcap=<file>`` property, for example: 40104fcb215SGerd Hoffmann 40204fcb215SGerd Hoffmann``-device usb-mouse,pcap=mouse.pcap`` 40304fcb215SGerd Hoffmann 40404fcb215SGerd HoffmannThe pcap files are compatible with the linux kernels usbmon. Many 40504fcb215SGerd Hoffmanntools, including ``wireshark``, can decode and inspect these trace 40604fcb215SGerd Hoffmannfiles. 407