| 1 | USB emulation |
| 2 | ------------- |
| 3 | |
| 4 | QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can |
| 5 | plug virtual USB devices or real host USB devices (only works with |
| 6 | certain host operating systems). QEMU will automatically create and |
| 7 | connect virtual USB hubs as necessary to connect multiple USB devices. |
| 8 | |
| 9 | USB controllers |
| 10 | ~~~~~~~~~~~~~~~ |
| 11 | |
| 12 | XHCI controller support |
| 13 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 14 | |
| 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 |
| 17 | emulation uses less resources (especially CPU). So if your guest |
| 18 | supports XHCI (which should be the case for any operating system |
| 19 | released around 2010 or later) we recommend using it: |
| 20 | |
| 21 | |qemu_system| -device qemu-xhci |
| 22 | |
| 23 | XHCI supports USB 1.1, USB 2.0 and USB 3.0 devices, so this is the |
| 24 | only controller you need. With only a single USB controller (and |
| 25 | therefore only a single USB bus) present in the system there is no |
| 26 | need to use the bus= parameter when adding USB devices. |
| 27 | |
| 28 | |
| 29 | EHCI controller support |
| 30 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 31 | |
| 32 | The QEMU EHCI Adapter supports USB 2.0 devices. It can be used either |
| 33 | standalone or with companion controllers (UHCI, OHCI) for USB 1.1 |
| 34 | devices. The companion controller setup is more convenient to use |
| 35 | because it provides a single USB bus supporting both USB 2.0 and USB |
| 36 | 1.1 devices. See next section for details. |
| 37 | |
| 38 | When running EHCI in standalone mode you can add UHCI or OHCI |
| 39 | controllers for USB 1.1 devices too. Each controller creates its own |
| 40 | bus though, so there are two completely separate USB buses: One USB |
| 41 | 1.1 bus driven by the UHCI controller and one USB 2.0 bus driven by |
| 42 | the EHCI controller. Devices must be attached to the correct |
| 43 | controller manually. |
| 44 | |
| 45 | The easiest way to add a UHCI controller to a ``pc`` machine is the |
| 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``. |
| 48 | |
| 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 |
| 51 | the controller so the USB 2.0 bus gets an individual name, for example |
| 52 | ``-device usb-ehci,id=ehci``. This will give you a USB 2.0 bus named |
| 53 | ``ehci.0``. |
| 54 | |
| 55 | When adding USB devices using the ``-device`` switch you can specify the |
| 56 | bus they should be attached to. Here is a complete example: |
| 57 | |
| 58 | .. parsed-literal:: |
| 59 | |
| 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 |
| 66 | |
| 67 | This attaches a USB tablet to the UHCI adapter and a USB mass storage |
| 68 | device to the EHCI adapter. |
| 69 | |
| 70 | |
| 71 | Companion controller support |
| 72 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 73 | |
| 74 | The UHCI and OHCI controllers can attach to a USB bus created by EHCI |
| 75 | as companion controllers. This is done by specifying the ``masterbus`` |
| 76 | and ``firstport`` properties. ``masterbus`` specifies the bus name the |
| 77 | controller should attach to. ``firstport`` specifies the first port the |
| 78 | controller should attach to, which is needed as usually one EHCI |
| 79 | controller with six ports has three UHCI companion controllers with |
| 80 | two ports each. |
| 81 | |
| 82 | There is a config file in docs which will do all this for |
| 83 | you, which you can use like this: |
| 84 | |
| 85 | .. parsed-literal:: |
| 86 | |
| 87 | |qemu_system| -readconfig docs/config/ich9-ehci-uhci.cfg |
| 88 | |
| 89 | Then use ``bus=ehci.0`` to assign your USB devices to that bus. |
| 90 | |
| 91 | Using the ``-usb`` switch for ``q35`` machines will create a similar |
| 92 | USB controller configuration. |
| 93 | |
| 94 | |
| 95 | .. _Connecting USB devices: |
| 96 | |
| 97 | Connecting USB devices |
| 98 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 99 | |
| 100 | USB devices can be connected with the ``-device usb-...`` command line |
| 101 | option or the ``device_add`` monitor command. Available devices are: |
| 102 | |
| 103 | ``usb-mouse`` |
| 104 | Virtual Mouse. This will override the PS/2 mouse emulation when |
| 105 | activated. |
| 106 | |
| 107 | ``usb-tablet`` |
| 108 | Pointer device that uses absolute coordinates (like a touchscreen). |
| 109 | This means QEMU is able to report the mouse position without having |
| 110 | to grab the mouse. Also overrides the PS/2 mouse emulation when |
| 111 | activated. |
| 112 | |
| 113 | ``usb-storage,drive=drive_id`` |
| 114 | Mass storage device backed by drive_id (see the :ref:`disk images` |
| 115 | chapter in the System Emulation Users Guide). This is the classic |
| 116 | bulk-only transport protocol used by 99% of USB sticks. This |
| 117 | example shows it connected to an XHCI USB controller and with |
| 118 | a drive backed by a raw format disk image: |
| 119 | |
| 120 | .. parsed-literal:: |
| 121 | |
| 122 | |qemu_system| [...] \\ |
| 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 |
| 126 | |
| 127 | ``usb-uas`` |
| 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 |
| 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 |
| 132 | handle multiple logical units (disks). This example creates three |
| 133 | logical units: two disks and one cdrom drive: |
| 134 | |
| 135 | .. parsed-literal:: |
| 136 | |
| 137 | |qemu_system| [...] \\ |
| 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 |
| 146 | |
| 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, |
| 153 | i.e. for three devices you must use 0+1+2. The 0+1+5 numbering from the |
| 154 | ``usb-uas`` example above won't work with ``usb-bot``. |
| 155 | |
| 156 | ``usb-mtp,rootdir=dir`` |
| 157 | Media transfer protocol device, using dir as root of the file tree |
| 158 | that is presented to the guest. |
| 159 | |
| 160 | ``usb-host,hostbus=bus,hostaddr=addr`` |
| 161 | Pass through the host device identified by bus and addr |
| 162 | |
| 163 | ``usb-host,vendorid=vendor,productid=product`` |
| 164 | Pass through the host device identified by vendor and product ID |
| 165 | |
| 166 | ``usb-wacom-tablet`` |
| 167 | Virtual Wacom PenPartner tablet. This device is similar to the |
| 168 | ``tablet`` above but it can be used with the tslib library because in |
| 169 | addition to touch coordinates it reports touch pressure. |
| 170 | |
| 171 | ``usb-kbd`` |
| 172 | Standard USB keyboard. Will override the PS/2 keyboard (if present). |
| 173 | |
| 174 | ``usb-serial,chardev=id`` |
| 175 | Serial converter. This emulates an FTDI FT232BM chip connected to |
| 176 | host character device id. |
| 177 | |
| 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 |
| 182 | device with |
| 183 | |
| 184 | .. parsed-literal:: |
| 185 | |
| 186 | |qemu_system| [...] -chardev braille,id=brl -device usb-braille,chardev=brl |
| 187 | |
| 188 | or alternatively, use the following equivalent shortcut: |
| 189 | |
| 190 | .. parsed-literal:: |
| 191 | |
| 192 | |qemu_system| [...] -usbdevice braille |
| 193 | |
| 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 |
| 198 | |
| 199 | .. parsed-literal:: |
| 200 | |
| 201 | |qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0 |
| 202 | |
| 203 | ``usb-ccid`` |
| 204 | Smartcard reader device |
| 205 | |
| 206 | ``usb-audio`` |
| 207 | USB audio device |
| 208 | |
| 209 | ``u2f-{emulated,passthru}`` |
| 210 | :doc:`usb-u2f` |
| 211 | |
| 212 | ``canokey`` |
| 213 | An Open-source Secure Key implementing FIDO2, OpenPGP, PIV and more. |
| 214 | For more information, see :ref:`canokey`. |
| 215 | |
| 216 | Physical port addressing |
| 217 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| 218 | |
| 219 | For all the above USB devices, by default QEMU will plug the device |
| 220 | into the next available port on the specified USB bus, or onto |
| 221 | some available USB bus if you didn't specify one explicitly. |
| 222 | If you need to, you can also specify the physical port where |
| 223 | the device will show up in the guest. This can be done using the |
| 224 | ``port`` property. UHCI has two root ports (1,2). EHCI has six root |
| 225 | ports (1-6), and the emulated (1.1) USB hub has eight ports. |
| 226 | |
| 227 | Plugging a tablet into UHCI port 1 works like this:: |
| 228 | |
| 229 | -device usb-tablet,bus=usb-bus.0,port=1 |
| 230 | |
| 231 | Plugging a hub into UHCI port 2 works like this:: |
| 232 | |
| 233 | -device usb-hub,bus=usb-bus.0,port=2 |
| 234 | |
| 235 | Plugging a virtual USB stick into port 4 of the hub just plugged works |
| 236 | this way:: |
| 237 | |
| 238 | -device usb-storage,bus=usb-bus.0,port=2.4,drive=... |
| 239 | |
| 240 | In the monitor, the ``device_add` command also accepts a ``port`` |
| 241 | property specification. If you want to unplug devices too you should |
| 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. |
| 244 | For example:: |
| 245 | |
| 246 | (qemu) device_add usb-tablet,bus=usb-bus.0,port=1,id=my-tablet |
| 247 | (qemu) device_del my-tablet |
| 248 | |
| 249 | Hotplugging USB storage |
| 250 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 251 | |
| 252 | The ``usb-bot`` and ``usb-uas`` devices can be hotplugged. In the hotplug |
| 253 | case they are added with ``attached = false`` so the guest will not see |
| 254 | the device until the ``attached`` property is explicitly set to true. |
| 255 | That allows you to attach one or more scsi devices before making the |
| 256 | device visible to the guest. The workflow looks like this: |
| 257 | |
| 258 | #. ``device-add usb-bot,id=foo`` |
| 259 | #. ``device-add scsi-{hd,cd},bus=foo.0,lun=0`` |
| 260 | #. optionally add more devices (luns 1 ... 15) |
| 261 | #. ``scripts/qmp/qom-set foo.attached = true`` |
| 262 | |
| 263 | .. _host_005fusb_005fdevices: |
| 264 | |
| 265 | Using host USB devices on a Linux host |
| 266 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 267 | |
| 268 | WARNING: this is an experimental feature. QEMU will slow down when using |
| 269 | it. USB devices requiring real time streaming (i.e. USB Video Cameras) |
| 270 | are not supported yet. |
| 271 | |
| 272 | 1. If you use an early Linux 2.4 kernel, verify that no Linux driver is |
| 273 | actually using the USB device. A simple way to do that is simply to |
| 274 | disable the corresponding kernel module by renaming it from |
| 275 | ``mydriver.o`` to ``mydriver.o.disabled``. |
| 276 | |
| 277 | 2. Verify that ``/proc/bus/usb`` is working (most Linux distributions |
| 278 | should enable it by default). You should see something like that: |
| 279 | |
| 280 | :: |
| 281 | |
| 282 | ls /proc/bus/usb |
| 283 | 001 devices drivers |
| 284 | |
| 285 | 3. Since only root can access to the USB devices directly, you can |
| 286 | either launch QEMU as root or change the permissions of the USB |
| 287 | devices you want to use. For testing, the following suffices: |
| 288 | |
| 289 | :: |
| 290 | |
| 291 | chown -R myuid /proc/bus/usb |
| 292 | |
| 293 | 4. Launch QEMU and do in the monitor: |
| 294 | |
| 295 | :: |
| 296 | |
| 297 | info usbhost |
| 298 | Device 1.2, speed 480 Mb/s |
| 299 | Class 00: USB device 1234:5678, USB DISK |
| 300 | |
| 301 | You should see the list of the devices you can use (Never try to use |
| 302 | hubs, it won't work). |
| 303 | |
| 304 | 5. Add the device in QEMU by using: |
| 305 | |
| 306 | :: |
| 307 | |
| 308 | device_add usb-host,vendorid=0x1234,productid=0x5678 |
| 309 | |
| 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. |
| 312 | |
| 313 | 6. Now you can try to use the host USB device in QEMU. |
| 314 | |
| 315 | When relaunching QEMU, you may have to unplug and plug again the USB |
| 316 | device to make it work again (this is a bug). |
| 317 | |
| 318 | ``usb-host`` properties for specifying the host device |
| 319 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 320 | |
| 321 | The example above uses the ``vendorid`` and ``productid`` to |
| 322 | specify which host device to pass through, but this is not |
| 323 | the only way to specify the host device. ``usb-host`` supports |
| 324 | the following properties: |
| 325 | |
| 326 | ``hostbus=<nr>`` |
| 327 | Specifies the bus number the device must be attached to |
| 328 | ``hostaddr=<nr>`` |
| 329 | Specifies the device address the device got assigned by the guest os |
| 330 | ``hostport=<str>`` |
| 331 | Specifies the physical port the device is attached to |
| 332 | ``vendorid=<hexnr>`` |
| 333 | Specifies the vendor ID of the device |
| 334 | ``productid=<hexnr>`` |
| 335 | Specifies the product ID of the device. |
| 336 | |
| 337 | In theory you can combine all these properties as you like. In |
| 338 | practice only a few combinations are useful: |
| 339 | |
| 340 | - ``vendorid`` and ``productid`` -- match for a specific device, pass it to |
| 341 | the guest when it shows up somewhere in the host. |
| 342 | |
| 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 |
| 345 | guest. |
| 346 | |
| 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 |
| 349 | will get a new hostaddr. |
| 350 | |
| 351 | Note that on the host USB 1.1 devices are handled by UHCI/OHCI and USB |
| 352 | 2.0 by EHCI. That means different USB devices plugged into the very |
| 353 | same physical port on the host may show up on different host buses |
| 354 | depending on the speed. Supposing that devices plugged into a given |
| 355 | physical port appear as bus 1 + port 1 for 2.0 devices and bus 3 + port 1 |
| 356 | for 1.1 devices, you can pass through any device plugged into that port |
| 357 | and also assign it to the correct USB bus in QEMU like this: |
| 358 | |
| 359 | .. parsed-literal:: |
| 360 | |
| 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 |
| 366 | |
| 367 | ``usb-host`` properties for reset behavior |
| 368 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 369 | |
| 370 | The ``guest-reset`` and ``guest-reset-all`` properties control |
| 371 | whenever the guest is allowed to reset the physical usb device on the |
| 372 | host. There are three cases: |
| 373 | |
| 374 | ``guest-reset=false`` |
| 375 | The guest is not allowed to reset the (physical) usb device. |
| 376 | |
| 377 | ``guest-reset=true,guest-resets-all=false`` |
| 378 | The guest is allowed to reset the device when it is not yet |
| 379 | initialized (aka no usb bus address assigned). Usually this results |
| 380 | in one guest reset being allowed. This is the default behavior. |
| 381 | |
| 382 | ``guest-reset=true,guest-resets-all=true`` |
| 383 | The guest is allowed to reset the device as it pleases. |
| 384 | |
| 385 | The reason for this existing are broken usb devices. In theory one |
| 386 | should be able to reset (and re-initialize) usb devices at any time. |
| 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 |
| 389 | and re-plug) it. |
| 390 | |
| 391 | What works best pretty much depends on the behavior of the specific |
| 392 | usb device at hand, so it's a trial-and-error game. If the default |
| 393 | doesn't work, try another option and see whenever the situation |
| 394 | improves. |
| 395 | |
| 396 | record usb transfers |
| 397 | ^^^^^^^^^^^^^^^^^^^^ |
| 398 | |
| 399 | All usb devices have support for recording the usb traffic. This can |
| 400 | be enabled using the ``pcap=<file>`` property, for example: |
| 401 | |
| 402 | ``-device usb-mouse,pcap=mouse.pcap`` |
| 403 | |
| 404 | The pcap files are compatible with the linux kernels usbmon. Many |
| 405 | tools, including ``wireshark``, can decode and inspect these trace |
| 406 | files. |