Documentation/usb/mass-storage.rst

Source file repositories/reference/linux-study-clean/Documentation/usb/mass-storage.rst

File Facts

System
Linux kernel
Corpus path
Documentation/usb/mass-storage.rst
Extension
.rst
Size
10195 bytes
Lines
244
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=========================
Mass Storage Gadget (MSG)
=========================

Overview
========

  Mass Storage Gadget (or MSG) acts as a USB Mass Storage device,
  appearing to the host as a disk or a CD-ROM drive.  It supports
  multiple logical units (LUNs).  Backing storage for each LUN is
  provided by a regular file or a block device, access can be limited
  to read-only, and gadget can indicate that it is removable and/or
  CD-ROM (the latter implies read-only access).

  Its requirements are modest; only a bulk-in and a bulk-out endpoint
  are needed.  The memory requirement amounts to two 16K buffers.
  Support is included for full-speed, high-speed and SuperSpeed
  operation.

  Note that the driver is slightly non-portable in that it assumes
  a single memory/DMA buffer will be usable for bulk-in and bulk-out
  endpoints.  With most device controllers this is not an issue, but
  there may be some with hardware restrictions that prevent a buffer
  from being used by more than one endpoint.

  This document describes how to use the gadget from user space, its
  relation to mass storage function (or MSF) and different gadgets
  using it, and how it differs from File Storage Gadget (or FSG)
  (which is no longer included in Linux).  It will talk only briefly
  about how to use MSF within composite gadgets.

Module parameters
=================

  The mass storage gadget accepts the following mass storage specific
  module parameters:

  - file=filename[,filename...]

    This parameter lists paths to files or block devices used for
    backing storage for each logical unit.  There may be at most
    FSG_MAX_LUNS (8) LUNs set.  If more files are specified, they will
    be silently ignored.  See also “luns” parameter.

    *BEWARE* that if a file is used as a backing storage, it may not
    be modified by any other process.  This is because the host
    assumes the data does not change without its knowledge.  It may be
    read, but (if the logical unit is writable) due to buffering on
    the host side, the contents are not well defined.

    The size of the logical unit will be rounded down to a full
    logical block.  The logical block size is 2048 bytes for LUNs
    simulating CD-ROM, block size of the device if the backing file is
    a block device, or 512 bytes otherwise.

  - removable=b[,b...]

    This parameter specifies whether each logical unit should be
    removable.  “b” here is either “y”, “Y” or “1” for true or “n”,
    “N” or “0” for false.

    If this option is set for a logical unit, gadget will accept an
    “eject” SCSI request (Start/Stop Unit).  When it is sent, the
    backing file will be closed to simulate ejection and the logical
    unit will not be mountable by the host until a new backing file is
    specified by userspace on the device (see “sysfs entries”
    section).

    If a logical unit is not removable (the default), a backing file
    must be specified for it with the “file” parameter as the module

Annotation

Implementation Notes