diff options
| -rw-r--r-- | MAINTAINERS | 2 | ||||
| -rw-r--r-- | docs/system/devices/usb.rst | 57 | ||||
| -rw-r--r-- | docs/usb-storage.txt | 59 |
3 files changed, 51 insertions, 67 deletions
diff --git a/MAINTAINERS b/MAINTAINERS index 42ac45c3e5..b1f8e82bef 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 eeab78dcfb..7da142ecbb 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 diff --git a/docs/usb-storage.txt b/docs/usb-storage.txt deleted file mode 100644 index 551af6f88b..0000000000 --- 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> |