Documentation/usb/mass-storage.rst

   1 =========================
   2 Mass Storage Gadget (MSG)
   3 =========================
   4
   5 Overview
   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
  32 Module 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
 155 sysfs 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
 196 Other 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
 213 Relation 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.