lkml.org 
[lkml]   [2012]   [Jun]   [11]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [PATCH 3/3] usb: gadget: mass storage: add documentation
    On Mon, 11 Jun 2012, Michal Nazarewicz wrote:

    > This commit adds Documentation/usb/mass-storage.txt file. It contains
    > description of how to use the mass storage gadget from user space. It
    > elaborates on madule parameters and sysfs interface more then it was
    > written in the comments in the source code.
    >
    > Signed-off-by: Michal Nazarewicz <mina86@mina86.com>
    > ---
    > Documentation/usb/mass-storage.txt | 219 +++++++++++++++++++++++++++++++++++
    > drivers/usb/gadget/f_mass_storage.c | 69 +----------
    > 2 files changed, 226 insertions(+), 62 deletions(-)
    > create mode 100644 Documentation/usb/mass-storage.txt
    >
    > diff --git a/Documentation/usb/mass-storage.txt b/Documentation/usb/mass-storage.txt
    > new file mode 100644
    > index 0000000..1c2fff9
    > --- /dev/null
    > +++ b/Documentation/usb/mass-storage.txt
    > @@ -0,0 +1,219 @@
    > + -*- org -*-

    What is the purpose of this line?

    > +
    > +* 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).

    Does CD-ROM really imply read-only? If not, shouldn't it?

    > +
    > + 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 super-speed

    s/super-speed/SuperSpeed/

    > + operation.
    > +
    > + Note that the driver is slightly non-portable in that it assumes
    > + a single memory/DMA buffer will be useable 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, as well as and how does it differ from File Storage Gadget

    s/as well as and how does it differ/and how it differs/

    > + (or FSG). 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 host assumes

    s/host/the host/

    > + the data does not change without its knowledge. It may by read,

    s/by/be/

    > + 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 full logical

    s/full/a full/

    > + block. A logical block size is 2048 for LUNs simulating CD-ROM,

    s/A/The/
    s/2048/2048 bytes/

    > + block size of a device if the device is the backing file, or 512

    s/a device if the device is the backing file/the device if the backing
    file is a block device/

    > + 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.

    Add something like this: 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".

    > +
    > + 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 released to simulate ejection and the logical

    s/released/closed/

    > + 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 logical unit is not removable (the default), backing file must

    s/logical/a logical/
    s/backing file/a backing file/

    > + be specified for it with the “file” as the module is loaded. The

    s/"file"/"file" parameter/

    > + 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.
    > +
    > + - 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 each logical unit is false.

    Shouldn't the default be true for logical units that are cdroms?

    > +
    > + - 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

    s/synchronous/synchronous,/

    > + achieved by setting FUA (Force Unit Access) bit in SCSI

    s/FUA/the FUA/

    > + Write(10,12) commands. This prevents I/O requests aggregation in
    > + block layer dramatically decreasing performance.

    Actually it forces writes to be done with the O_SYNC flag set. Not
    only does this prevent request aggregation, it also forces each write
    operation to wait until the data has actually been written out --
    dramatically decreasing performance.

    > +
    > + Note that this may mean that if the device is powered from USB and
    > + user unplugs the device without unmounting (which at lest some

    s/user/the user/
    s/unmounting/unmounting it first/
    s/lest/least/

    > + 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 deducted from the number of files specified in the “file”

    s/deducted/deduced/

    > + 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 (sting)
    > +
    > +* 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 given

    s/for given/for the given/

    > + logical unit. If there is no backing file (possible only if
    > + logical unit is removable), the content is empty.

    s/logical/the logical/

    > +
    > + 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 Allow Medium Removal SCSI command.

    s/Allow/the Prevent-Allow/

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

    s/for given/for the given/

    > +
    > + - nofua
    > +
    > + Reflects the state of nofua flag for given logical unit. It can

    s/for given/for the given/

    > + be read and written to change it.

    s/to change it//

    > +
    > + Other then those, as usual, the values of modules parameters can be

    s/modules/module/

    > + read from /sys/module/g_mass_storage/parameters/* files.
    > +
    > +* 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 gadget's documentation or its source code.

    s/gadget's/the gadget's/

    > +
    > + 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).
    > +
    > +* 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 is 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 deprecated and
    > + scheduled to be removed in Linux 3.8. All users need to transition
    > + to the Mass Storage Gadget by that time. 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.

    Very good. When you make the small changes listed above, you can add

    Acked-by: Alan Stern <stern@rowland.harvard.edu>

    --
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

    \
     
     \ /
      Last update: 2012-06-11 18:03    [W:0.047 / U:2.100 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site