docs: Incorporate information in usb-storage.txt into rST manual

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>
This commit is contained in:
Peter Maydell 2021-07-28 15:14:54 +01:00 committed by Gerd Hoffmann
parent 5e796671e6
commit 2a49e4e927
3 changed files with 51 additions and 67 deletions

View File

@ -1836,7 +1836,7 @@ S: Maintained
F: hw/usb/*
F: stubs/usb-dev-stub.c
F: tests/qtest/usb-*-test.c
F: docs/usb2.txt
F: docs/system/devices/usb.rst
F: docs/usb-storage.txt
F: include/hw/usb.h
F: include/hw/usb/

View File

@ -28,17 +28,46 @@ option or the ``device_add`` monitor command. Available devices are:
``usb-storage,drive=drive_id``
Mass storage device backed by drive_id (see the :ref:`disk images`
chapter in the System Emulation Users Guide)
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, see
`usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
for details
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, see
`usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
for details here, too
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
@ -84,6 +113,20 @@ option or the ``device_add`` monitor command. Available devices are:
``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

View File

@ -1,59 +0,0 @@
qemu usb storage emulation
--------------------------
QEMU has three devices for usb storage emulation.
Number one emulates the classic bulk-only transport protocol which is
used by 99% of the usb sticks on the market today and is called
"usb-storage". Usage (hooking up to xhci, other host controllers work
too):
qemu ${other_vm_args} \
-drive if=none,id=stick,file=/path/to/file.img \
-device nec-usb-xhci,id=xhci \
-device usb-storage,bus=xhci.0,drive=stick
Number two is the newer usb attached scsi transport. This one doesn't
automagically create a scsi disk, so you have to explicitly attach one
manually. Multiple logical units are supported. Here is an example
with tree logical units:
qemu ${other_vm_args} \
-drive if=none,id=uas-disk1,file=/path/to/file1.img \
-drive if=none,id=uas-disk2,file=/path/to/file2.img \
-drive if=none,id=uas-cdrom,media=cdrom,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
Number three emulates the classic bulk-only transport protocol too.
It's called "usb-bot". It shares most code with "usb-storage", and
the guest will not be able to see the difference. The qemu command
line interface is similar to usb-uas though, i.e. no automatic scsi
disk creation. It also features support for up to 16 LUNs. 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 isn't going to work
with "usb-bot".
Starting with qemu version 2.7 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 to attach one or more
scsi devices before making the device visible to the guest, i.e. the
workflow looks like this:
(1) device-add usb-bot,id=foo
(2) device-add scsi-{hd,cd},bus=foo.0,lun=0
(2b) optionally add more devices (luns 1 ... 15).
(3) scripts/qmp/qom-set foo.attached = true
enjoy,
Gerd
--
Gerd Hoffmann <kraxel@redhat.com>