2a49e4e927
We already have a section on USB in the rST manual; fold the information in docs/usb-storage.txt into it. We add 'format=raw' to the various -drive options in the code examples, because QEMU will print warnings these days if you omit it. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20210728141457.14825-2-peter.maydell@linaro.org> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
184 lines
6.5 KiB
ReStructuredText
184 lines
6.5 KiB
ReStructuredText
.. _pcsys_005fusb:
|
|
|
|
USB emulation
|
|
-------------
|
|
|
|
QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
|
|
plug virtual USB devices or real host USB devices (only works with
|
|
certain host operating systems). QEMU will automatically create and
|
|
connect virtual USB hubs as necessary to connect multiple USB devices.
|
|
|
|
.. _Connecting USB devices:
|
|
|
|
Connecting USB devices
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
USB devices can be connected with the ``-device usb-...`` command line
|
|
option or the ``device_add`` monitor command. Available devices are:
|
|
|
|
``usb-mouse``
|
|
Virtual Mouse. This will override the PS/2 mouse emulation when
|
|
activated.
|
|
|
|
``usb-tablet``
|
|
Pointer device that uses absolute coordinates (like a touchscreen).
|
|
This means QEMU is able to report the mouse position without having
|
|
to grab the mouse. Also overrides the PS/2 mouse emulation when
|
|
activated.
|
|
|
|
``usb-storage,drive=drive_id``
|
|
Mass storage device backed by drive_id (see the :ref:`disk images`
|
|
chapter in the System Emulation Users Guide). This is the classic
|
|
bulk-only transport protocol used by 99% of USB sticks. This
|
|
example shows it connected to an XHCI USB controller and with
|
|
a drive backed by a raw format disk image:
|
|
|
|
.. parsed-literal::
|
|
|
|
|qemu_system| [...] \\
|
|
-drive if=none,id=stick,format=raw,file=/path/to/file.img \\
|
|
-device nec-usb-xhci,id=xhci \\
|
|
-device usb-storage,bus=xhci.0,drive=stick
|
|
|
|
``usb-uas``
|
|
USB attached SCSI device. This does not create a SCSI disk, so
|
|
you need to explicitly create a ``scsi-hd`` or ``scsi-cd`` device
|
|
on the command line, as well as using the ``-drive`` option to
|
|
specify what those disks are backed by. One ``usb-uas`` device can
|
|
handle multiple logical units (disks). This example creates three
|
|
logical units: two disks and one cdrom drive:
|
|
|
|
.. parsed-literal::
|
|
|
|
|qemu_system| [...] \\
|
|
-drive if=none,id=uas-disk1,format=raw,file=/path/to/file1.img \\
|
|
-drive if=none,id=uas-disk2,format=raw,file=/path/to/file2.img \\
|
|
-drive if=none,id=uas-cdrom,media=cdrom,format=raw,file=/path/to/image.iso \\
|
|
-device nec-usb-xhci,id=xhci \\
|
|
-device usb-uas,id=uas,bus=xhci.0 \\
|
|
-device scsi-hd,bus=uas.0,scsi-id=0,lun=0,drive=uas-disk1 \\
|
|
-device scsi-hd,bus=uas.0,scsi-id=0,lun=1,drive=uas-disk2 \\
|
|
-device scsi-cd,bus=uas.0,scsi-id=0,lun=5,drive=uas-cdrom
|
|
|
|
``usb-bot``
|
|
Bulk-only transport storage device. This presents the guest with the
|
|
same USB bulk-only transport protocol interface as ``usb-storage``, but
|
|
the QEMU command line option works like ``usb-uas`` and does not
|
|
automatically create SCSI disks for you. ``usb-bot`` supports up to
|
|
16 LUNs. Unlike ``usb-uas``, the LUN numbers must be continuous,
|
|
i.e. for three devices you must use 0+1+2. The 0+1+5 numbering from the
|
|
``usb-uas`` example above won't work with ``usb-bot``.
|
|
|
|
``usb-mtp,rootdir=dir``
|
|
Media transfer protocol device, using dir as root of the file tree
|
|
that is presented to the guest.
|
|
|
|
``usb-host,hostbus=bus,hostaddr=addr``
|
|
Pass through the host device identified by bus and addr
|
|
|
|
``usb-host,vendorid=vendor,productid=product``
|
|
Pass through the host device identified by vendor and product ID
|
|
|
|
``usb-wacom-tablet``
|
|
Virtual Wacom PenPartner tablet. This device is similar to the
|
|
``tablet`` above but it can be used with the tslib library because in
|
|
addition to touch coordinates it reports touch pressure.
|
|
|
|
``usb-kbd``
|
|
Standard USB keyboard. Will override the PS/2 keyboard (if present).
|
|
|
|
``usb-serial,chardev=id``
|
|
Serial converter. This emulates an FTDI FT232BM chip connected to
|
|
host character device id.
|
|
|
|
``usb-braille,chardev=id``
|
|
Braille device. This will use BrlAPI to display the braille output on
|
|
a real or fake device referenced by id.
|
|
|
|
``usb-net[,netdev=id]``
|
|
Network adapter that supports CDC ethernet and RNDIS protocols. id
|
|
specifies a netdev defined with ``-netdev …,id=id``. For instance,
|
|
user-mode networking can be used with
|
|
|
|
.. parsed-literal::
|
|
|
|
|qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0
|
|
|
|
``usb-ccid``
|
|
Smartcard reader device
|
|
|
|
``usb-audio``
|
|
USB audio device
|
|
|
|
``u2f-{emulated,passthru}``
|
|
Universal Second Factor device
|
|
|
|
Hotplugging USB storage
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The ``usb-bot`` and ``usb-uas`` devices can be hotplugged. In the hotplug
|
|
case they are added with ``attached = false`` so the guest will not see
|
|
the device until the ``attached`` property is explicitly set to true.
|
|
That allows you to attach one or more scsi devices before making the
|
|
device visible to the guest. The workflow looks like this:
|
|
|
|
#. ``device-add usb-bot,id=foo``
|
|
#. ``device-add scsi-{hd,cd},bus=foo.0,lun=0``
|
|
#. optionally add more devices (luns 1 ... 15)
|
|
#. ``scripts/qmp/qom-set foo.attached = true``
|
|
|
|
.. _host_005fusb_005fdevices:
|
|
|
|
Using host USB devices on a Linux host
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
WARNING: this is an experimental feature. QEMU will slow down when using
|
|
it. USB devices requiring real time streaming (i.e. USB Video Cameras)
|
|
are not supported yet.
|
|
|
|
1. If you use an early Linux 2.4 kernel, verify that no Linux driver is
|
|
actually using the USB device. A simple way to do that is simply to
|
|
disable the corresponding kernel module by renaming it from
|
|
``mydriver.o`` to ``mydriver.o.disabled``.
|
|
|
|
2. Verify that ``/proc/bus/usb`` is working (most Linux distributions
|
|
should enable it by default). You should see something like that:
|
|
|
|
::
|
|
|
|
ls /proc/bus/usb
|
|
001 devices drivers
|
|
|
|
3. Since only root can access to the USB devices directly, you can
|
|
either launch QEMU as root or change the permissions of the USB
|
|
devices you want to use. For testing, the following suffices:
|
|
|
|
::
|
|
|
|
chown -R myuid /proc/bus/usb
|
|
|
|
4. Launch QEMU and do in the monitor:
|
|
|
|
::
|
|
|
|
info usbhost
|
|
Device 1.2, speed 480 Mb/s
|
|
Class 00: USB device 1234:5678, USB DISK
|
|
|
|
You should see the list of the devices you can use (Never try to use
|
|
hubs, it won't work).
|
|
|
|
5. Add the device in QEMU by using:
|
|
|
|
::
|
|
|
|
device_add usb-host,vendorid=0x1234,productid=0x5678
|
|
|
|
Normally the guest OS should report that a new USB device is plugged.
|
|
You can use the option ``-device usb-host,...`` to do the same.
|
|
|
|
6. Now you can try to use the host USB device in QEMU.
|
|
|
|
When relaunching QEMU, you may have to unplug and plug again the USB
|
|
device to make it work again (this is a bug).
|