Mass Storage Gadget (MSG)

개요

Mass Storage Gadget(MSG)은 host에 disk 또는 CD-ROM drive로 보이는 USB Mass Storage device이며 여러 logical unit(LUN)을 지원합니다.

각 LUN의 backing storage는 regular file 또는 block device입니다. 접근을 read-only로 제한하고 removable 또는 CD-ROM으로 표시할 수 있으며 CD-ROM 표시는 read-only를 뜻합니다.

필요한 endpoint는 bulk-in과 bulk-out 하나씩이고 memory는 16KiB buffer 두 개입니다. full-speed, high-speed, SuperSpeed를 지원합니다.

드라이버는 하나의 memory/DMA buffer를 bulk-in과 bulk-out 양쪽 endpoint에서 사용할 수 있다고 가정합니다. 대부분의 controller에서는 문제없지만 한 buffer를 여러 endpoint에서 쓰지 못하는 hardware에서는 이식성 문제가 생길 수 있습니다.

문서는 사용자 공간에서 gadget을 사용하는 방법, Mass Storage Function(MSF)과 이를 쓰는 다른 gadget의 관계, Linux에서 제거된 File Storage Gadget(FSG)과의 차이를 설명합니다.

composite gadget 안에서 MSF를 사용하는 방법은 간단히만 다룹니다.

=========================
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 parameter

`file=filename[,filename...]`은 각 LUN의 backing file 또는 block device 경로 목록입니다. 최대 `FSG_MAX_LUNS`인 8개이며 초과 항목은 경고 없이 무시됩니다.

regular file을 backing storage로 쓰면 다른 process가 수정해서는 안 됩니다. host는 알지 못하는 변경이 없다고 가정하기 때문입니다. 읽기는 가능하지만 writable LUN은 host buffering 때문에 다른 process가 보는 내용이 명확하지 않을 수 있습니다.

LUN 크기는 완전한 logical block 단위로 내림됩니다. CD-ROM은 2048바이트, block device는 그 장치의 block size, 그 밖의 file은 512바이트입니다.

`removable=b[,b...]`은 LUN별 removable 여부이며 yes/no를 나타내는 y/Y/1과 n/N/0 형식 값을 사용합니다.

removable LUN은 SCSI Start/Stop Unit의 eject 요청을 받습니다. eject하면 backing file을 닫고 device 사용자 공간이 sysfs로 새 backing file을 지정할 때까지 host에서 mount할 수 없습니다.

non-removable이 기본값이며 module load 때 `file`로 backing file을 반드시 지정해야 합니다. built-in인 경우도 예외가 없습니다. 과거 기본값은 true였으므로 이전 kernel과의 호환성을 위해 기본값을 명시하고, 옛 동작에 의존했다면 이제 명시적으로 false 값을 써야 합니다.

removable은 LUN media를 꺼낼 수 있다는 뜻이지 gadget 전체를 host에서 분리할 수 있다는 뜻이 아닙니다. gadget 전체에는 hot-unpluggable이라는 용어를 사용합니다.

`cdrom=b[,b...]`은 LUN별 CD-ROM simulation 여부이고 기본값은 false입니다.

`ro=b[,b...]`은 LUN을 read-only로 보고해 host의 backing file 수정을 막습니다. false여도 file을 R/W로 열 수 없으면 read-only로 fallback합니다. non-CD-ROM 기본값은 false이고 CD-ROM은 true로 강제됩니다.

`nofua=b[,b...]`은 해당 LUN의 SCSI Write10/Write12에서 FUA(Force Unit Access) flag를 무시할지 정합니다. Windows의 removal-optimized mode는 FUA로 모든 write를 동기화해 aggregation을 막고 성능을 크게 낮출 수 있습니다.

FUA를 무시하면 성능은 좋아질 수 있지만 USB 전원 장치를 unmount하지 않고 분리할 때 data loss가 생길 수 있습니다. `nofua` 기본값은 false입니다.

`luns=N`은 LUN 수이며 최대 8로 제한됩니다. `file` 수가 더 많으면 초과 file은 무시됩니다. `luns`가 없으면 `file` 개수에서 추론하고 `file`도 없으면 LUN 1개를 가정합니다.

`stall=b`은 bulk endpoint halt 허용 여부입니다. 기본값은 USB device controller 종류에 따라 정해지지만 보통 true입니다.

