Commit | Line | Data |
---|---|---|
d80b5005 MCC |
1 | ========================= |
2 | Mass Storage Gadget (MSG) | |
3 | ========================= | |
4 | ||
5 | Overview | |
6 | ======== | |
a8287a4e MN |
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 | |
c98be0c9 | 21 | a single memory/DMA buffer will be usable for bulk-in and bulk-out |
a8287a4e MN |
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 | |
fa06920a MN |
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. | |
a8287a4e | 31 | |
d80b5005 MCC |
32 | Module parameters |
33 | ================= | |
a8287a4e MN |
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 | ||
d80b5005 MCC |
155 | sysfs entries |
156 | ============= | |
a8287a4e MN |
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 | ||
d80b5005 MCC |
187 | Other gadgets using mass storage function |
188 | ========================================= | |
a8287a4e MN |
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 | ||
d80b5005 MCC |
204 | Relation to file storage gadget |
205 | =============================== | |
a8287a4e MN |
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) | |
fa06920a | 210 | while file storage gadget was a traditional gadget. From userspace |
a8287a4e MN |
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 | ||
fa06920a MN |
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: | |
a8287a4e MN |
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. |