summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2012-07-26 21:23:47 +0400
committerLinus Torvalds <torvalds@linux-foundation.org>2012-07-26 21:23:47 +0400
commit9fc377799bc9bfd8d5cb35d0d1ea2e2458cbdbb3 (patch)
treefe93603b4e33dd50ff5f95ff769a0748b230cdf9 /Documentation
parent5e23ae49960d05f578a73ecd19749c45af682c2b (diff)
parente387ef5c47ddeaeaa3cbdc54424cdb7a28dae2c0 (diff)
downloadlinux-9fc377799bc9bfd8d5cb35d0d1ea2e2458cbdbb3.tar.xz
Merge tag 'usb-3.6-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/usb
Pull USB patches from Greg Kroah-Hartman: "Here's the big USB patch set for the 3.6-rc1 merge window. Lots of little changes in here, primarily for gadget controllers and drivers. There's some scsi changes that I think also went in through the scsi tree, but they merge just fine. All of these patches have been in the linux-next tree for a while now. Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>" Fix up trivial conflicts in include/scsi/scsi_device.h (same libata conflict that Jeff had already encountered) * tag 'usb-3.6-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/usb: (207 commits) usb: Add USB_QUIRK_RESET_RESUME for all Logitech UVC webcams usb: Add quirk detection based on interface information usb: s3c-hsotg: Add header file protection macros in s3c-hsotg.h USB: ehci-s5p: Add vbus setup function to the s5p ehci glue layer USB: add USB_VENDOR_AND_INTERFACE_INFO() macro USB: notify phy when root hub port connect change USB: remove 8 bytes of padding from usb_host_interface on 64 bit builds USB: option: add ZTE MF821D USB: sierra: QMI mode MC7710 moved to qcserial USB: qcserial: adding Sierra Wireless devices USB: qcserial: support generic Qualcomm serial ports USB: qcserial: make probe more flexible USB: qcserial: centralize probe exit path USB: qcserial: consolidate usb_set_interface calls USB: ehci-s5p: Add support for device tree USB: ohci-exynos: Add support for device tree USB: ehci-omap: fix compile failure(v1) usb: host: tegra: pass correct pointer in ehci_setup() USB: ehci-fsl: Update ifdef check to work on 64-bit ppc USB: serial: keyspan: Removed unrequired parentheses. ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/testing/sysfs-bus-usb12
-rw-r--r--Documentation/devicetree/bindings/usb/ci13xxx-imx.txt18
-rw-r--r--Documentation/devicetree/bindings/usb/mxs-phy.txt13
-rw-r--r--Documentation/usb/mass-storage.txt226
4 files changed, 269 insertions, 0 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb
index 6df4e6f57560..5f75f8f7df34 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb
+++ b/Documentation/ABI/testing/sysfs-bus-usb
@@ -208,3 +208,15 @@ Description:
such as ACPI. This file will read either "removable" or
"fixed" if the information is available, and "unknown"
otherwise.
+
+What: /sys/bus/usb/devices/.../ltm_capable
+Date: July 2012
+Contact: Sarah Sharp <sarah.a.sharp@linux.intel.com>
+Description:
+ USB 3.0 devices may optionally support Latency Tolerance
+ Messaging (LTM). They indicate their support by setting a bit
+ in the bmAttributes field of their SuperSpeed BOS descriptors.
+ If that bit is set for the device, ltm_capable will read "yes".
+ If the device doesn't support LTM, the file will read "no".
+ The file will be present for all speeds of USB devices, and will
+ always read "no" for USB 1.1 and USB 2.0 devices.
diff --git a/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt b/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt
new file mode 100644
index 000000000000..2c290418bb2d
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt
@@ -0,0 +1,18 @@
+* Freescale i.MX ci13xxx usb controllers
+
+Required properties:
+- compatible: Should be "fsl,imx27-usb"
+- reg: Should contain registers location and length
+- interrupts: Should contain controller interrupt
+
+Optional properties:
+- fsl,usbphy: phandler of usb phy that connects to the only one port
+- vbus-supply: regulator for vbus
+
+Examples:
+usb@02184000 { /* USB OTG */
+ compatible = "fsl,imx6q-usb", "fsl,imx27-usb";
+ reg = <0x02184000 0x200>;
+ interrupts = <0 43 0x04>;
+ fsl,usbphy = <&usbphy1>;
+};
diff --git a/Documentation/devicetree/bindings/usb/mxs-phy.txt b/Documentation/devicetree/bindings/usb/mxs-phy.txt
new file mode 100644
index 000000000000..5835b27146ea
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/mxs-phy.txt
@@ -0,0 +1,13 @@
+* Freescale MXS USB Phy Device
+
+Required properties:
+- compatible: Should be "fsl,imx23-usbphy"
+- reg: Should contain registers location and length
+- interrupts: Should contain phy interrupt
+
+Example:
+usbphy1: usbphy@020c9000 {
+ compatible = "fsl,imx6q-usbphy", "fsl,imx23-usbphy";
+ reg = <0x020c9000 0x1000>;
+ interrupts = <0 44 0x04>;
+};
diff --git a/Documentation/usb/mass-storage.txt b/Documentation/usb/mass-storage.txt
new file mode 100644
index 000000000000..e9b9334627bf
--- /dev/null
+++ b/Documentation/usb/mass-storage.txt
@@ -0,0 +1,226 @@
+* 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 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, and how it differs from File Storage Gadget (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 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 (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 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.
+
+ Other then those, as usual, the values of module parameters can be
+ 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 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).
+
+* 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.