mass-storage.rst 9.7 KB

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