composite framework 공통 parameter로 16-bit `idVendor`, `idProduct`, BCD `bcdDevice`, `iManufacturer`, `iProduct`, `iSerialNumber`도 받습니다.

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
    is loaded.  The same applies if the module is built in, no
    exceptions.

    The default value of the flag is false, *HOWEVER* it used to be
    true.  This has been changed to better match File Storage Gadget
    and because it seems like a saner default after all.  Thus to
    maintain compatibility with older kernels, it's best to specify
    the default values.  Also, if one relied on old default, explicit
    “n” needs to be specified now.

    Note that “removable” means the logical unit's media can be
    ejected or removed (as is true for a CD-ROM drive or a card
    reader).  It does *not* mean that the entire gadget can be
    unplugged from the host; the proper term for that is
    “hot-unpluggable”.

  - cdrom=b[,b...]

    This parameter specifies whether each logical unit should simulate
    CD-ROM.  The default is false.

  - ro=b[,b...]

    This parameter specifies whether each logical unit should be
    reported as read only.  This will prevent host from modifying the
    backing files.

    Note that if this flag for given logical unit is false but the
    backing file could not be opened in read/write mode, the gadget
    will fall back to read only mode anyway.

    The default value for non-CD-ROM logical units is false; for
    logical units simulating CD-ROM it is forced to true.

  - nofua=b[,b...]

    This parameter specifies whether FUA flag should be ignored in SCSI
    Write10 and Write12 commands sent to given logical units.

    MS Windows mounts removable storage in “Removal optimised mode” by
    default.  All the writes to the media are synchronous, which is
    achieved by setting the FUA (Force Unit Access) bit in SCSI
    Write(10,12) commands.  This forces each write to wait until the
    data has actually been written out and prevents I/O requests
    aggregation in block layer dramatically decreasing performance.

    Note that this may mean that if the device is powered from USB and
    the user unplugs the device without unmounting it first (which at
    least some Windows users do), the data may be lost.

    The default value is false.

  - luns=N

    This parameter specifies number of logical units the gadget will
    have.  It is limited by FSG_MAX_LUNS (8) and higher value will be
    capped.

    If this parameter is provided, and the number of files specified
    in “file” argument is greater then the value of “luns”, all excess
    files will be ignored.

    If this parameter is not present, the number of logical units will
    be deduced from the number of files specified in the “file”
    parameter.  If the file parameter is missing as well, one is
    assumed.

  - stall=b

    Specifies whether the gadget is allowed to halt bulk endpoints.
    The default is determined according to the type of USB device
    controller, but usually true.

  In addition to the above, the gadget also accepts the following
  parameters defined by the composite framework (they are common to
  all composite gadgets so just a quick listing):

  - idVendor      -- USB Vendor ID (16 bit integer)
  - idProduct     -- USB Product ID (16 bit integer)
  - bcdDevice     -- USB Device version (BCD) (16 bit integer)
  - iManufacturer -- USB Manufacturer string (string)
  - iProduct      -- USB Product string (string)
  - iSerialNumber -- SerialNumber string (string)

sysfs entry

gadget은 각 LUN마다 sysfs 디렉터리를 만들고 backing file과 access flag를 제어하는 파일을 노출합니다.

`file`을 읽으면 backing file 경로를 반환하며 removable LUN에 file이 없으면 비어 있습니다. 쓰면 backing file을 바꾸며 non-removable LUN에서도 가능하지만 host에는 이상하게 보일 수 있습니다. host가 Prevent-Allow Medium Removal SCSI command로 제거를 금지했다면 실패할 수 있습니다.

`ro`는 LUN의 read-only flag 상태입니다. 언제든 읽을 수 있고 backing file이 열려 있지 않을 때 쓸 수 있습니다.

`nofua`는 해당 flag 상태를 반영하며 읽고 쓸 수 있습니다.

`forced_eject`에 0이 아닌 byte를 쓰면 host 허가와 관계없이 backing file을 LUN에서 강제로 분리합니다. 읽을 수 없습니다. module parameter 값은 `/sys/module/g_mass_storage/parameters/*`에서도 읽을 수 있습니다.

