diff options
Diffstat (limited to 'Documentation/usb')
| -rw-r--r-- | Documentation/usb/URB.txt | 21 | ||||
| -rw-r--r-- | Documentation/usb/WUSB-Design-overview.txt | 2 | ||||
| -rw-r--r-- | Documentation/usb/chipidea.txt | 71 | ||||
| -rw-r--r-- | Documentation/usb/error-codes.txt | 7 | ||||
| -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 | 17 | ||||
| -rw-r--r-- | Documentation/usb/power-management.txt | 10 | ||||
| -rw-r--r-- | Documentation/usb/proc_usb_info.txt | 9 |
10 files changed, 494 insertions, 35 deletions
diff --git a/Documentation/usb/URB.txt b/Documentation/usb/URB.txt index 00d2c644068..50da0d45544 100644 --- a/Documentation/usb/URB.txt +++ b/Documentation/usb/URB.txt @@ -195,13 +195,12 @@ by 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 @@ -210,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/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/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 index e9b9334627b..e89803a5a96 100644 --- a/Documentation/usb/mass-storage.txt +++ b/Documentation/usb/mass-storage.txt @@ -13,16 +13,16 @@ 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 + 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). It - will talk only briefly about how to use MSF within composite - 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 @@ -198,16 +198,15 @@ 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 + 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 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: + 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 diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt index 4204eb01fd3..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? ---------------------- @@ -206,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 diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt index c9c3f0f5ad7..98be9198267 100644 --- a/Documentation/usb/proc_usb_info.txt +++ b/Documentation/usb/proc_usb_info.txt @@ -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 |