1 .. _pcsys_005fusb: 2 3 USB emulation 4 ------------- 5 6 QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can 7 plug virtual USB devices or real host USB devices (only works with 8 certain host operating systems). QEMU will automatically create and 9 connect virtual USB hubs as necessary to connect multiple USB devices. 10 11 USB controllers 12 ~~~~~~~~~~~~~~~ 13 14 XHCI controller support 15 ^^^^^^^^^^^^^^^^^^^^^^^ 16 17 QEMU has XHCI host adapter support. The XHCI hardware design is much 18 more virtualization-friendly when compared to EHCI and UHCI, thus XHCI 19 emulation uses less resources (especially CPU). So if your guest 20 supports XHCI (which should be the case for any operating system 21 released around 2010 or later) we recommend using it: 22 23 qemu -device qemu-xhci 24 25 XHCI supports USB 1.1, USB 2.0 and USB 3.0 devices, so this is the 26 only controller you need. With only a single USB controller (and 27 therefore only a single USB bus) present in the system there is no 28 need to use the bus= parameter when adding USB devices. 29 30 31 EHCI controller support 32 ^^^^^^^^^^^^^^^^^^^^^^^ 33 34 The QEMU EHCI Adapter supports USB 2.0 devices. It can be used either 35 standalone or with companion controllers (UHCI, OHCI) for USB 1.1 36 devices. The companion controller setup is more convenient to use 37 because it provides a single USB bus supporting both USB 2.0 and USB 38 1.1 devices. See next section for details. 39 40 When running EHCI in standalone mode you can add UHCI or OHCI 41 controllers for USB 1.1 devices too. Each controller creates its own 42 bus though, so there are two completely separate USB buses: One USB 43 1.1 bus driven by the UHCI controller and one USB 2.0 bus driven by 44 the EHCI controller. Devices must be attached to the correct 45 controller manually. 46 47 The easiest way to add a UHCI controller to a ``pc`` machine is the 48 ``-usb`` switch. QEMU will create the UHCI controller as function of 49 the PIIX3 chipset. The USB 1.1 bus will carry the name ``usb-bus.0``. 50 51 You can use the standard ``-device`` switch to add a EHCI controller to 52 your virtual machine. It is strongly recommended to specify an ID for 53 the controller so the USB 2.0 bus gets an individual name, for example 54 ``-device usb-ehci,id=ehci``. This will give you a USB 2.0 bus named 55 ``ehci.0``. 56 57 When adding USB devices using the ``-device`` switch you can specify the 58 bus they should be attached to. Here is a complete example: 59 60 .. parsed-literal:: 61 62 |qemu_system| -M pc ${otheroptions} \\ 63 -drive if=none,id=usbstick,format=raw,file=/path/to/image \\ 64 -usb \\ 65 -device usb-ehci,id=ehci \\ 66 -device usb-tablet,bus=usb-bus.0 \\ 67 -device usb-storage,bus=ehci.0,drive=usbstick 68 69 This attaches a USB tablet to the UHCI adapter and a USB mass storage 70 device to the EHCI adapter. 71 72 73 Companion controller support 74 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 75 76 The UHCI and OHCI controllers can attach to a USB bus created by EHCI 77 as companion controllers. This is done by specifying the ``masterbus`` 78 and ``firstport`` properties. ``masterbus`` specifies the bus name the 79 controller should attach to. ``firstport`` specifies the first port the 80 controller should attach to, which is needed as usually one EHCI 81 controller with six ports has three UHCI companion controllers with 82 two ports each. 83 84 There is a config file in docs which will do all this for 85 you, which you can use like this: 86 87 .. parsed-literal:: 88 89 |qemu_system| -readconfig docs/config/ich9-ehci-uhci.cfg 90 91 Then use ``bus=ehci.0`` to assign your USB devices to that bus. 92 93 Using the ``-usb`` switch for ``q35`` machines will create a similar 94 USB controller configuration. 95 96 97 .. _Connecting USB devices: 98 99 Connecting USB devices 100 ~~~~~~~~~~~~~~~~~~~~~~ 101 102 USB devices can be connected with the ``-device usb-...`` command line 103 option or the ``device_add`` monitor command. Available devices are: 104 105 ``usb-mouse`` 106 Virtual Mouse. This will override the PS/2 mouse emulation when 107 activated. 108 109 ``usb-tablet`` 110 Pointer device that uses absolute coordinates (like a touchscreen). 111 This means QEMU is able to report the mouse position without having 112 to grab the mouse. Also overrides the PS/2 mouse emulation when 113 activated. 114 115 ``usb-storage,drive=drive_id`` 116 Mass storage device backed by drive_id (see the :ref:`disk images` 117 chapter in the System Emulation Users Guide). This is the classic 118 bulk-only transport protocol used by 99% of USB sticks. This 119 example shows it connected to an XHCI USB controller and with 120 a drive backed by a raw format disk image: 121 122 .. parsed-literal:: 123 124 |qemu_system| [...] \\ 125 -drive if=none,id=stick,format=raw,file=/path/to/file.img \\ 126 -device nec-usb-xhci,id=xhci \\ 127 -device usb-storage,bus=xhci.0,drive=stick 128 129 ``usb-uas`` 130 USB attached SCSI device. This does not create a SCSI disk, so 131 you need to explicitly create a ``scsi-hd`` or ``scsi-cd`` device 132 on the command line, as well as using the ``-drive`` option to 133 specify what those disks are backed by. One ``usb-uas`` device can 134 handle multiple logical units (disks). This example creates three 135 logical units: two disks and one cdrom drive: 136 137 .. parsed-literal:: 138 139 |qemu_system| [...] \\ 140 -drive if=none,id=uas-disk1,format=raw,file=/path/to/file1.img \\ 141 -drive if=none,id=uas-disk2,format=raw,file=/path/to/file2.img \\ 142 -drive if=none,id=uas-cdrom,media=cdrom,format=raw,file=/path/to/image.iso \\ 143 -device nec-usb-xhci,id=xhci \\ 144 -device usb-uas,id=uas,bus=xhci.0 \\ 145 -device scsi-hd,bus=uas.0,scsi-id=0,lun=0,drive=uas-disk1 \\ 146 -device scsi-hd,bus=uas.0,scsi-id=0,lun=1,drive=uas-disk2 \\ 147 -device scsi-cd,bus=uas.0,scsi-id=0,lun=5,drive=uas-cdrom 148 149 ``usb-bot`` 150 Bulk-only transport storage device. This presents the guest with the 151 same USB bulk-only transport protocol interface as ``usb-storage``, but 152 the QEMU command line option works like ``usb-uas`` and does not 153 automatically create SCSI disks for you. ``usb-bot`` supports up to 154 16 LUNs. Unlike ``usb-uas``, the LUN numbers must be continuous, 155 i.e. for three devices you must use 0+1+2. The 0+1+5 numbering from the 156 ``usb-uas`` example above won't work with ``usb-bot``. 157 158 ``usb-mtp,rootdir=dir`` 159 Media transfer protocol device, using dir as root of the file tree 160 that is presented to the guest. 161 162 ``usb-host,hostbus=bus,hostaddr=addr`` 163 Pass through the host device identified by bus and addr 164 165 ``usb-host,vendorid=vendor,productid=product`` 166 Pass through the host device identified by vendor and product ID 167 168 ``usb-wacom-tablet`` 169 Virtual Wacom PenPartner tablet. This device is similar to the 170 ``tablet`` above but it can be used with the tslib library because in 171 addition to touch coordinates it reports touch pressure. 172 173 ``usb-kbd`` 174 Standard USB keyboard. Will override the PS/2 keyboard (if present). 175 176 ``usb-serial,chardev=id`` 177 Serial converter. This emulates an FTDI FT232BM chip connected to 178 host character device id. 179 180 ``usb-braille,chardev=id`` 181 Braille device. This will use BrlAPI to display the braille output on 182 a real or fake device referenced by id. 183 184 ``usb-net[,netdev=id]`` 185 Network adapter that supports CDC ethernet and RNDIS protocols. id 186 specifies a netdev defined with ``-netdev …,id=id``. For instance, 187 user-mode networking can be used with 188 189 .. parsed-literal:: 190 191 |qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0 192 193 ``usb-ccid`` 194 Smartcard reader device 195 196 ``usb-audio`` 197 USB audio device 198 199 ``u2f-{emulated,passthru}`` 200 Universal Second Factor device 201 202 ``canokey`` 203 An Open-source Secure Key implementing FIDO2, OpenPGP, PIV and more. 204 For more information, see :ref:`canokey`. 205 206 Physical port addressing 207 ^^^^^^^^^^^^^^^^^^^^^^^^ 208 209 For all the above USB devices, by default QEMU will plug the device 210 into the next available port on the specified USB bus, or onto 211 some available USB bus if you didn't specify one explicitly. 212 If you need to, you can also specify the physical port where 213 the device will show up in the guest. This can be done using the 214 ``port`` property. UHCI has two root ports (1,2). EHCI has six root 215 ports (1-6), and the emulated (1.1) USB hub has eight ports. 216 217 Plugging a tablet into UHCI port 1 works like this:: 218 219 -device usb-tablet,bus=usb-bus.0,port=1 220 221 Plugging a hub into UHCI port 2 works like this:: 222 223 -device usb-hub,bus=usb-bus.0,port=2 224 225 Plugging a virtual USB stick into port 4 of the hub just plugged works 226 this way:: 227 228 -device usb-storage,bus=usb-bus.0,port=2.4,drive=... 229 230 In the monitor, the ``device_add` command also accepts a ``port`` 231 property specification. If you want to unplug devices too you should 232 specify some unique id which you can use to refer to the device. 233 You can then use ``device_del`` to unplug the device later. 234 For example:: 235 236 (qemu) device_add usb-tablet,bus=usb-bus.0,port=1,id=my-tablet 237 (qemu) device_del my-tablet 238 239 Hotplugging USB storage 240 ~~~~~~~~~~~~~~~~~~~~~~~ 241 242 The ``usb-bot`` and ``usb-uas`` devices can be hotplugged. In the hotplug 243 case they are added with ``attached = false`` so the guest will not see 244 the device until the ``attached`` property is explicitly set to true. 245 That allows you to attach one or more scsi devices before making the 246 device visible to the guest. The workflow looks like this: 247 248 #. ``device-add usb-bot,id=foo`` 249 #. ``device-add scsi-{hd,cd},bus=foo.0,lun=0`` 250 #. optionally add more devices (luns 1 ... 15) 251 #. ``scripts/qmp/qom-set foo.attached = true`` 252 253 .. _host_005fusb_005fdevices: 254 255 Using host USB devices on a Linux host 256 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 257 258 WARNING: this is an experimental feature. QEMU will slow down when using 259 it. USB devices requiring real time streaming (i.e. USB Video Cameras) 260 are not supported yet. 261 262 1. If you use an early Linux 2.4 kernel, verify that no Linux driver is 263 actually using the USB device. A simple way to do that is simply to 264 disable the corresponding kernel module by renaming it from 265 ``mydriver.o`` to ``mydriver.o.disabled``. 266 267 2. Verify that ``/proc/bus/usb`` is working (most Linux distributions 268 should enable it by default). You should see something like that: 269 270 :: 271 272 ls /proc/bus/usb 273 001 devices drivers 274 275 3. Since only root can access to the USB devices directly, you can 276 either launch QEMU as root or change the permissions of the USB 277 devices you want to use. For testing, the following suffices: 278 279 :: 280 281 chown -R myuid /proc/bus/usb 282 283 4. Launch QEMU and do in the monitor: 284 285 :: 286 287 info usbhost 288 Device 1.2, speed 480 Mb/s 289 Class 00: USB device 1234:5678, USB DISK 290 291 You should see the list of the devices you can use (Never try to use 292 hubs, it won't work). 293 294 5. Add the device in QEMU by using: 295 296 :: 297 298 device_add usb-host,vendorid=0x1234,productid=0x5678 299 300 Normally the guest OS should report that a new USB device is plugged. 301 You can use the option ``-device usb-host,...`` to do the same. 302 303 6. Now you can try to use the host USB device in QEMU. 304 305 When relaunching QEMU, you may have to unplug and plug again the USB 306 device to make it work again (this is a bug). 307 308 ``usb-host`` properties for specifying the host device 309 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 310 311 The example above uses the ``vendorid`` and ``productid`` to 312 specify which host device to pass through, but this is not 313 the only way to specify the host device. ``usb-host`` supports 314 the following properties: 315 316 ``hostbus=<nr>`` 317 Specifies the bus number the device must be attached to 318 ``hostaddr=<nr>`` 319 Specifies the device address the device got assigned by the guest os 320 ``hostport=<str>`` 321 Specifies the physical port the device is attached to 322 ``vendorid=<hexnr>`` 323 Specifies the vendor ID of the device 324 ``productid=<hexnr>`` 325 Specifies the product ID of the device. 326 327 In theory you can combine all these properties as you like. In 328 practice only a few combinations are useful: 329 330 - ``vendorid`` and ``productid`` -- match for a specific device, pass it to 331 the guest when it shows up somewhere in the host. 332 333 - ``hostbus`` and ``hostport`` -- match for a specific physical port in the 334 host, any device which is plugged in there gets passed to the 335 guest. 336 337 - ``hostbus`` and ``hostaddr`` -- most useful for ad-hoc pass through as the 338 hostaddr isn't stable. The next time you plug the device into the host it 339 will get a new hostaddr. 340 341 Note that on the host USB 1.1 devices are handled by UHCI/OHCI and USB 342 2.0 by EHCI. That means different USB devices plugged into the very 343 same physical port on the host may show up on different host buses 344 depending on the speed. Supposing that devices plugged into a given 345 physical port appear as bus 1 + port 1 for 2.0 devices and bus 3 + port 1 346 for 1.1 devices, you can pass through any device plugged into that port 347 and also assign it to the correct USB bus in QEMU like this: 348 349 .. parsed-literal:: 350 351 |qemu_system| -M pc [...] \\ 352 -usb \\ 353 -device usb-ehci,id=ehci \\ 354 -device usb-host,bus=usb-bus.0,hostbus=3,hostport=1 \\ 355 -device usb-host,bus=ehci.0,hostbus=1,hostport=1 356