diff options
Diffstat (limited to 'Documentation/usb')
23 files changed, 989 insertions, 351 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/callbacks.txt b/Documentation/usb/callbacks.txt index bfb36b34b79..9e85846bdb9 100644 --- a/Documentation/usb/callbacks.txt +++ b/Documentation/usb/callbacks.txt @@ -95,9 +95,11 @@ pre_reset int (*pre_reset)(struct usb_interface *intf); -Another driver or user space is triggering a reset on the device which -contains the interface passed as an argument. Cease IO and save any -device state you need to restore. +A driver or user space is triggering a reset on the device which +contains the interface passed as an argument. Cease IO, wait for all +outstanding URBs to complete, and save any device state you need to +restore. No more URBs may be submitted until the post_reset method +is called. If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you are in atomic context. 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/dma.txt b/Documentation/usb/dma.txt index 84ef865237d..444651e70d9 100644 --- a/Documentation/usb/dma.txt +++ b/Documentation/usb/dma.txt @@ -7,7 +7,7 @@ API OVERVIEW The big picture is that USB drivers can continue to ignore most DMA issues, though they still must provide DMA-ready buffers (see -Documentation/PCI/PCI-DMA-mapping.txt). That's how they've worked through +Documentation/DMA-API-HOWTO.txt). That's how they've worked through the 2.4 (and earlier) kernels. OR: they can now be DMA-aware. @@ -57,7 +57,7 @@ and effects like cache-trashing can impose subtle penalties. force a consistent memory access ordering by using memory barriers. It's not using a streaming DMA mapping, so it's good for small transfers on systems where the I/O would otherwise thrash an IOMMU mapping. (See - Documentation/PCI/PCI-DMA-mapping.txt for definitions of "coherent" and + Documentation/DMA-API-HOWTO.txt for definitions of "coherent" and "streaming" DMA mappings.) Asking for 1/Nth of a page (as well as asking for N pages) is reasonably @@ -88,7 +88,7 @@ WORKING WITH EXISTING BUFFERS Existing buffers aren't usable for DMA without first being mapped into the DMA address space of the device. However, most buffers passed to your driver can safely be used with such DMA mapping. (See the first section -of Documentation/PCI/PCI-DMA-mapping.txt, titled "What memory is DMA-able?") +of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") - When you're using scatterlists, you can map everything at once. On some systems, this kicks in an IOMMU and turns the scatterlists into single diff --git a/Documentation/usb/dwc3.txt b/Documentation/usb/dwc3.txt new file mode 100644 index 00000000000..1d02c01d1c7 --- /dev/null +++ b/Documentation/usb/dwc3.txt @@ -0,0 +1,45 @@ + + TODO +~~~~~~ +Please pick something while reading :) + +- Convert interrupt handler to per-ep-thread-irq + + As it turns out some DWC3-commands ~1ms to complete. Currently we spin + until the command completes which is bad. + + Implementation idea: + - dwc core implements a demultiplexing irq chip for interrupts per + endpoint. The interrupt numbers are allocated during probe and belong + to the device. If MSI provides per-endpoint interrupt this dummy + interrupt chip can be replaced with "real" interrupts. + - interrupts are requested / allocated on usb_ep_enable() and removed on + usb_ep_disable(). Worst case are 32 interrupts, the lower limit is two + for ep0/1. + - dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout() + until the command completes. + - the interrupt handler is split into the following pieces: + - primary handler of the device + goes through every event and calls generic_handle_irq() for event + it. On return from generic_handle_irq() in acknowledges the event + counter so interrupt goes away (eventually). + + - threaded handler of the device + none + + - primary handler of the EP-interrupt + 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 + handed something to thread so we don't process event X prio Y + where X > Y. + + - threaded handler of the EP-interrupt + handles the remaining EP work which might sleep such as waiting + for command completion. + + Latency: + There should be no increase in latency since the interrupt-thread has a + high priority and will be run before an average task in user land + (except the user changed priorities). diff --git a/Documentation/usb/ehci.txt b/Documentation/usb/ehci.txt index 9dcafa7d930..160bd6c3ab7 100644 --- a/Documentation/usb/ehci.txt +++ b/Documentation/usb/ehci.txt @@ -210,3 +210,5 @@ TBD: Interrupt and ISO transfer performance issues. Those periodic transfers are fully scheduled, so the main issue is likely to be how to trigger "high bandwidth" modes. +TBD: More than standard 80% periodic bandwidth allocation is possible +through sysfs uframe_periodic_max parameter. Describe that. diff --git a/Documentation/usb/error-codes.txt b/Documentation/usb/error-codes.txt index d83703ea74b..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. @@ -76,6 +77,13 @@ A transfer's actual_length may be positive even when an error has been reported. That's because transfers often involve several packets, so that one or more packets could finish before an error stops further endpoint I/O. +For isochronous URBs, the urb status value is non-zero only if the URB is +unlinked, the device is removed, the host controller is disabled, or the total +transferred length is less than the requested length and the URB_SHORT_NOT_OK +flag is set. Completion handlers for isochronous URBs should only see +urb->status set to zero, -ENOENT, -ECONNRESET, -ESHUTDOWN, or -EREMOTEIO. +Individual frame descriptor status fields may report more status codes. + 0 Transfer completed successfully @@ -132,7 +140,7 @@ one or more packets could finish before an error stops further endpoint I/O. device removal events immediately. -EXDEV ISO transfer only partially completed - look at individual frame status for details + (only set in iso_frame_desc[n].status, not urb->status) -EINVAL ISO madness, if this happens: Log off and go home 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_hid.txt b/Documentation/usb/gadget_hid.txt index f4a51f56742..12696c2e43f 100644 --- a/Documentation/usb/gadget_hid.txt +++ b/Documentation/usb/gadget_hid.txt @@ -81,8 +81,8 @@ Send and receive HID reports to do this. hid_gadget_test is a small interactive program to test the HID - gadget driver. To use, point it at a hidg device and set the - device type (keyboard / mouse / joystick) - E.G.: + gadget driver. To use, point it at a hidg device and set the + device type (keyboard / mouse / joystick) - E.G.: # hid_gadget_test /dev/hidg0 keyboard @@ -97,7 +97,7 @@ Send and receive HID reports HID gadget. Another interesting example is the caps lock test. Type - -–caps-lock and hit return. A report is then sent by the + --caps-lock and hit return. A report is then sent by the gadget and you should receive the host answer, corresponding to the caps lock LED status. 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/hiddev.txt b/Documentation/usb/hiddev.txt deleted file mode 100644 index 6e8c9f1d2f2..00000000000 --- a/Documentation/usb/hiddev.txt +++ /dev/null @@ -1,205 +0,0 @@ -Care and feeding of your Human Interface Devices - -INTRODUCTION - -In addition to the normal input type HID devices, USB also uses the -human interface device protocols for things that are not really human -interfaces, but have similar sorts of communication needs. The two big -examples for this are power devices (especially uninterruptable power -supplies) and monitor control on higher end monitors. - -To support these disparate requirements, the Linux USB system provides -HID events to two separate interfaces: -* the input subsystem, which converts HID events into normal input -device interfaces (such as keyboard, mouse and joystick) and a -normalised event interface - see Documentation/input/input.txt -* the hiddev interface, which provides fairly raw HID events - -The data flow for a HID event produced by a device is something like -the following : - - usb.c ---> hid-core.c ----> hid-input.c ----> [keyboard/mouse/joystick/event] - | - | - --> hiddev.c ----> POWER / MONITOR CONTROL - -In addition, other subsystems (apart from USB) can potentially feed -events into the input subsystem, but these have no effect on the hid -device interface. - -USING THE HID DEVICE INTERFACE - -The hiddev interface is a char interface using the normal USB major, -with the minor numbers starting at 96 and finishing at 111. Therefore, -you need the following commands: -mknod /dev/usb/hiddev0 c 180 96 -mknod /dev/usb/hiddev1 c 180 97 -mknod /dev/usb/hiddev2 c 180 98 -mknod /dev/usb/hiddev3 c 180 99 -mknod /dev/usb/hiddev4 c 180 100 -mknod /dev/usb/hiddev5 c 180 101 -mknod /dev/usb/hiddev6 c 180 102 -mknod /dev/usb/hiddev7 c 180 103 -mknod /dev/usb/hiddev8 c 180 104 -mknod /dev/usb/hiddev9 c 180 105 -mknod /dev/usb/hiddev10 c 180 106 -mknod /dev/usb/hiddev11 c 180 107 -mknod /dev/usb/hiddev12 c 180 108 -mknod /dev/usb/hiddev13 c 180 109 -mknod /dev/usb/hiddev14 c 180 110 -mknod /dev/usb/hiddev15 c 180 111 - -So you point your hiddev compliant user-space program at the correct -interface for your device, and it all just works. - -Assuming that you have a hiddev compliant user-space program, of -course. If you need to write one, read on. - - -THE HIDDEV API -This description should be read in conjunction with the HID -specification, freely available from http://www.usb.org, and -conveniently linked of http://www.linux-usb.org. - -The hiddev API uses a read() interface, and a set of ioctl() calls. - -HID devices exchange data with the host computer using data -bundles called "reports". Each report is divided into "fields", -each of which can have one or more "usages". In the hid-core, -each one of these usages has a single signed 32 bit value. - -read(): -This is the event interface. When the HID device's state changes, -it performs an interrupt transfer containing a report which contains -the changed value. The hid-core.c module parses the report, and -returns to hiddev.c the individual usages that have changed within -the report. In its basic mode, the hiddev will make these individual -usage changes available to the reader using a struct hiddev_event: - - struct hiddev_event { - unsigned hid; - signed int value; - }; - -containing the HID usage identifier for the status that changed, and -the value that it was changed to. Note that the structure is defined -within <linux/hiddev.h>, along with some other useful #defines and -structures. The HID usage identifier is a composite of the HID usage -page shifted to the 16 high order bits ORed with the usage code. The -behavior of the read() function can be modified using the HIDIOCSFLAG -ioctl() described below. - - -ioctl(): -This is the control interface. There are a number of controls: - -HIDIOCGVERSION - int (read) -Gets the version code out of the hiddev driver. - -HIDIOCAPPLICATION - (none) -This ioctl call returns the HID application usage associated with the -hid device. The third argument to ioctl() specifies which application -index to get. This is useful when the device has more than one -application collection. If the index is invalid (greater or equal to -the number of application collections this device has) the ioctl -returns -1. You can find out beforehand how many application -collections the device has from the num_applications field from the -hiddev_devinfo structure. - -HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write) -This returns a superset of the information above, providing not only -application collections, but all the collections the device has. It -also returns the level the collection lives in the hierarchy. -The user passes in a hiddev_collection_info struct with the index -field set to the index that should be returned. The ioctl fills in -the other fields. If the index is larger than the last collection -index, the ioctl returns -1 and sets errno to -EINVAL. - -HIDIOCGDEVINFO - struct hiddev_devinfo (read) -Gets a hiddev_devinfo structure which describes the device. - -HIDIOCGSTRING - struct hiddev_string_descriptor (read/write) -Gets a string descriptor from the device. The caller must fill in the -"index" field to indicate which descriptor should be returned. - -HIDIOCINITREPORT - (none) -Instructs the kernel to retrieve all input and feature report values -from the device. At this point, all the usage structures will contain -current values for the device, and will maintain it as the device -changes. Note that the use of this ioctl is unnecessary in general, -since later kernels automatically initialize the reports from the -device at attach time. - -HIDIOCGNAME - string (variable length) -Gets the device name - -HIDIOCGREPORT - struct hiddev_report_info (write) -Instructs the kernel to get a feature or input report from the device, -in order to selectively update the usage structures (in contrast to -INITREPORT). - -HIDIOCSREPORT - struct hiddev_report_info (write) -Instructs the kernel to send a report to the device. This report can -be filled in by the user through HIDIOCSUSAGE calls (below) to fill in -individual usage values in the report before sending the report in full -to the device. - -HIDIOCGREPORTINFO - struct hiddev_report_info (read/write) -Fills in a hiddev_report_info structure for the user. The report is -looked up by type (input, output or feature) and id, so these fields -must be filled in by the user. The ID can be absolute -- the actual -report id as reported by the device -- or relative -- -HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT | -report_id) for the next report after report_id. Without a-priori -information about report ids, the right way to use this ioctl is to -use the relative IDs above to enumerate the valid IDs. The ioctl -returns non-zero when there is no more next ID. The real report ID is -filled into the returned hiddev_report_info structure. - -HIDIOCGFIELDINFO - struct hiddev_field_info (read/write) -Returns the field information associated with a report in a -hiddev_field_info structure. The user must fill in report_id and -report_type in this structure, as above. The field_index should also -be filled in, which should be a number from 0 and maxfield-1, as -returned from a previous HIDIOCGREPORTINFO call. - -HIDIOCGUCODE - struct hiddev_usage_ref (read/write) -Returns the usage_code in a hiddev_usage_ref structure, given that -given its report type, report id, field index, and index within the -field have already been filled into the structure. - -HIDIOCGUSAGE - struct hiddev_usage_ref (read/write) -Returns the value of a usage in a hiddev_usage_ref structure. The -usage to be retrieved can be specified as above, or the user can -choose to fill in the report_type field and specify the report_id as -HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be -filled in with the report and field information associated with this -usage if it is found. - -HIDIOCSUSAGE - struct hiddev_usage_ref (write) -Sets the value of a usage in an output report. The user fills in -the hiddev_usage_ref structure as above, but additionally fills in -the value field. - -HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write) -Returns the collection index associated with this usage. This -indicates where in the collection hierarchy this usage sits. - -HIDIOCGFLAG - int (read) -HIDIOCSFLAG - int (write) -These operations respectively inspect and replace the mode flags -that influence the read() call above. The flags are as follows: - - HIDDEV_FLAG_UREF - read() calls will now return - struct hiddev_usage_ref instead of struct hiddev_event. - This is a larger structure, but in situations where the - device has more than one usage in its reports with the - same usage code, this mode serves to resolve such - ambiguity. - - HIDDEV_FLAG_REPORT - This flag can only be used in conjunction - with HIDDEV_FLAG_UREF. With this flag set, when the device - sends a report, a struct hiddev_usage_ref will be returned - to read() filled in with the report_type and report_id, but - with field_index set to FIELD_INDEX_NONE. This serves as - additional notification when the device has sent a report. 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/linux-cdc-acm.inf b/Documentation/usb/linux-cdc-acm.inf index 612e7220fb2..f0ffc27d4c0 100644 --- a/Documentation/usb/linux-cdc-acm.inf +++ b/Documentation/usb/linux-cdc-acm.inf @@ -90,10 +90,10 @@ ServiceBinary=%12%\USBSER.sys [SourceDisksFiles] [SourceDisksNames] [DeviceList] -%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02 +%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_1D6B&PID_0104&MI_02, USB\VID_1D6B&PID_0106&MI_00 [DeviceList.NTamd64] -%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02 +%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_1D6B&PID_0104&MI_02, USB\VID_1D6B&PID_0106&MI_00 ;------------------------------------------------------------------------------ diff --git a/Documentation/usb/linux.inf b/Documentation/usb/linux.inf index 4dee9585122..4ffa715b0ae 100644 --- a/Documentation/usb/linux.inf +++ b/Documentation/usb/linux.inf @@ -18,15 +18,15 @@ DriverVer = 06/21/2006,6.0.6000.16384 ; Decoration for x86 architecture [LinuxDevices.NTx86] -%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00 +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_1d6b&PID_0104&MI_00 ; Decoration for x64 architecture [LinuxDevices.NTamd64] -%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00 +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_1d6b&PID_0104&MI_00 ; Decoration for ia64 architecture [LinuxDevices.NTia64] -%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00 +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_1d6b&PID_0104&MI_00 ;@@@ This is the common setting for setup [ControlFlags] 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 b29d8e56cf2..1392b61d6eb 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -2,7 +2,7 @@ Alan Stern <stern@rowland.harvard.edu> - December 11, 2009 + October 28, 2010 @@ -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? ---------------------- @@ -107,9 +111,14 @@ allowed to issue dynamic suspends. The user interface for controlling dynamic PM is located in the power/ subdirectory of each USB device's sysfs directory, that is, in /sys/bus/usb/devices/.../power/ where "..." is the device's ID. The -relevant attribute files are: wakeup, control, and autosuspend. -(There may also be a file named "level"; this file was deprecated -as of the 2.6.35 kernel and replaced by the "control" file.) +relevant attribute files are: wakeup, control, and +autosuspend_delay_ms. (There may also be a file named "level"; this +file was deprecated as of the 2.6.35 kernel and replaced by the +"control" file. In 2.6.38 the "autosuspend" file will be deprecated +and replaced by the "autosuspend_delay_ms" file. The only difference +is that the newer file expresses the delay in milliseconds whereas the +older file uses seconds. Confusingly, both files are present in 2.6.37 +but only "autosuspend" works.) power/wakeup @@ -140,38 +149,42 @@ as of the 2.6.35 kernel and replaced by the "control" file.) suspended and autoresume was not allowed. This setting is no longer supported.) - power/autosuspend + power/autosuspend_delay_ms This file contains an integer value, which is the - number of seconds the device should remain idle before - the kernel will autosuspend it (the idle-delay time). - The default is 2. 0 means to autosuspend as soon as - the device becomes idle, and negative values mean - never to autosuspend. You can write a number to the - file to change the autosuspend idle-delay time. - -Writing "-1" to power/autosuspend and writing "on" to power/control do -essentially the same thing -- they both prevent the device from being -autosuspended. Yes, this is a redundancy in the API. + number of milliseconds the device should remain idle + before the kernel will autosuspend it (the idle-delay + time). The default is 2000. 0 means to autosuspend + as soon as the device becomes idle, and negative + values mean never to autosuspend. You can write a + number to the file to change the autosuspend + idle-delay time. + +Writing "-1" to power/autosuspend_delay_ms and writing "on" to +power/control do essentially the same thing -- they both prevent the +device from being autosuspended. Yes, this is a redundancy in the +API. (In 2.6.21 writing "0" to power/autosuspend would prevent the device from being autosuspended; the behavior was changed in 2.6.22. The power/autosuspend attribute did not exist prior to 2.6.21, and the power/level attribute did not exist prior to 2.6.22. power/control -was added in 2.6.34.) +was added in 2.6.34, and power/autosuspend_delay_ms was added in +2.6.37 but did not become functional until 2.6.38.) Changing the default idle-delay time ------------------------------------ -The default autosuspend idle-delay time is controlled by a module -parameter in usbcore. You can specify the value when usbcore is -loaded. For example, to set it to 5 seconds instead of 2 you would +The default autosuspend idle-delay time (in seconds) is controlled by +a module parameter in usbcore. You can specify the value when usbcore +is loaded. For example, to set it to 5 seconds instead of 2 you would 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 @@ -197,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 @@ -234,25 +245,23 @@ every device. If a driver knows that its device has proper suspend/resume support, it can enable autosuspend all by itself. For example, the video -driver for a laptop's webcam might do this, since these devices are -rarely used and so should normally be autosuspended. +driver for a laptop's webcam might do this (in recent kernels they +do), since these devices are rarely used and so should normally be +autosuspended. Sometimes it turns out that even when a device does work okay with -autosuspend there are still problems. For example, there are -experimental patches adding autosuspend support to the usbhid driver, -which manages keyboards and mice, among other things. Tests with a -number of keyboards showed that typing on a suspended keyboard, while -causing the keyboard to do a remote wakeup all right, would -nonetheless frequently result in lost keystrokes. Tests with mice -showed that some of them would issue a remote-wakeup request in -response to button presses but not to motion, and some in response to -neither. +autosuspend there are still problems. For example, the usbhid driver, +which manages keyboards and mice, has autosuspend support. Tests with +a number of keyboards show that typing on a suspended keyboard, while +causing the keyboard to do a remote wakeup all right, will nonetheless +frequently result in lost keystrokes. Tests with mice show that some +of them will issue a remote-wakeup request in response to button +presses but not to motion, and some in response to neither. The kernel will not prevent you from enabling autosuspend on devices that can't handle it. It is even possible in theory to damage a -device by suspending it at the wrong time -- for example, suspending a -USB hard disk might cause it to spin down without parking the heads. -(Highly unlikely, but possible.) Take care. +device by suspending it at the wrong time. (Highly unlikely, but +possible.) Take care. The driver interface for Power Management @@ -336,14 +345,10 @@ autosuspend the interface's device. When the usage counter is = 0 then the interface is considered to be idle, and the kernel may autosuspend the device. -(There is a similar usage counter field in struct usb_device, -associated with the device itself rather than any of its interfaces. -This counter is used only by the USB core.) - 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 @@ -409,11 +414,11 @@ during autosuspend. For example, there's not much point autosuspending a keyboard if the user can't cause the keyboard to do a remote wakeup by typing on it. If the driver sets intf->needs_remote_wakeup to 1, the kernel won't autosuspend the -device if remote wakeup isn't available or has been disabled through -the power/wakeup attribute. (If the device is already autosuspended, -though, setting this flag won't cause the kernel to autoresume it. -Normally a driver would set this flag in its probe method, at which -time the device is guaranteed not to be autosuspended.) +device if remote wakeup isn't available. (If the device is already +autosuspended, though, setting this flag won't cause the kernel to +autoresume it. Normally a driver would set this flag in its probe +method, at which time the device is guaranteed not to be +autosuspended.) If a driver does its I/O asynchronously in interrupt context, it should call usb_autopm_get_interface_async() before starting output and @@ -422,26 +427,25 @@ it receives an input event, it should call usb_mark_last_busy(struct usb_device *udev); -in the event handler. This sets udev->last_busy to the current time. -udev->last_busy is the field used for idle-delay calculations; -updating it will cause any pending autosuspend to be moved back. Most -of the usb_autopm_* routines will also set the last_busy field to the -current time. +in the event handler. This tells the PM core that the device was just +busy and therefore the next autosuspend idle-delay expiration should +be pushed back. Many of the usb_autopm_* routines also make this call, +so drivers need to worry only when interrupt-driven input arrives. Asynchronous operation is always subject to races. For example, a -driver may call one of the usb_autopm_*_interface_async() routines at -a time when the core has just finished deciding the device has been -idle for long enough but not yet gotten around to calling the driver's -suspend method. The suspend method must be responsible for -synchronizing with the output request routine and the URB completion -handler; it should cause autosuspends to fail with -EBUSY if the -driver needs to use the device. +driver may call the usb_autopm_get_interface_async() routine at a time +when the core has just finished deciding the device has been idle for +long enough but not yet gotten around to calling the driver's suspend +method. The suspend method must be responsible for synchronizing with +the I/O request routine and the URB completion handler; it should +cause autosuspends to fail with -EBUSY if the driver needs to use the +device. External suspend calls should never be allowed to fail in this way, -only autosuspend calls. The driver can tell them apart by checking -the PM_EVENT_AUTO bit in the message.event argument to the suspend -method; this bit will be set for internal PM events (autosuspend) and -clear for external PM events. +only autosuspend calls. The driver can tell them apart by applying +the PMSG_IS_AUTO() macro to the message argument to the suspend +method; it will return True for internal PM events (autosuspend) and +False for external PM events. Mutual exclusion @@ -472,7 +476,9 @@ Firstly, a device may already be autosuspended when a system suspend occurs. Since system suspends are supposed to be as transparent as possible, the device should remain suspended following the system resume. But this theory may not work out well in practice; over time -the kernel's behavior in this regard has changed. +the kernel's behavior in this regard has changed. As of 2.6.37 the +policy is to resume all devices during a system resume and let them +handle their own runtime suspends afterward. Secondly, a dynamic power-management event may occur as a system suspend is underway. The window for this is short, since system @@ -484,3 +490,29 @@ succeed, it may still remain active and thus cause the system to resume as soon as the system suspend is complete. Or the remote wakeup may fail and get lost. Which outcome occurs depends on timing and on the hardware and firmware design. + + + xHCI hardware link PM + --------------------- + +xHCI host controller provides hardware link power management to usb2.0 +(xHCI 1.0 feature) and usb3.0 devices which support link PM. By +enabling hardware LPM, the host can automatically put the device into +lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices), +which state device can enter and resume very quickly. + +The user interface for controlling USB2 hardware LPM is located in the +power/ subdirectory of each USB device's sysfs directory, that is, in +/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The +relevant attribute files is usb2_hardware_lpm. + + power/usb2_hardware_lpm + + When a USB2 device which support LPM is plugged to a + xHCI host root hub which support software LPM, the + host will run a software LPM test for it; if the device + enters L1 state and resume successfully and the host + supports USB2 hardware LPM, this file will show up and + driver will enable hardware LPM for the device. You + can write y/Y/1 or n/N/0 to the file to enable/disable + USB2 hardware LPM manually. This is for test purpose mainly. 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 66f92d1194c..c42bb9cd3b4 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -12,6 +12,10 @@ Controller Drivers (HCD). So, if HCD is buggy, the traces reported by usbmon may not correspond to bus transactions precisely. This is the same situation as with tcpdump. +Two APIs are currently implemented: "text" and "binary". The binary API +is available through a character device in /dev namespace and is an ABI. +The text API is deprecated since 2.6.35, but available for convenience. + * How to use usbmon to collect raw text traces Unlike the packet socket, usbmon has an interface which provides traces @@ -43,10 +47,11 @@ This allows to filter away annoying devices that talk continuously. 2. Find which bus connects to the desired device -Run "cat /proc/bus/usb/devices", and find the T-line which corresponds to -the device. Usually you do it by looking for the vendor string. If you have -many similar devices, unplug one and compare two /proc/bus/usb/devices outputs. -The T-line will have a bus number. Example: +Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds +to the device. Usually you do it by looking for the vendor string. If you have +many similar devices, unplug one and compare the two +/sys/kernel/debug/usb/devices outputs. The T-line will have a bus number. +Example: T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 @@ -54,7 +59,10 @@ P: Vendor=0557 ProdID=2004 Rev= 1.00 S: Manufacturer=ATEN S: Product=UC100KM V2.00 -Bus=03 means it's bus 3. +"Bus=03" means it's bus 3. Alternatively, you can look at the output from +"lsusb" and get the bus number from the appropriate line. Example: + +Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00 3. Start 'cat' @@ -162,39 +170,11 @@ Here is the list of words, from left to right: not machine words, but really just a byte stream split into words to make it easier to read. Thus, the last word may contain from one to four bytes. The length of collected data is limited and can be less than the data length - report in Data Length word. - -Here is an example of code to read the data stream in a well known programming -language: - -class ParsedLine { - int data_len; /* Available length of data */ - byte data[]; - - void parseData(StringTokenizer st) { - int availwords = st.countTokens(); - data = new byte[availwords * 4]; - data_len = 0; - while (st.hasMoreTokens()) { - String data_str = st.nextToken(); - int len = data_str.length() / 2; - int i; - int b; // byte is signed, apparently?! XXX - for (i = 0; i < len; i++) { - // data[data_len] = Byte.parseByte( - // data_str.substring(i*2, i*2 + 2), - // 16); - b = Integer.parseInt( - data_str.substring(i*2, i*2 + 2), - 16); - if (b >= 128) - b *= -1; - data[data_len] = (byte) b; - data_len++; - } - } - } -} + reported in the Data Length word. In the case of an Isochronous input (Zi) + completion where the received data is sparse in the buffer, the length of + the collected data can be greater than the Data Length value (because Data + Length counts only the bytes that were received whereas the Data words + contain the entire transfer buffer). Examples: @@ -203,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 |