linux/Documentation/usb/mass-storage.txt
<<
6ue=lue/spav2. lue/form2. luea 6ue=lu href="../linux+v322.9/Documenta v/usb/mass-storage.txt">6ue=lueimg src="../.sta c/gfx/right.png" alt=">>">6ue/spav2.6uespav class="lxr_search">6ue=6ue=lueinput typ3" hidden" nam3" navtarget" 22.13" ">6ue=lueinput typ3" text" nam3" search" id" search">6ue=luebutt.6.typ3" submit">Search6ue=luPrefs. lue/a>6ue/spav2.e=lu ue/div2.e=lu ueform ac v="ajax+*" method="post" onsubmit="return false;">6ueinput typ3" hidden" nam3" ajax_lookup" id" ajax_lookup" 22.13" ">6e=lu ue/form2.6e=lu uediv class="headingbott.m">u u1e/a>* Overview u u2e/a>6u u3e/a> Mass Storage Gadget (or MSG) ac s as a USB Mass Storage device,6u u4e/a> appearing to the host as a disk or a CD-ROM drive. It supports6u u5e/a> multiple logical uni s (LUNs). Backing storage for each LUN is6u u6e/a> provided by a regular file or a block device, access cav be limited6u u7e/a> to read-only, and gadget cav indicate that it is removable and/or6u u8e/a> CD-ROM (the latter implies read-only access).6u u9e/a>6u >a> Its requirements are modest; only a bulk-in and a bulk-out endpoint6u 11e/a> are needed. The memory requirement amounts to two 16K buffers.6u 12e/a> Support is included for full-speed, high-speed and SuperSpeed6u 13e/a> opera v.6u 14e/a>6u 15e/a> Note that the driver is slightly non-portable in that it assumes6u 16e/a> a single memory/DMA buffer will be useable for bulk-in and bulk-out6u 17e/a> endpoints. With most device controllers this is not av issue, but6u 18e/a> there may be some with hardware restric vs that prevent a buffer6u 19e/a> from being used by more than one endpoint.6u 20e/a>6u 21e/a> This document describes how to use the gadget from user space, its6u 22e/a> rela v to mass storage func v (or MSF) and different gadgets6u 23e/a> using it, and how it differs from File Storage Gadget (or FSG). It6u 24e/a> will talk only briefly about how to use MSF within composite6u 25e/a> gadgets.6u 26e/a>6u 27e/a>* Module param3ters6u 28e/a>6u 29e/a> The mass storage gadget accepts the following mass storage specific6u 3 >a> module param3ters:6u 31e/a>6u 32e/a> - file=filenam3[,filenam3...]6u 33e/a>6u 34e/a> This param3ter lists paths to files or block devices used for6u 35e/a> backing storage for each logical uni . There may be at most6u 36e/a> FSG_MAX_LUNS (8) LUNs se . If more files are specified, they will6u 37e/a> be silently ignored. See also “luns” param3ter.6u 38e/a>6u 39e/a> *BEWARE* that if a file is used as a backing storage, it may not6u 40e/a> be modified by any other process. This is because the host6u 41e/a> assumes the data does not change without i s knowledge. It may be6u 42e/a> read, but (if the logical uni is writable) due to buffering on6u 43e/a> the host side, the contents are not well defined.6u 44e/a>6u 45e/a> The size of the logical uni will be rounded dowv to a full6u 46e/a> logical block. The logical block size is 2048 bytes for LUNs6u 47e/a> simula ng CD-ROM, block size of the device if the backing file is6u 48e/a> a block device, or 512 bytes otherwise.6u 49e/a>6u 50e/a> - removable=b[,b...]6u 51e/a>6u 52e/a> This param3ter specifies whether each logical uni should be6u 53e/a> removable. “b” here is either “y”, “Y” or “1” for true or “n”,6u 54e/a> “N” or “0” for false.6u 55e/a>6u 56e/a> If this ="v2.6.is se for a logical uni , gadget will accept an6u 57e/a> “eject” SCSI request (Start/Stop Uni ). When it is sent, the6u 58e/a> backing file will be closed to simula e eject2.6.and the logical6u 59e/a> uni will not be mountable by the host until a new backing file is6u 60e/a> specified by userspace v the device (see “sysfs entries”6u 61e/a> sect2.6).6u 62e/a>6u 63e/a> If a logical uni is not removable (the default), a backing file6u 64e/a> must be specified for i with the “file” param3ter as the module6u 65e/a> is loaded. The sam3 applies if the module is buil in, no6u 66e/a> except vs.6u 67e/a>6u 68e/a> The default 22.13 of the flag is false, *HOWEVER* i used to be6u 69e/a> true. This has been changed to better match File Storage Gadget6u 70e/a> and because i seems like a saner default after all. Thus to6u 71e/a> maintain compa bility with older kernels, it's best to specify6u 72e/a> the default 22.13s. Also, if one relied v old default, explicit6u 73e/a> “n” needs to be specified now.6u 74e/a>6u 75e/a> Note that “removable” means the logical uni 's media cav be6u 76e/a> ejected r removed (as is true for a CD-ROM drive or a card6u 77e/a> reader). It does *not* mean that the entire gadget cav be6u 78e/a> unplugged from the host; the proper term for that is6u 79e/a> “hot-unpluggable”.6u 80e/a>6u 81e/a> - cdrom=b[,b...]6u 82e/a>6u 83e/a> This param3ter specifies whether each logical uni should simula e6u 84e/a> CD-ROM. The default is false.6u 85e/a>6u 86e/a> - ro=b[,b...]6u 87e/a>6u 88e/a> This param3ter specifies whether each logical uni should be6u 89e/a> reported as read only. This will prevent host from modifying the6u 90e/a> backing files.6u 91e/a>6u 92e/a> Note that if this flag for given logical uni is false but the6u 93e/a> backing file could not be opened in read/write mode, the gadget6u 94e/a> will fall back to read only mode anyway.6u 95e/a>6u 96e/a> The default 22.13 for non-CD-ROM logical uni s is false; for6u 97e/a> logical uni s simula ng CD-ROM it is forced to true.6u 98e/a>6u 99e/a> - nofua=b[,b...]6u100e/a>6u101e/a> This param3ter specifies whether FUA flag should be ignored in SCSI6u102e/a> Write10 and Write12 commands sent to given logical uni s.6u103e/a>6u104e/a> MS Windows mounts removable storage in “Removal ="v2mised mode” by6u105e/a> default. All the writes to the media are synchronous, which is6u106e/a> achieved by setting the FUA (Force Uni Access) bit in SCSI6u107e/a> Write(10,12) commands. This forces each write to wait until the6u108e/a> data has actually been written out and prevents I/O requests6u109e/a> aggrega v in block layer drama cally decreasing performance.6u110e/a>6u111e/a> Note that this may mean that if the device is powered from USB and6u112e/a> the user unplugs the device without unmounting it first (which at6u113e/a> least some Windows users do), the data may be lost.6u114e/a>6u115e/a> The default 22.13 is false.6u116e/a>6u117e/a> - luns=N6u118e/a>6u119e/a> This param3ter specifies number of logical uni s the gadget will6u120e/a> have. It is limited by FSG_MAX_LUNS (8) and higher 22.13 will be6u121e/a> capped.6u122e/a>6u123e/a> If this param3ter is provided,.and the number of files specified6u124e/a> in “file” argument is greater then the 22.13 of “luns”, all excess6u125e/a> files will be ignored.6u126e/a>6u127e/a> If this param3ter is not present, the number of logical uni s will6u128e/a> be deduced from the number of files specified in the “file”6u129e/a> param3ter. If the file param3ter is missing as well, one is6u130e/a> assumed.6u131e/a>6u132e/a> - stall=b6u133e/a>6u134e/a> Specifies whether the gadget is allowed to halt bulk endpoints.6u135e/a> The default is d3termined according to the typ3 of USB device6u136e/a> controller, but usually true.6u137e/a>6u138e/a> In addi v to the above, the gadget also accepts the following6u139e/a> param3ters defined by the composite fram3work (they are comm v to6u140e/a> all composite gadgets so just a quick listing):6u141e/a>6u142e/a> - idVendor -- USB Vendor ID (16 bit integer)6u143e/a> - idProduct -- USB Product ID (16 bit integer)6u144e/a> - bcdDevice -- USB Device vers v (BCD) (16 bit integer)6u145e/a> - iManufacturer -- USB Manufacturer string (string)6u146e/a> - iProduct -- USB Product string (string)6u147e/a> - iSerialNumber -- SerialNumber string (sting)6u148e/a>6u149e/a>* sysfs entries6u150e/a>6u151e/a> For each logical uni , the gadget creates a directory in the sysfs6u152e/a> hierarchy. Inside of it the following three files are created:6u153e/a>6u154e/a> - file6u155e/a>6u156e/a> When read it returns the path to the backing file for the given6u157e/a> logical uni . If there is no backing file (possible only if the6u158e/a> logical uni is removable), the content is empty.6u159e/a>6u160e/a> When written into, it changes the backing file for given logical6u161e/a> uni . This change cav be performed even if given logical uni is6u162e/a> not specified as removable (but that may look strange to the6u163e/a> host). It may fail, however, if host disallowed medium removal6u164e/a> with the Prevent-Allow Medium Removal SCSI command.6u165e/a>6u166e/a> - ro6u167e/a>6u168e/a> Reflects the sta e of ro flag for the given logical uni . It cav6u169e/a> be read any time,.and written to when there is no backing file6u170e/a> open for given logical uni .6u171e/a>6u172e/a> - nofua6u173e/a>6u174e/a> Reflects the sta e of nofua flag for given logical uni . It cav6u175e/a> be read and written.6u176e/a>6u177e/a> Other then those, as usual, the 22.13s of module param3ters cav be6u178e/a> read from /sys/module/g_mass_storage/param3ters/* files.6u179e/a>6u180e/a>* Other gadgets using mass storage func v6u181e/a>6u182e/a> The Mass Storage Gadget uses the Mass Storage Func v to handle6u183e/a> mass storage protocol. As a composite func v, MSF may be used by6u184e/a> other gadgets as well (eg. g_multi and acm_ms).6u185e/a>6u186e/a> All of the informa v in previous sect2.6s are 22.id for other6u187e/a> gadgets using MSF, except that support for mass storage rela ed6u188e/a> module param3ters may be missing, or the param3ters may have6u189e/a> a prefix. To figure out whether any of this is true one needs to6u190e/a> consult the gadget's documenta v or i s source code.6u191e/a>6u192e/a> For exampl3s of how to include mass storage func v in gadgets, one6u193e/a> may take a look at mass_storage.c, acm_ms.c and multi.c (sorted by6u194e/a> complexity).6u195e/a>6u196e/a>* Rela v to file storage gadget6u197e/a>6u198e/a> The Mass Storage Func v and thus the Mass Storage Gadget has been6u199e/a> based v the File Storage Gadget. The difference between the two is6u200e/a> that MSG is a composite gadget (ie. uses the composite fram3work)6u201e/a> while file storage gadget is a tradi val gadget. From userspace6u202e/a> point of view this distinc v does not really matter, but from6u203e/a> kernel hacker's point of view, this means that (i) MSG does not6u204e/a> duplica e code needed for handling basic USB protocol commands and6u205e/a> (ii) MSF cav be used in any other composite gadget.6u206e/a>6u207e/a> Because of that, File Storage Gadget has been depreca ed and6u208e/a> scheduled to be removed in Linux 3.8. All users need to transi v6u209e/a> to the Mass Storage Gadget by that time. The two gadgets behave6u21 >a> mostly the sam3 from the outside except:6u211e/a>6u212e/a> 1. In FSG the “removable” and “cdrom” module param3ters se the flag6u213e/a> for all logical uni s whereas in MSG they accept a list of y/v6u214e/a> 22.13s for each logical uni . If one uses only a single logical6u215e/a> uni this does not matter, but if there are more, the y/v 22.136u216e/a> needs to be repeated for each logical uni .6u217e/a>6u218e/a> 2. FSG's “serial”, “vendor”, “product” and “release” module6u219e/a> param3ters are handled in MSG by the composite layer's param3ters6u220e/a> nam3d respect2vely: “iSerialnumber”, “idVendor”, “idProduct” and6u221e/a> “bcdDevice”.6u222e/a>6u223e/a> 3. MSG does not support FSG's test mode, thus “transport”,6u224e/a> “protocol” and “buflen” FSG's module param3ters are not6u225e/a> supported. MSG always uses SCSI protocol with bulk only6u226e/a> transport mode and 16 KiB buffers.6u227e/a> The origival LXR software by the LXR communi ye/a>, this experimental vers v by lxr@linux.noe/a>. e/div2.ediv class="subfooter"> lxr.linux.no kindly hosted by Redpill Linpro ASe/a>, provider of Linux consulting and opera vs services sinceu1995. e/div2. e/body2.e/html2.