diff options
Diffstat (limited to 'Documentation/usb')
| -rw-r--r-- | Documentation/usb/URB.txt | 43 | ||||
| -rw-r--r-- | Documentation/usb/WUSB-Design-overview.txt | 2 | ||||
| -rw-r--r-- | Documentation/usb/chipidea.txt | 71 | ||||
| -rw-r--r-- | Documentation/usb/dwc3.txt | 2 | ||||
| -rw-r--r-- | Documentation/usb/error-codes.txt | 7 | ||||
| -rw-r--r-- | Documentation/usb/functionfs.txt | 67 | ||||
| -rw-r--r-- | Documentation/usb/gadget_configfs.txt | 384 | ||||
| -rw-r--r-- | Documentation/usb/gadget_multi.txt | 2 | ||||
| -rw-r--r-- | Documentation/usb/hotplug.txt | 6 | ||||
| -rw-r--r-- | Documentation/usb/mass-storage.txt | 225 | ||||
| -rw-r--r-- | Documentation/usb/mtouchusb.txt | 2 | ||||
| -rw-r--r-- | Documentation/usb/persist.txt | 3 | ||||
| -rw-r--r-- | Documentation/usb/power-management.txt | 15 | ||||
| -rw-r--r-- | Documentation/usb/proc_usb_info.txt | 11 | ||||
| -rw-r--r-- | Documentation/usb/usbmon.txt | 6 | ||||
| -rw-r--r-- | Documentation/usb/wusb-cbaf | 2 |
16 files changed, 813 insertions, 35 deletions
diff --git a/Documentation/usb/URB.txt b/Documentation/usb/URB.txt index 8ffce746d49..50da0d45544 100644 --- a/Documentation/usb/URB.txt +++ b/Documentation/usb/URB.txt @@ -168,18 +168,39 @@ that if the completion handler or anyone else tries to resubmit it they will get a -EPERM error. Thus you can be sure that when usb_kill_urb() returns, the URB is totally idle. +There is a lifetime issue to consider. An URB may complete at any +time, and the completion handler may free the URB. If this happens +while usb_unlink_urb or usb_kill_urb is running, it will cause a +memory-access violation. The driver is responsible for avoiding this, +which often means some sort of lock will be needed to prevent the URB +from being deallocated while it is still in use. + +On the other hand, since usb_unlink_urb may end up calling the +completion handler, the handler must not take any lock that is held +when usb_unlink_urb is invoked. The general solution to this problem +is to increment the URB's reference count while holding the lock, then +drop the lock and call usb_unlink_urb or usb_kill_urb, and then +decrement the URB's reference count. You increment the reference +count by calling + + struct urb *usb_get_urb(struct urb *urb) + +(ignore the return value; it is the same as the argument) and +decrement the reference count by calling usb_free_urb. Of course, +none of this is necessary if there's no danger of the URB being freed +by the completion handler. + 1.7. What about the completion handler? The handler is of the following type: - typedef void (*usb_complete_t)(struct urb *, struct pt_regs *) + typedef void (*usb_complete_t)(struct urb *) -I.e., it gets the URB that caused the completion call, plus the -register values at the time of the corresponding interrupt (if any). -In the completion handler, you should have a look at urb->status to -detect any USB errors. Since the context parameter is included in the URB, -you can pass information to the completion handler. +I.e., it gets the URB that caused the completion call. In the completion +handler, you should have a look at urb->status to detect any USB errors. +Since the context parameter is included in the URB, you can pass +information to the completion handler. Note that even when an error (or unlink) is reported, data may have been transferred. That's because USB transfers are packetized; it might take @@ -188,12 +209,12 @@ have transferred successfully before the completion was called. NOTE: ***** WARNING ***** -NEVER SLEEP IN A COMPLETION HANDLER. These are normally called -during hardware interrupt processing. If you can, defer substantial -work to a tasklet (bottom half) to keep system latencies low. You'll -probably need to use spinlocks to protect data structures you manipulate -in completion handlers. +NEVER SLEEP IN A COMPLETION HANDLER. These are often called in atomic +context. +In the current kernel, completion handlers run with local interrupts +disabled, but in the future this will be changed, so don't assume that +local IRQs are always disabled inside completion handlers. 1.8. How to do isochronous (ISO) transfers? diff --git a/Documentation/usb/WUSB-Design-overview.txt b/Documentation/usb/WUSB-Design-overview.txt index 4c5e3793934..1cd07c017cf 100644 --- a/Documentation/usb/WUSB-Design-overview.txt +++ b/Documentation/usb/WUSB-Design-overview.txt @@ -25,7 +25,7 @@ updated content. * Design-overview.txt-1.8 This code implements a Ultra Wide Band stack for Linux, as well as -drivers for the the USB based UWB radio controllers defined in the +drivers for the USB based UWB radio controllers defined in the Wireless USB 1.0 specification (including Wireless USB host controller and an Intel WiNET controller). diff --git a/Documentation/usb/chipidea.txt b/Documentation/usb/chipidea.txt new file mode 100644 index 00000000000..995c8bca40e --- /dev/null +++ b/Documentation/usb/chipidea.txt @@ -0,0 +1,71 @@ +1. How to test OTG FSM(HNP and SRP) +----------------------------------- +To show how to demo OTG HNP and SRP functions via sys input files +with 2 Freescale i.MX6Q sabre SD boards. + +1.1 How to enable OTG FSM in menuconfig +--------------------------------------- +Select CONFIG_USB_OTG_FSM, rebuild kernel Image and modules. +If you want to check some internal variables for otg fsm, +select CONFIG_USB_CHIPIDEA_DEBUG, there are 2 files which +can show otg fsm variables and some controller registers value: +cat /sys/kernel/debug/ci_hdrc.0/otg +cat /sys/kernel/debug/ci_hdrc.0/registers + +1.2 Test operations +------------------- +1) Power up 2 Freescale i.MX6Q sabre SD boards with gadget class driver loaded + (e.g. g_mass_storage). + +2) Connect 2 boards with usb cable with one end is micro A plug, the other end + is micro B plug. + + The A-device(with micro A plug inserted) should enumrate B-device. + +3) Role switch + On B-device: + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + if HNP polling is not supported, also need: + On A-device: + echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req + + B-device should take host role and enumrate A-device. + +4) A-device switch back to host. + On B-device: + echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + A-device should switch back to host and enumrate B-device. + +5) Remove B-device(unplug micro B plug) and insert again in 10 seconds, + A-device should enumrate B-device again. + +6) Remove B-device(unplug micro B plug) and insert again after 10 seconds, + A-device should NOT enumrate B-device. + + if A-device wants to use bus: + On A-device: + echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req + + if B-device wants to use bus: + On B-device: + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + +7) A-device power down the bus. + On A-device: + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop + + A-device should disconnect with B-device and power down the bus. + +8) B-device does data pulse for SRP. + On B-device: + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + A-device should resume usb bus and enumrate B-device. + +1.3 Reference document +---------------------- +"On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification +July 27, 2012 Revision 2.0 version 1.1a" diff --git a/Documentation/usb/dwc3.txt b/Documentation/usb/dwc3.txt index 7b590edae14..1d02c01d1c7 100644 --- a/Documentation/usb/dwc3.txt +++ b/Documentation/usb/dwc3.txt @@ -28,7 +28,7 @@ Please pick something while reading :) none - primary handler of the EP-interrupt - reads the event and tries to process it. Everything that requries + reads the event and tries to process it. Everything that requires sleeping is handed over to the Thread. The event is saved in an per-endpoint data-structure. We probably have to pay attention not to process events once we diff --git a/Documentation/usb/error-codes.txt b/Documentation/usb/error-codes.txt index b3f606b81a0..9c3eb845ebe 100644 --- a/Documentation/usb/error-codes.txt +++ b/Documentation/usb/error-codes.txt @@ -21,6 +21,8 @@ Non-USB-specific: USB-specific: +-EBUSY The URB is already active. + -ENODEV specified USB-device or bus doesn't exist -ENOENT specified interface or endpoint does not exist or @@ -35,9 +37,8 @@ USB-specific: d) ISO: number_of_packets is < 0 e) various other cases --EAGAIN a) specified ISO start frame too early - b) (using ISO-ASAP) too much scheduled for the future - wait some time and try again. +-EXDEV ISO: URB_ISO_ASAP wasn't specified and all the frames + the URB would be scheduled in have already expired. -EFBIG Host controller driver can't schedule that many ISO frames. diff --git a/Documentation/usb/functionfs.txt b/Documentation/usb/functionfs.txt new file mode 100644 index 00000000000..eaaaea019fc --- /dev/null +++ b/Documentation/usb/functionfs.txt @@ -0,0 +1,67 @@ +*How FunctionFS works* + +From kernel point of view it is just a composite function with some +unique behaviour. It may be added to an USB configuration only after +the user space driver has registered by writing descriptors and +strings (the user space program has to provide the same information +that kernel level composite functions provide when they are added to +the configuration). + +This in particular means that the composite initialisation functions +may not be in init section (ie. may not use the __init tag). + +From user space point of view it is a file system which when +mounted provides an "ep0" file. User space driver need to +write descriptors and strings to that file. It does not need +to worry about endpoints, interfaces or strings numbers but +simply provide descriptors such as if the function was the +only one (endpoints and strings numbers starting from one and +interface numbers starting from zero). The FunctionFS changes +them as needed also handling situation when numbers differ in +different configurations. + +When descriptors and strings are written "ep#" files appear +(one for each declared endpoint) which handle communication on +a single endpoint. Again, FunctionFS takes care of the real +numbers and changing of the configuration (which means that +"ep1" file may be really mapped to (say) endpoint 3 (and when +configuration changes to (say) endpoint 2)). "ep0" is used +for receiving events and handling setup requests. + +When all files are closed the function disables itself. + +What I also want to mention is that the FunctionFS is designed in such +a way that it is possible to mount it several times so in the end +a gadget could use several FunctionFS functions. The idea is that +each FunctionFS instance is identified by the device name used +when mounting. + +One can imagine a gadget that has an Ethernet, MTP and HID interfaces +where the last two are implemented via FunctionFS. On user space +level it would look like this: + +$ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid +$ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp +$ ( cd /dev/ffs-mtp && mtp-daemon ) & +$ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid +$ ( cd /dev/ffs-hid && hid-daemon ) & + +On kernel level the gadget checks ffs_data->dev_name to identify +whether it's FunctionFS designed for MTP ("mtp") or HID ("hid"). + +If no "functions" module parameters is supplied, the driver accepts +just one function with any name. + +When "functions" module parameter is supplied, only functions +with listed names are accepted. In particular, if the "functions" +parameter's value is just a one-element list, then the behaviour +is similar to when there is no "functions" at all; however, +only a function with the specified name is accepted. + +The gadget is registered only after all the declared function +filesystems have been mounted and USB descriptors of all functions +have been written to their ep0's. + +Conversely, the gadget is unregistered after the first USB function +closes its endpoints. + diff --git a/Documentation/usb/gadget_configfs.txt b/Documentation/usb/gadget_configfs.txt new file mode 100644 index 00000000000..4cf53e40661 --- /dev/null +++ b/Documentation/usb/gadget_configfs.txt @@ -0,0 +1,384 @@ + + + + + Linux USB gadget configured through configfs + + + 25th April 2013 + + + + +Overview +======== + +A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can +be connected to a USB Host to extend it with additional functions like a serial +port or a mass storage capability. + +A gadget is seen by its host as a set of configurations, each of which contains +a number of interfaces which, from the gadget's perspective, are known as +functions, each function representing e.g. a serial connection or a SCSI disk. + +Linux provides a number of functions for gadgets to use. + +Creating a gadget means deciding what configurations there will be +and which functions each configuration will provide. + +Configfs (please see Documentation/filesystems/configfs/*) lends itself nicely +for the purpose of telling the kernel about the above mentioned decision. +This document is about how to do it. + +It also describes how configfs integration into gadget is designed. + + + + +Requirements +============ + +In order for this to work configfs must be available, so CONFIGFS_FS must be +'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS. + + + + +Usage +===== + +(The original post describing the first function +made available through configfs can be seen here: +http://www.spinics.net/lists/linux-usb/msg76388.html) + +$ modprobe libcomposite +$ mount none $CONFIGFS_HOME -t configfs + +where CONFIGFS_HOME is the mount point for configfs + +1. Creating the gadgets +----------------------- + +For each gadget to be created its corresponding directory must be created: + +$ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name> + +e.g.: + +$ mkdir $CONFIGFS_HOME/usb_gadget/g1 + +... +... +... + +$ cd $CONFIGFS_HOME/usb_gadget/g1 + +Each gadget needs to have its vendor id <VID> and product id <PID> specified: + +$ echo <VID> > idVendor +$ echo <PID> > idProduct + +A gadget also needs its serial number, manufacturer and product strings. +In order to have a place to store them, a strings subdirectory must be created +for each language, e.g.: + +$ mkdir strings/0x409 + +Then the strings can be specified: + +$ echo <serial number> > strings/0x409/serialnumber +$ echo <manufacturer> > strings/0x409/manufacturer +$ echo <product> > strings/0x409/product + +2. Creating the configurations +------------------------------ + +Each gadget will consist of a number of configurations, their corresponding +directories must be created: + +$ mkdir configs/<name>.<number> + +where <name> can be any string which is legal in a filesystem and the +<number> is the configuration's number, e.g.: + +$ mkdir configs/c.1 + +... +... +... + +Each configuration also needs its strings, so a subdirectory must be created +for each language, e.g.: + +$ mkdir configs/c.1/strings/0x409 + +Then the configuration string can be specified: + +$ echo <configuration> > configs/c.1/strings/0x409/configuration + +Some attributes can also be set for a configuration, e.g.: + +$ echo 120 > configs/c.1/MaxPower + +3. Creating the functions +------------------------- + +The gadget will provide some functions, for each function its corresponding +directory must be created: + +$ mkdir functions/<name>.<instance name> + +where <name> corresponds to one of allowed function names and instance name +is an arbitrary string allowed in a filesystem, e.g.: + +$ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() + +... +... +... + +Each function provides its specific set of attributes, with either read-only +or read-write access. Where applicable they need to be written to as +appropriate. +Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information. + +4. Associating the functions with their configurations +------------------------------------------------------ + +At this moment a number of gadgets is created, each of which has a number of +configurations specified and a number of functions available. What remains +is specifying which function is available in which configuration (the same +function can be used in multiple configurations). This is achieved with +creating symbolic links: + +$ ln -s functions/<name>.<instance name> configs/<name>.<number> + +e.g.: + +$ ln -s functions/ncm.usb0 configs/c.1 + +... +... +... + +5. Enabling the gadget +---------------------- + +All the above steps serve the purpose of composing the gadget of +configurations and functions. + +An example directory structure might look like this: + +. +./strings +./strings/0x409 +./strings/0x409/serialnumber +./strings/0x409/product +./strings/0x409/manufacturer +./configs +./configs/c.1 +./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0 +./configs/c.1/strings +./configs/c.1/strings/0x409 +./configs/c.1/strings/0x409/configuration +./configs/c.1/bmAttributes +./configs/c.1/MaxPower +./functions +./functions/ncm.usb0 +./functions/ncm.usb0/ifname +./functions/ncm.usb0/qmult +./functions/ncm.usb0/host_addr +./functions/ncm.usb0/dev_addr +./UDC +./bcdUSB +./bcdDevice +./idProduct +./idVendor +./bMaxPacketSize0 +./bDeviceProtocol +./bDeviceSubClass +./bDeviceClass + + +Such a gadget must be finally enabled so that the USB host can enumerate it. +In order to enable the gadget it must be bound to a UDC (USB Device Controller). + +$ echo <udc name> > UDC + +where <udc name> is one of those found in /sys/class/udc/* +e.g.: + +$ echo s3c-hsotg > UDC + + +6. Disabling the gadget +----------------------- + +$ echo "" > UDC + +7. Cleaning up +-------------- + +Remove functions from configurations: + +$ rm configs/<config name>.<number>/<function> + +where <config name>.<number> specify the configuration and <function> is +a symlink to a function being removed from the configuration, e.g.: + +$ rm configfs/c.1/ncm.usb0 + +... +... +... + +Remove strings directories in configurations + +$ rmdir configs/<config name>.<number>/strings/<lang> + +e.g.: + +$ rmdir configs/c.1/strings/0x409 + +... +... +... + +and remove the configurations + +$ rmdir configs/<config name>.<number> + +e.g.: + +rmdir configs/c.1 + +... +... +... + +Remove functions (function modules are not unloaded, though) + +$ rmdir functions/<name>.<instance name> + +e.g.: + +$ rmdir functions/ncm.usb0 + +... +... +... + +Remove strings directories in the gadget + +$ rmdir strings/<lang> + +e.g.: + +$ rmdir strings/0x409 + +and finally remove the gadget: + +$ cd .. +$ rmdir <gadget name> + +e.g.: + +$ rmdir g1 + + + + +Implementation design +===================== + +Below the idea of how configfs works is presented. +In configfs there are items and groups, both represented as directories. +The difference between an item and a group is that a group can contain +other groups. In the picture below only an item is shown. +Both items and groups can have attributes, which are represented as files. +The user can create and remove directories, but cannot remove files, +which can be read-only or read-write, depending on what they represent. + +The filesystem part of configfs operates on config_items/groups and +configfs_attributes which are generic and of the same type for all +configured elements. However, they are embedded in usage-specific +larger structures. In the picture below there is a "cs" which contains +a config_item and an "sa" which contains a configfs_attribute. + +The filesystem view would be like this: + +./ +./cs (directory) + | + +--sa (file) + | + . + . + . + +Whenever a user reads/writes the "sa" file, a function is called +which accepts a struct config_item and a struct configfs_attribute. +In the said function the "cs" and "sa" are retrieved using the well +known container_of technique and an appropriate sa's function (show or +store) is called and passed the "cs" and a character buffer. The "show" +is for displaying the file's contents (copy data from the cs to the +buffer), while the "store" is for modifying the file's contents (copy data +from the buffer to the cs), but it is up to the implementer of the +two functions to decide what they actually do. + +typedef struct configured_structure cs; +typedef struct specific_attribute sa; + + sa + +----------------------------------+ + cs | (*show)(cs *, buffer); | ++-----------------+ | (*store)(cs *, buffer, length); | +| | | | +| +-------------+ | | +------------------+ | +| | struct |-|----|------>|struct | | +| | config_item | | | |configfs_attribute| | +| +-------------+ | | +------------------+ | +| | +----------------------------------+ +| data to be set | . +| | . ++-----------------+ . + +The file names are decided by the config item/group designer, while +the directories in general can be named at will. A group can have +a number of its default sub-groups created automatically. + +For more information on configfs please see +Documentation/filesystems/configfs/*. + +The concepts described above translate to USB gadgets like this: + +1. A gadget has its config group, which has some attributes (idVendor, +idProduct etc) and default sub-groups (configs, functions, strings). +Writing to the attributes causes the information to be stored in +appropriate locations. In the configs, functions and strings sub-groups +a user can create their sub-groups to represent configurations, functions, +and groups of strings in a given language. + +2. The user creates configurations and functions, in the configurations +creates symbolic links to functions. This information is used when the +gadget's UDC attribute is written to, which means binding the gadget +to the UDC. The code in drivers/usb/gadget/configfs.c iterates over +all configurations, and in each configuration it iterates over all +functions and binds them. This way the whole gadget is bound. + +3. The file drivers/usb/gadget/configfs.c contains code for + + - gadget's config_group + - gadget's default groups (configs, functions, strings) + - associating functions with configurations (symlinks) + +4. Each USB function naturally has its own view of what it wants +configured, so config_groups for particular functions are defined +in the functions implementation files drivers/usb/gadget/f_*.c. + +5. Funciton's code is written in such a way that it uses + +usb_get_function_instance(), which, in turn, calls request_module. +So, provided that modprobe works, modules for particular functions +are loaded automatically. Please note that the converse is not true: +after a gadget is disabled and torn down, the modules remain loaded. diff --git a/Documentation/usb/gadget_multi.txt b/Documentation/usb/gadget_multi.txt index 80f4ef0eb75..7d66a8636cb 100644 --- a/Documentation/usb/gadget_multi.txt +++ b/Documentation/usb/gadget_multi.txt @@ -14,7 +14,7 @@ A CDC ECM (Ethernet) function may be turned on via a Kconfig option and RNDIS can be turned off. If they are both enabled the gadget will have two configurations -- one with RNDIS and another with CDC ECM[3]. -Please not that if you use non-standard configuration (that is enable +Please note that if you use non-standard configuration (that is enable CDC ECM) you may need to change vendor and/or product ID. * Host drivers diff --git a/Documentation/usb/hotplug.txt b/Documentation/usb/hotplug.txt index 4c945716a66..6424b130485 100644 --- a/Documentation/usb/hotplug.txt +++ b/Documentation/usb/hotplug.txt @@ -33,9 +33,9 @@ you get the best hotplugging when you configure a highly modular system. KERNEL HOTPLUG HELPER (/sbin/hotplug) -When you compile with CONFIG_HOTPLUG, you get a new kernel parameter: -/proc/sys/kernel/hotplug, which normally holds the pathname "/sbin/hotplug". -That parameter names a program which the kernel may invoke at various times. +There is a kernel parameter: /proc/sys/kernel/hotplug, which normally +holds the pathname "/sbin/hotplug". That parameter names a program +which the kernel may invoke at various times. The /sbin/hotplug program can be invoked by any subsystem as part of its reaction to a configuration change, from a thread in that subsystem. diff --git a/Documentation/usb/mass-storage.txt b/Documentation/usb/mass-storage.txt new file mode 100644 index 00000000000..e89803a5a96 --- /dev/null +++ b/Documentation/usb/mass-storage.txt @@ -0,0 +1,225 @@ +* 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 + 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 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. diff --git a/Documentation/usb/mtouchusb.txt b/Documentation/usb/mtouchusb.txt index 86302cd53ed..a91adb26ea7 100644 --- a/Documentation/usb/mtouchusb.txt +++ b/Documentation/usb/mtouchusb.txt @@ -1,7 +1,7 @@ CHANGES - 0.3 - Created based off of scanner & INSTALL from the original touchscreen - driver on freshmeat (http://freshmeat.net/projects/3mtouchscreendriver) + driver on freecode (http://freecode.com/projects/3mtouchscreendriver) - Amended for linux-2.4.18, then 2.4.19 - 0.5 - Complete rewrite using Linux Input in 2.6.3 diff --git a/Documentation/usb/persist.txt b/Documentation/usb/persist.txt index 074b159b77c..35d70eda9ad 100644 --- a/Documentation/usb/persist.txt +++ b/Documentation/usb/persist.txt @@ -155,6 +155,9 @@ If the kernel gets fooled in this way, it's almost certain to cause data corruption and to crash your system. You'll have no one to blame but yourself. +For those devices with avoid_reset_quirk attribute being set, persist +maybe fail because they may morph after reset. + YOU HAVE BEEN WARNED! USE AT YOUR OWN RISK! That having been said, most of the time there shouldn't be any trouble diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt index 12511c98cc4..1392b61d6eb 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -33,6 +33,10 @@ built with CONFIG_USB_SUSPEND enabled (which depends on CONFIG_PM_RUNTIME). System PM support is present only if the kernel was built with CONFIG_SUSPEND or CONFIG_HIBERNATION enabled. +(Starting with the 3.10 kernel release, dynamic PM support for USB is +present whenever the kernel was built with CONFIG_PM_RUNTIME enabled. +The CONFIG_USB_SUSPEND option has been eliminated.) + What is Remote Wakeup? ---------------------- @@ -179,7 +183,8 @@ do: modprobe usbcore autosuspend=5 -Equivalently, you could add to /etc/modprobe.conf a line saying: +Equivalently, you could add to a configuration file in /etc/modprobe.d +a line saying: options usbcore autosuspend=5 @@ -205,10 +210,8 @@ initialized to 5. (The idle-delay values for already existing devices will not be affected.) Setting the initial default idle-delay to -1 will prevent any -autosuspend of any USB device. This is a simple alternative to -disabling CONFIG_USB_SUSPEND and rebuilding the kernel, and it has the -added benefit of allowing you to enable autosuspend for selected -devices. +autosuspend of any USB device. This has the benefit of allowing you +then to enable autosuspend for selected devices. Warnings @@ -345,7 +348,7 @@ autosuspend the device. Drivers need not be concerned about balancing changes to the usage counter; the USB core will undo any remaining "get"s when a driver is unbound from its interface. As a corollary, drivers must not call -any of the usb_autopm_* functions after their diconnect() routine has +any of the usb_autopm_* functions after their disconnect() routine has returned. Drivers using the async routines are responsible for their own diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt index afe596d5f20..98be9198267 100644 --- a/Documentation/usb/proc_usb_info.txt +++ b/Documentation/usb/proc_usb_info.txt @@ -7,7 +7,7 @@ The usbfs filesystem for USB devices is traditionally mounted at /proc/bus/usb. It provides the /proc/bus/usb/devices file, as well as the /proc/bus/usb/BBB/DDD files. -In many modern systems the usbfs filsystem isn't used at all. Instead +In many modern systems the usbfs filesystem isn't used at all. Instead USB device nodes are created under /dev/usb/ or someplace similar. The "devices" file is available in debugfs, typically as /sys/kernel/debug/usb/devices. @@ -54,9 +54,12 @@ it and 002/048 sometime later. These files can be read as binary data. The binary data consists of first the device descriptor, then the descriptors for each -configuration of the device. Multi-byte fields in the device and -configuration descriptors, but not other descriptors, are converted -to host endianness by the kernel. This information is also shown +configuration of the device. Multi-byte fields in the device descriptor +are converted to host endianness by the kernel. The configuration +descriptors are in bus endian format! The configuration descriptor +are wTotalLength bytes apart. If a device returns less configuration +descriptor data than indicated by wTotalLength there will be a hole in +the file for the missing bytes. This information is also shown in text form by the /proc/bus/usb/devices file, described later. These files may also be used to write user-level drivers for the USB diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index 5335fa8b06e..c42bb9cd3b4 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -183,10 +183,10 @@ An input control transfer to get a port status. d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 < d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000 -An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper -to a storage device at address 5: +An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte +Bulk wrapper to a storage device at address 5: -dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000 +dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000 dd65f0e8 4128379808 C Bo:1:005:2 0 31 > * Raw binary format and API diff --git a/Documentation/usb/wusb-cbaf b/Documentation/usb/wusb-cbaf index 426ddaaef96..8b3d43efce9 100644 --- a/Documentation/usb/wusb-cbaf +++ b/Documentation/usb/wusb-cbaf @@ -36,7 +36,7 @@ COMMAND/ARGS are get-cdid DEVICE - Get the device ID associated to the HOST-CHDI we sent with + Get the device ID associated to the HOST-CHID we sent with 'set-chid'. We might not know about it. set-cc DEVICE |