Michal Nazarewicz | a8287a4 | 2012-06-12 12:42:18 +0200 | [diff] [blame] | 1 | * Overview |
| 2 | |
| 3 | Mass Storage Gadget (or MSG) acts as a USB Mass Storage device, |
| 4 | appearing to the host as a disk or a CD-ROM drive. It supports |
| 5 | multiple logical units (LUNs). Backing storage for each LUN is |
| 6 | provided by a regular file or a block device, access can be limited |
| 7 | to read-only, and gadget can indicate that it is removable and/or |
| 8 | CD-ROM (the latter implies read-only access). |
| 9 | |
| 10 | Its requirements are modest; only a bulk-in and a bulk-out endpoint |
| 11 | are needed. The memory requirement amounts to two 16K buffers. |
| 12 | Support is included for full-speed, high-speed and SuperSpeed |
| 13 | operation. |
| 14 | |
| 15 | Note that the driver is slightly non-portable in that it assumes |
Carlos Garcia | c98be0c | 2014-04-04 22:31:00 -0400 | [diff] [blame] | 16 | a single memory/DMA buffer will be usable for bulk-in and bulk-out |
Michal Nazarewicz | a8287a4 | 2012-06-12 12:42:18 +0200 | [diff] [blame] | 17 | endpoints. With most device controllers this is not an issue, but |
| 18 | there may be some with hardware restrictions that prevent a buffer |
| 19 | from being used by more than one endpoint. |
| 20 | |
| 21 | This document describes how to use the gadget from user space, its |
| 22 | relation to mass storage function (or MSF) and different gadgets |
Michal Nazarewicz | fa06920 | 2012-11-06 22:52:36 +0100 | [diff] [blame] | 23 | using it, and how it differs from File Storage Gadget (or FSG) |
| 24 | (which is no longer included in Linux). It will talk only briefly |
| 25 | about how to use MSF within composite gadgets. |
Michal Nazarewicz | a8287a4 | 2012-06-12 12:42:18 +0200 | [diff] [blame] | 26 | |
| 27 | * Module parameters |
| 28 | |
| 29 | The mass storage gadget accepts the following mass storage specific |
| 30 | module parameters: |
| 31 | |
| 32 | - file=filename[,filename...] |
| 33 | |
| 34 | This parameter lists paths to files or block devices used for |
| 35 | backing storage for each logical unit. There may be at most |
| 36 | FSG_MAX_LUNS (8) LUNs set. If more files are specified, they will |
| 37 | be silently ignored. See also “luns” parameter. |
| 38 | |
| 39 | *BEWARE* that if a file is used as a backing storage, it may not |
| 40 | be modified by any other process. This is because the host |
| 41 | assumes the data does not change without its knowledge. It may be |
| 42 | read, but (if the logical unit is writable) due to buffering on |
| 43 | the host side, the contents are not well defined. |
| 44 | |
| 45 | The size of the logical unit will be rounded down to a full |
| 46 | logical block. The logical block size is 2048 bytes for LUNs |
| 47 | simulating CD-ROM, block size of the device if the backing file is |
| 48 | a block device, or 512 bytes otherwise. |
| 49 | |
| 50 | - removable=b[,b...] |
| 51 | |
| 52 | This parameter specifies whether each logical unit should be |
| 53 | removable. “b” here is either “y”, “Y” or “1” for true or “n”, |
| 54 | “N” or “0” for false. |
| 55 | |
| 56 | If this option is set for a logical unit, gadget will accept an |
| 57 | “eject” SCSI request (Start/Stop Unit). When it is sent, the |
| 58 | backing file will be closed to simulate ejection and the logical |
| 59 | unit will not be mountable by the host until a new backing file is |
| 60 | specified by userspace on the device (see “sysfs entries” |
| 61 | section). |
| 62 | |
| 63 | If a logical unit is not removable (the default), a backing file |
| 64 | must be specified for it with the “file” parameter as the module |
| 65 | is loaded. The same applies if the module is built in, no |
| 66 | exceptions. |
| 67 | |
| 68 | The default value of the flag is false, *HOWEVER* it used to be |
| 69 | true. This has been changed to better match File Storage Gadget |
| 70 | and because it seems like a saner default after all. Thus to |
| 71 | maintain compatibility with older kernels, it's best to specify |
| 72 | the default values. Also, if one relied on old default, explicit |
| 73 | “n” needs to be specified now. |
| 74 | |
| 75 | Note that “removable” means the logical unit's media can be |
| 76 | ejected or removed (as is true for a CD-ROM drive or a card |
| 77 | reader). It does *not* mean that the entire gadget can be |
| 78 | unplugged from the host; the proper term for that is |
| 79 | “hot-unpluggable”. |
| 80 | |
| 81 | - cdrom=b[,b...] |
| 82 | |
| 83 | This parameter specifies whether each logical unit should simulate |
| 84 | CD-ROM. The default is false. |
| 85 | |
| 86 | - ro=b[,b...] |
| 87 | |
| 88 | This parameter specifies whether each logical unit should be |
| 89 | reported as read only. This will prevent host from modifying the |
| 90 | backing files. |
| 91 | |
| 92 | Note that if this flag for given logical unit is false but the |
| 93 | backing file could not be opened in read/write mode, the gadget |
| 94 | will fall back to read only mode anyway. |
| 95 | |
| 96 | The default value for non-CD-ROM logical units is false; for |
| 97 | logical units simulating CD-ROM it is forced to true. |
| 98 | |
| 99 | - nofua=b[,b...] |
| 100 | |
| 101 | This parameter specifies whether FUA flag should be ignored in SCSI |
| 102 | Write10 and Write12 commands sent to given logical units. |
| 103 | |
| 104 | MS Windows mounts removable storage in “Removal optimised mode” by |
| 105 | default. All the writes to the media are synchronous, which is |
| 106 | achieved by setting the FUA (Force Unit Access) bit in SCSI |
| 107 | Write(10,12) commands. This forces each write to wait until the |
| 108 | data has actually been written out and prevents I/O requests |
| 109 | aggregation in block layer dramatically decreasing performance. |
| 110 | |
| 111 | Note that this may mean that if the device is powered from USB and |
| 112 | the user unplugs the device without unmounting it first (which at |
| 113 | least some Windows users do), the data may be lost. |
| 114 | |
| 115 | The default value is false. |
| 116 | |
| 117 | - luns=N |
| 118 | |
| 119 | This parameter specifies number of logical units the gadget will |
| 120 | have. It is limited by FSG_MAX_LUNS (8) and higher value will be |
| 121 | capped. |
| 122 | |
| 123 | If this parameter is provided, and the number of files specified |
| 124 | in “file” argument is greater then the value of “luns”, all excess |
| 125 | files will be ignored. |
| 126 | |
| 127 | If this parameter is not present, the number of logical units will |
| 128 | be deduced from the number of files specified in the “file” |
| 129 | parameter. If the file parameter is missing as well, one is |
| 130 | assumed. |
| 131 | |
| 132 | - stall=b |
| 133 | |
| 134 | Specifies whether the gadget is allowed to halt bulk endpoints. |
| 135 | The default is determined according to the type of USB device |
| 136 | controller, but usually true. |
| 137 | |
| 138 | In addition to the above, the gadget also accepts the following |
| 139 | parameters defined by the composite framework (they are common to |
| 140 | all composite gadgets so just a quick listing): |
| 141 | |
| 142 | - idVendor -- USB Vendor ID (16 bit integer) |
| 143 | - idProduct -- USB Product ID (16 bit integer) |
| 144 | - bcdDevice -- USB Device version (BCD) (16 bit integer) |
| 145 | - iManufacturer -- USB Manufacturer string (string) |
| 146 | - iProduct -- USB Product string (string) |
| 147 | - iSerialNumber -- SerialNumber string (sting) |
| 148 | |
| 149 | * sysfs entries |
| 150 | |
| 151 | For each logical unit, the gadget creates a directory in the sysfs |
| 152 | hierarchy. Inside of it the following three files are created: |
| 153 | |
| 154 | - file |
| 155 | |
| 156 | When read it returns the path to the backing file for the given |
| 157 | logical unit. If there is no backing file (possible only if the |
| 158 | logical unit is removable), the content is empty. |
| 159 | |
| 160 | When written into, it changes the backing file for given logical |
| 161 | unit. This change can be performed even if given logical unit is |
| 162 | not specified as removable (but that may look strange to the |
| 163 | host). It may fail, however, if host disallowed medium removal |
| 164 | with the Prevent-Allow Medium Removal SCSI command. |
| 165 | |
| 166 | - ro |
| 167 | |
| 168 | Reflects the state of ro flag for the given logical unit. It can |
| 169 | be read any time, and written to when there is no backing file |
| 170 | open for given logical unit. |
| 171 | |
| 172 | - nofua |
| 173 | |
| 174 | Reflects the state of nofua flag for given logical unit. It can |
| 175 | be read and written. |
| 176 | |
| 177 | Other then those, as usual, the values of module parameters can be |
| 178 | read from /sys/module/g_mass_storage/parameters/* files. |
| 179 | |
| 180 | * Other gadgets using mass storage function |
| 181 | |
| 182 | The Mass Storage Gadget uses the Mass Storage Function to handle |
| 183 | mass storage protocol. As a composite function, MSF may be used by |
| 184 | other gadgets as well (eg. g_multi and acm_ms). |
| 185 | |
| 186 | All of the information in previous sections are valid for other |
| 187 | gadgets using MSF, except that support for mass storage related |
| 188 | module parameters may be missing, or the parameters may have |
| 189 | a prefix. To figure out whether any of this is true one needs to |
| 190 | consult the gadget's documentation or its source code. |
| 191 | |
| 192 | For examples of how to include mass storage function in gadgets, one |
| 193 | may take a look at mass_storage.c, acm_ms.c and multi.c (sorted by |
| 194 | complexity). |
| 195 | |
| 196 | * Relation to file storage gadget |
| 197 | |
| 198 | The Mass Storage Function and thus the Mass Storage Gadget has been |
| 199 | based on the File Storage Gadget. The difference between the two is |
| 200 | that MSG is a composite gadget (ie. uses the composite framework) |
Michal Nazarewicz | fa06920 | 2012-11-06 22:52:36 +0100 | [diff] [blame] | 201 | while file storage gadget was a traditional gadget. From userspace |
Michal Nazarewicz | a8287a4 | 2012-06-12 12:42:18 +0200 | [diff] [blame] | 202 | point of view this distinction does not really matter, but from |
| 203 | kernel hacker's point of view, this means that (i) MSG does not |
| 204 | duplicate code needed for handling basic USB protocol commands and |
| 205 | (ii) MSF can be used in any other composite gadget. |
| 206 | |
Michal Nazarewicz | fa06920 | 2012-11-06 22:52:36 +0100 | [diff] [blame] | 207 | Because of that, File Storage Gadget has been removed in Linux 3.8. |
| 208 | All users need to transition to the Mass Storage Gadget. The two |
| 209 | gadgets behave mostly the same from the outside except: |
Michal Nazarewicz | a8287a4 | 2012-06-12 12:42:18 +0200 | [diff] [blame] | 210 | |
| 211 | 1. In FSG the “removable” and “cdrom” module parameters set the flag |
| 212 | for all logical units whereas in MSG they accept a list of y/n |
| 213 | values for each logical unit. If one uses only a single logical |
| 214 | unit this does not matter, but if there are more, the y/n value |
| 215 | needs to be repeated for each logical unit. |
| 216 | |
| 217 | 2. FSG's “serial”, “vendor”, “product” and “release” module |
| 218 | parameters are handled in MSG by the composite layer's parameters |
| 219 | named respectively: “iSerialnumber”, “idVendor”, “idProduct” and |
| 220 | “bcdDevice”. |
| 221 | |
| 222 | 3. MSG does not support FSG's test mode, thus “transport”, |
| 223 | “protocol” and “buflen” FSG's module parameters are not |
| 224 | supported. MSG always uses SCSI protocol with bulk only |
| 225 | transport mode and 16 KiB buffers. |