qapi: add missing colon-ending for section name
[qemu/armbru.git] / docs / usb-storage.txt
blobfbc1f2edd81a4fb3b7bec703e259820ca70f9c8a
2 qemu usb storage emulation
3 --------------------------
5 QEMU has three devices for usb storage emulation.
7 Number one emulates the classic bulk-only transport protocol which is
8 used by 99% of the usb sticks on the market today and is called
9 "usb-storage".  Usage (hooking up to xhci, other host controllers work
10 too):
12   qemu ${other_vm_args}                                \
13        -drive if=none,id=stick,file=/path/to/file.img  \
14        -device nec-usb-xhci,id=xhci                    \
15        -device usb-storage,bus=xhci.0,drive=stick
18 Number two is the newer usb attached scsi transport.  This one doesn't
19 automagically create a scsi disk, so you have to explicitly attach one
20 manually.  Multiple logical units are supported.  Here is an example
21 with tree logical units:
23   qemu ${other_vm_args}                                                \
24        -drive if=none,id=uas-disk1,file=/path/to/file1.img             \
25        -drive if=none,id=uas-disk2,file=/path/to/file2.img             \
26        -drive if=none,id=uas-cdrom,media=cdrom,file=/path/to/image.iso \
27        -device nec-usb-xhci,id=xhci                                    \
28        -device usb-uas,id=uas,bus=xhci.0                               \
29        -device scsi-hd,bus=uas.0,scsi-id=0,lun=0,drive=uas-disk1       \
30        -device scsi-hd,bus=uas.0,scsi-id=0,lun=1,drive=uas-disk2       \
31        -device scsi-cd,bus=uas.0,scsi-id=0,lun=5,drive=uas-cdrom
34 Number three emulates the classic bulk-only transport protocol too.
35 It's called "usb-bot".  It shares most code with "usb-storage", and
36 the guest will not be able to see the difference.  The qemu command
37 line interface is simliar to usb-uas though, i.e. no automatic scsi
38 disk creation.  It also features support for up to 16 LUNs.  The LUN
39 numbers must be continuous, i.e. for three devices you must use 0+1+2.
40 The 0+1+5 numbering from the "usb-uas" example isn't going to work
41 with "usb-bot".
43 Starting with qemu version 2.7 usb-bot and usb-uas devices can be
44 hotplugged.  In the hotplug case they are added with "attached =
45 false" so the guest will not see the device until the "attached"
46 property is explicitly set to true.  That allows to attach one or more
47 scsi devices before making the device visible to the guest, i.e. the
48 workflow looks like this:
50    (1) device-add usb-bot,id=foo
51    (2) device-add scsi-{hd,cd},bus=foo.0,lun=0
52    (2b) optionally add more devices (luns 1 ... 15).
53    (3) scripts/qmp/qom-set foo.attached = true
55 enjoy,
56   Gerd
59 Gerd Hoffmann <kraxel@redhat.com>