About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / mass-storage.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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 usable 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)
24	  (which is no longer included in Linux).  It will talk only briefly
25	  about how to use MSF within composite 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 “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)
201	  while file storage gadget was 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 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:
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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog