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
Gerd Hoffmann
parent
5e796671e6
commit
2a49e4e927
@ -1836,7 +1836,7 @@ S: Maintained
|
|||||||
F: hw/usb/*
|
F: hw/usb/*
|
||||||
F: stubs/usb-dev-stub.c
|
F: stubs/usb-dev-stub.c
|
||||||
F: tests/qtest/usb-*-test.c
|
F: tests/qtest/usb-*-test.c
|
||||||
F: docs/usb2.txt
|
F: docs/system/devices/usb.rst
|
||||||
F: docs/usb-storage.txt
|
F: docs/usb-storage.txt
|
||||||
F: include/hw/usb.h
|
F: include/hw/usb.h
|
||||||
F: include/hw/usb/
|
F: include/hw/usb/
|
||||||
|
|||||||
@ -28,17 +28,46 @@ option or the ``device_add`` monitor command. Available devices are:
|
|||||||
|
|
||||||
``usb-storage,drive=drive_id``
|
``usb-storage,drive=drive_id``
|
||||||
Mass storage device backed by drive_id (see the :ref:`disk images`
|
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-uas``
|
||||||
USB attached SCSI device, see
|
USB attached SCSI device. This does not create a SCSI disk, so
|
||||||
`usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
|
you need to explicitly create a ``scsi-hd`` or ``scsi-cd`` device
|
||||||
for details
|
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``
|
``usb-bot``
|
||||||
Bulk-only transport storage device, see
|
Bulk-only transport storage device. This presents the guest with the
|
||||||
`usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
|
same USB bulk-only transport protocol interface as ``usb-storage``, but
|
||||||
for details here, too
|
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``
|
``usb-mtp,rootdir=dir``
|
||||||
Media transfer protocol device, using dir as root of the file tree
|
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}``
|
``u2f-{emulated,passthru}``
|
||||||
Universal Second Factor device
|
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:
|
.. _host_005fusb_005fdevices:
|
||||||
|
|
||||||
Using host USB devices on a Linux host
|
Using host USB devices on a Linux host
|
||||||
|
|||||||
@ -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>
|
|
||||||
Loading…
Reference in New Issue
Block a user