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 16 a single memory/DMA buffer will be useable for bulk-in and bulk-out 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 23 using it, and how it differs from File Storage Gadget (or FSG). It 24 will talk only briefly about how to use MSF within composite 25 gadgets. 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 \xE2\x80\x9Cluns\xE2\x80\x9D 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. \xE2\x80\x9Cb\xE2\x80\x9D here is either \xE2\x80\x9Cy\xE2\x80\x9D, \xE2\x80\x9CY\xE2\x80\x9D or \xE2\x80\x9C1\xE2\x80\x9D for true or \xE2\x80\x9Cn\xE2\x80\x9D, 54 \xE2\x80\x9CN\xE2\x80\x9D or \xE2\x80\x9C0\xE2\x80\x9D for false. 55 56 If this option is set for a logical unit, gadget will accept an 57 \xE2\x80\x9Ceject\xE2\x80\x9D 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 \xE2\x80\x9Csysfs entries\xE2\x80\x9D 61 section). 62 63 If a logical unit is not removable (the default), a backing file 64 must be specified for it with the \xE2\x80\x9Cfile\xE2\x80\x9D 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 \xE2\x80\x9Cn\xE2\x80\x9D needs to be specified now. 74 75 Note that \xE2\x80\x9Cremovable\xE2\x80\x9D 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 \xE2\x80\x9Chot-unpluggable\xE2\x80\x9D. 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 \xE2\x80\x9CRemoval optimised mode\xE2\x80\x9D 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 \xE2\x80\x9Cfile\xE2\x80\x9D argument is greater then the value of \xE2\x80\x9Cluns\xE2\x80\x9D, 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 \xE2\x80\x9Cfile\xE2\x80\x9D 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) 201 while file storage gadget is a traditional gadget. From userspace 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 207 Because of that, File Storage Gadget has been deprecated and 208 scheduled to be removed in Linux 3.8. All users need to transition 209 to the Mass Storage Gadget by that time. The two gadgets behave 210 mostly the same from the outside except: 211 212 1. In FSG the \xE2\x80\x9Cremovable\xE2\x80\x9D and \xE2\x80\x9Ccdrom\xE2\x80\x9D module parameters set the flag 213 for all logical units whereas in MSG they accept a list of y/n 214 values for each logical unit. If one uses only a single logical 215 unit this does not matter, but if there are more, the y/n value 216 needs to be repeated for each logical unit. 217 218 2. FSG's \xE2\x80\x9Cserial\xE2\x80\x9D, \xE2\x80\x9Cvendor\xE2\x80\x9D, \xE2\x80\x9Cproduct\xE2\x80\x9D and \xE2\x80\x9Crelease\xE2\x80\x9D module 219 parameters are handled in MSG by the composite layer's parameters 220 named respectively: \xE2\x80\x9CiSerialnumber\xE2\x80\x9D, \xE2\x80\x9CidVendor\xE2\x80\x9D, \xE2\x80\x9CidProduct\xE2\x80\x9D and 221 \xE2\x80\x9CbcdDevice\xE2\x80\x9D. 222 223 3. MSG does not support FSG's test mode, thus \xE2\x80\x9Ctransport\xE2\x80\x9D, 224 \xE2\x80\x9Cprotocol\xE2\x80\x9D and \xE2\x80\x9Cbuflen\xE2\x80\x9D FSG's module parameters are not 225 supported. MSG always uses SCSI protocol with bulk only 226 transport mode and 16 KiB buffers. 227