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