From: Gerd Hoffmann <kraxel@redhat.com>
To: qemu-devel@nongnu.org
Cc: "Peter Maydell" <peter.maydell@linaro.org>,
"Thomas Huth" <thuth@redhat.com>,
"Philippe Mathieu-Daudé" <f4bug@amsat.org>,
"Wainer dos Santos Moschetta" <wainersm@redhat.com>,
"Willian Rampazzo" <willianr@redhat.com>,
"Gerd Hoffmann" <kraxel@redhat.com>,
"Alex Bennée" <alex.bennee@linaro.org>
Subject: [PULL 4/7] docs: Incorporate information in usb-storage.txt into rST manual
Date: Thu, 29 Jul 2021 14:50:41 +0200 [thread overview]
Message-ID: <20210729125044.3531457-5-kraxel@redhat.com> (raw)
In-Reply-To: <20210729125044.3531457-1-kraxel@redhat.com>
From: Peter Maydell <peter.maydell@linaro.org>
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>
---
docs/usb-storage.txt | 59 -------------------------------------
MAINTAINERS | 2 +-
docs/system/devices/usb.rst | 57 ++++++++++++++++++++++++++++++-----
3 files changed, 51 insertions(+), 67 deletions(-)
delete mode 100644 docs/usb-storage.txt
diff --git a/docs/usb-storage.txt b/docs/usb-storage.txt
deleted file mode 100644
index 551af6f88bb1..000000000000
--- a/docs/usb-storage.txt
+++ /dev/null
@@ -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>
diff --git a/MAINTAINERS b/MAINTAINERS
index 42ac45c3e502..b1f8e82befc6 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -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/
diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst
index eeab78dcfbee..7da142ecbb9f 100644
--- a/docs/system/devices/usb.rst
+++ b/docs/system/devices/usb.rst
@@ -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
--
2.31.1
next prev parent reply other threads:[~2021-07-29 12:59 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-07-29 12:50 [PULL 0/7] Usb 20210729 patches Gerd Hoffmann
2021-07-29 12:50 ` [PULL 1/7] usb-host: wire up timer for windows Gerd Hoffmann
2021-07-29 12:50 ` [PULL 2/7] ci: add libusb for windows builds Gerd Hoffmann
2021-07-29 12:50 ` [PULL 3/7] usbredir: fix free call Gerd Hoffmann
2021-07-29 12:50 ` Gerd Hoffmann [this message]
2021-07-29 12:50 ` [PULL 5/7] docs: Fold usb2.txt USB controller information into usb.rst Gerd Hoffmann
2021-07-29 12:50 ` [PULL 6/7] docs: Fold usb2.txt physical port addressing info " Gerd Hoffmann
2021-07-29 12:50 ` [PULL 7/7] docs: Fold usb2.txt passthrough information " Gerd Hoffmann
2021-07-30 8:14 ` [PULL 0/7] Usb 20210729 patches Peter Maydell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210729125044.3531457-5-kraxel@redhat.com \
--to=kraxel@redhat.com \
--cc=alex.bennee@linaro.org \
--cc=f4bug@amsat.org \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
--cc=thuth@redhat.com \
--cc=wainersm@redhat.com \
--cc=willianr@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).