linux/Documentation/usb/mass-storage.txt
<<
>>
Prefs
   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 useable 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).  It
  24  will talk only briefly about how to use MSF within composite
  25  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 is 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 deprecated and
 208  scheduled to be removed in Linux 3.8.  All users need to transition
 209  to the Mass Storage Gadget by that time.  The two gadgets behave
 210  mostly the same from the outside except:
 211
 212  1. In FSG the “removable” and “cdrom” module parameters set the flag
 213     for all logical units whereas in MSG they accept a list of y/n
 214     values for each logical unit.  If one uses only a single logical
 215     unit this does not matter, but if there are more, the y/n value
 216     needs to be repeated for each logical unit.
 217
 218  2. FSG's “serial”, “vendor”, “product” and “release” module
 219     parameters are handled in MSG by the composite layer's parameters
 220     named respectively: “iSerialnumber”, “idVendor”, “idProduct” and
 221     “bcdDevice”.
 222
 223  3. MSG does not support FSG's test mode, thus “transport”,
 224     “protocol” and “buflen” FSG's module parameters are not
 225     supported.  MSG always uses SCSI protocol with bulk only
 226     transport mode and 16 KiB buffers.
 227
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.