sysfs entries
=============

  For each logical unit, the gadget creates a directory in the sysfs
  hierarchy.  Inside of it the following three files are created:

  - file

    When read it returns the path to the backing file for the given
    logical unit.  If there is no backing file (possible only if the
    logical unit is removable), the content is empty.

    When written into, it changes the backing file for given logical
    unit.  This change can be performed even if given logical unit is
    not specified as removable (but that may look strange to the
    host).  It may fail, however, if host disallowed medium removal
    with the Prevent-Allow Medium Removal SCSI command.

  - ro

    Reflects the state of ro flag for the given logical unit.  It can
    be read any time, and written to when there is no backing file
    open for given logical unit.

  - nofua

    Reflects the state of nofua flag for given logical unit.  It can
    be read and written.

  - forced_eject

    When written into, it causes the backing file to be forcibly
    detached from the LUN, regardless of whether the host has allowed
    it.  The content doesn't matter, any non-zero number of bytes
    written will result in ejection.

    Can not be read.

  Other then those, as usual, the values of module parameters can be
  read from /sys/module/g_mass_storage/parameters/* files.

MSF를 사용하는 다른 gadget

MSG는 mass storage protocol 처리를 위해 Mass Storage Function(MSF)을 사용합니다.

MSF는 composite function이므로 `g_multi`, `acm_ms` 같은 다른 gadget에서도 사용할 수 있습니다.

앞 절의 정보는 다른 MSF gadget에도 적용되지만 mass-storage 관련 module parameter가 없거나 prefix가 붙을 수 있습니다. gadget 문서나 source code를 확인해야 합니다.

MSF 포함 예제는 복잡도 순으로 `mass_storage.c`, `acm_ms.c`, `multi.c`를 참고할 수 있습니다.

Other gadgets using mass storage function
=========================================

  The Mass Storage Gadget uses the Mass Storage Function to handle
  mass storage protocol.  As a composite function, MSF may be used by
  other gadgets as well (eg. g_multi and acm_ms).

  All of the information in previous sections are valid for other
  gadgets using MSF, except that support for mass storage related
  module parameters may be missing, or the parameters may have
  a prefix.  To figure out whether any of this is true one needs to
  consult the gadget's documentation or its source code.

  For examples of how to include mass storage function in gadgets, one
  may take a look at mass_storage.c, acm_ms.c and multi.c (sorted by
  complexity).

File Storage Gadget과의 관계

MSF와 MSG는 File Storage Gadget(FSG)을 기반으로 합니다. MSG는 composite framework를 쓰는 composite gadget이고 FSG는 전통적인 gadget이었습니다.

사용자 공간 관점의 차이는 작지만 kernel 관점에서는 MSG가 기본 USB protocol command 처리 코드를 중복하지 않고 MSF를 다른 composite gadget에서도 재사용할 수 있다는 의미입니다.

FSG는 Linux 3.8에서 제거되었고 사용자는 MSG로 전환해야 합니다.

FSG의 `removable`과 `cdrom`은 모든 LUN에 한 값을 적용했지만 MSG는 LUN별 y/n 목록을 받습니다. LUN이 여러 개면 각 LUN 값만큼 반복해야 합니다.

FSG의 `serial`, `vendor`, `product`, `release`는 MSG에서 composite layer의 `iSerialNumber`, `idVendor`, `idProduct`, `bcdDevice`로 각각 대응됩니다.

MSG는 FSG test mode와 `transport`, `protocol`, `buflen` parameter를 지원하지 않습니다. 항상 SCSI protocol, bulk-only transport, 16KiB buffer를 사용합니다.

Relation to file storage gadget
===============================

  The Mass Storage Function and thus the Mass Storage Gadget has been
  based on the File Storage Gadget.  The difference between the two is
  that MSG is a composite gadget (ie. uses the composite framework)
  while file storage gadget was a traditional gadget.  From userspace
  point of view this distinction does not really matter, but from
  kernel hacker's point of view, this means that (i) MSG does not
  duplicate code needed for handling basic USB protocol commands and
  (ii) MSF can be used in any other composite gadget.

  Because of that, File Storage Gadget has been removed in Linux 3.8.
  All users need to transition to the Mass Storage Gadget.  The two
  gadgets behave mostly the same from the outside except:

  1. In FSG the “removable” and “cdrom” module parameters set the flag
     for all logical units whereas in MSG they accept a list of y/n
     values for each logical unit.  If one uses only a single logical
     unit this does not matter, but if there are more, the y/n value
     needs to be repeated for each logical unit.

  2. FSG's “serial”, “vendor”, “product” and “release” module
     parameters are handled in MSG by the composite layer's parameters
     named respectively: “iSerialnumber”, “idVendor”, “idProduct” and
     “bcdDevice”.

  3. MSG does not support FSG's test mode, thus “transport”,
     “protocol” and “buflen” FSG's module parameters are not
     supported.  MSG always uses SCSI protocol with bulk only
     transport mode and 16 KiB buffers.