Merge git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/usb-2.6

<!-- !Edrivers/usb/gadget/epautoconf.c -->

</sect1>

<sect1 id="composite"><title>Composite Device Framework</title>

<para>The core API is sufficient for writing drivers for composite

USB devices (with more than one function in a given configuration),

and also multi-configuration devices (also more than one function,

but not necessarily sharing a given configuration).

There is however an optional framework which makes it easier to

reuse and combine functions.

</para>

<para>Devices using this framework provide a <emphasis>struct

usb_composite_driver</emphasis>, which in turn provides one or

more <emphasis>struct usb_configuration</emphasis> instances.

Each such configuration includes at least one

<emphasis>struct usb_function</emphasis>, which packages a user

visible role such as "network link" or "mass storage device".

Management functions may also exist, such as "Device Firmware

Upgrade".

</para>

!Iinclude/linux/usb/composite.h

!Edrivers/usb/gadget/composite.c

</sect1>

<sect1 id="functions"><title>Composite Device Functions</title>

<para>At this writing, a few of the current gadget drivers have

been converted to this framework.

Near-term plans include converting all of them, except for "gadgetfs".

</para>

!Edrivers/usb/gadget/f_acm.c

!Edrivers/usb/gadget/f_serial.c

</sect1>

</chapter>

<chapter id="controllers"><title>Peripheral Controller Drivers</title>

                 Linux Gadget Serial Driver v2.0

                           11/20/2004

                  (updated 8-May-2008 for v2.3)

License and Disclaimer

-------------

Versions of the gadget serial driver are available for the

2.4 Linux kernels, but this document assumes you are using

version 2.0 or later of the gadget serial driver in a 2.6

version 2.3 or later of the gadget serial driver in a 2.6

Linux kernel.

This document assumes that you are familiar with Linux and

USB and serial devices.  It also assumes you configure the Linux

gadget and usb drivers as modules.

With version 2.3 of the driver, major and minor device nodes are

no longer statically defined.  Your Linux based system should mount

sysfs in /sys, and use "mdev" (in Busybox) or "udev" to make the

/dev nodes matching the sysfs /sys/class/tty files.

Overview

--------

configuring the kernel.  Then rebuild and install the kernel or

modules.

The gadget serial driver uses major number 127, for now.  So you

will need to create a device node for it, like this:

  mknod /dev/ttygserial c 127 0

You only need to do this once.

Then you must load the gadget serial driver.  To load it as an

ACM device, do this:

ACM device (recommended for interoperability), do this:

  modprobe g_serial use_acm=1

side Linux system.  You can add this to the start up scripts, if

desired.

Your system should use mdev (from busybox) or udev to make the

device nodes.  After this gadget driver has been set up you should

then see a /dev/ttyGS0 node:

  # ls -l /dev/ttyGS0 | cat

  crw-rw----    1 root     root     253,   0 May  8 14:10 /dev/ttyGS0

  #

Note that the major number (253, above) is system-specific.  If

you need to create /dev nodes by hand, the right numbers to use

will be in the /sys/class/tty/ttyGS0/dev file.

When you link this gadget driver early, perhaps even statically,

you may want to set up an /etc/inittab entry to run "getty" on it.

The /dev/ttyGS0 line should work like most any other serial port.

If gadget serial is loaded as an ACM device you will want to use

either the Windows or Linux ACM driver on the host side.  If gadget

serial is loaded as a bulk in/out device, you will want to use the

same descriptors as before, including the Vendor and Product IDs, then

the kernel continues to use the same device structure.  In effect, the

kernel treats the device as though it had merely been reset instead of

unplugged.  The same thing happens if the host controller is in the

expected state but a USB device was unplugged and then replugged.

unplugged.

The same thing happens if the host controller is in the expected state

but a USB device was unplugged and then replugged, or if a USB device

fails to carry out a normal resume.

If no device is now attached to the port, or if the descriptors are

different from what the kernel remembers, then the treatment is what

Specification and Internals for the New UHCI Driver (Whitepaper...)

	brought to you by

	Georg Acher, acher@in.tum.de (executive slave) (base guitar)

	Deti Fliegl, deti@fliegl.de (executive slave) (lead voice)

	Thomas Sailer, sailer@ife.ee.ethz.ch (chief consultant) (cheer leader)

	$Id: README.uhci,v 1.1 1999/12/14 14:03:02 fliegl Exp $

This document and the new uhci sources can be found on

		http://hotswap.in.tum.de/usb

1. General issues

1.1 Why a new UHCI driver, we already have one?!?

Correct, but its internal structure got more and more mixed up by the (still

ongoing) efforts to get isochronous transfers (ISO) to work.

Since there is an increasing need for reliable ISO-transfers (especially 

for USB-audio needed by TS and for a DAB-USB-Receiver build by GA and DF), 

this state was a bit unsatisfying in our opinion, so we've decided (based

on knowledge and experiences with the old UHCI driver) to start 

from scratch with a new approach, much simpler but at the same time more 

powerful.

It is inspired by the way Win98/Win2000 handles USB requests via URBs,

but it's definitely 100% free of MS-code and doesn't crash while 

unplugging an used ISO-device like Win98 ;-)

Some code for HW setup and root hub management was taken from the 

original UHCI driver, but heavily modified to fit into the new code.

The invention of the basic concept, and major coding were completed in two 

days (and nights) on the 16th and 17th of October 1999, now known as the

great USB-October-Revolution started by GA, DF, and TS ;-)

Since the concept is in no way UHCI dependent, we hope that it will also be 

transferred to the OHCI-driver, so both drivers share a common API.

1.2. Advantages and disadvantages

+ All USB transfer types work now!

+ Asynchronous operation

+ Simple, but powerful interface (only two calls for start and cancel)

+ Easy migration to the new API, simplified by a compatibility API

+ Simple usage of ISO transfers

+ Automatic linking of requests

+ ISO transfers allow variable length for each frame and striping

+ No CPU dependent and non-portable atomic memory access, no asm()-inlines

+ Tested on x86 and Alpha

- Rewriting for ISO transfers needed

1.3. Is there some compatibility to the old API?

Yes, but only for control, bulk and interrupt transfers. We've implemented 

some wrapper calls for these transfer types. The usbcore works fine with 

these wrappers. For ISO there's no compatibility, because the old ISO-API 

and its semantics were unnecessary complicated in our opinion.

1.4. What's really working?

As said above, CTRL and BULK already work fine even with the wrappers,

so legacy code wouldn't notice the change.

Regarding to Thomas, ISO transfers now run stable with USB audio.

INT transfers (e.g. mouse driver) work fine, too.

1.5. Are there any bugs?

No ;-)

Hm...

Well, of course this implementation needs extensive testing on all available

hardware, but we believe that any fixes shouldn't harm the overall concept.

1.6. What should be done next?

A large part of the request handling seems to be identical for UHCI and 

OHCI, so it would be a good idea to extract the common parts and have only 

the HW specific stuff in uhci.c. Furthermore, all other USB device drivers

should need URBification, if they use isochronous or interrupt transfers.

One thing missing in the current implementation (and the old UHCI driver) 

is fair queueing for BULK transfers. Since this would need (in principle) 

the alteration of already constructed TD chains (to switch from depth to 

breadth execution), another way has to be found. Maybe some simple 

heuristics work with the same effect.

---------------------------------------------------------------------------

2. Internal structure and mechanisms

To get quickly familiar with the internal structures, here's a short

description how the new UHCI driver works. However, the ultimate source of

truth is only uhci.c!

2.1. Descriptor structure (QHs and TDs)

During initialization, the following skeleton is allocated in init_skel:

	 framespecific           |           common chain     

framelist[]

[  0 ]-----> TD --> TD -------\

[  1 ]-----> TD --> TD --------> TD ----> QH -------> QH -------> QH ---> NULL

  ...        TD --> TD -------/

[1023]-----> TD --> TD ------/

	     ^^     ^^           ^^       ^^          ^^          ^^

   1024 TDs for   7 TDs for    1 TD for   Start of    Start of    End Chain

	    ISO  INT (2-128ms) 1ms-INT    CTRL Chain  BULK Chain

For each CTRL or BULK transfer a new QH is allocated and the containing data

transfers are appended as (vertical) TDs. After building the whole QH with its

dangling TDs, the QH is inserted before the BULK Chain QH (for CTRL) or

before the End Chain QH (for BULK). Since only the QH->next pointers are

affected, no atomic memory operation is required. The three QHs in the

common chain are never equipped with TDs!

For ISO or INT, the TD for each frame is simply inserted into the appropriate

ISO/INT-TD-chain for the desired frame. The 7 skeleton INT-TDs are scattered

among the 1024 frames similar to the old UHCI driver.

For CTRL/BULK/ISO, the last TD in the transfer has the IOC-bit set. For INT,

every TD (there is only one...) has the IOC-bit set.

Besides the data for the UHCI controller (2 or 4 32bit words), the descriptors

are double-linked through the .vertical and .horizontal elements in the 

SW data of the descriptor (using the double-linked list structures and 

operations), but SW-linking occurs only in closed domains, i.e. for each of

the 1024 ISO-chains and the 8 INT-chains there is a closed cycle. This 

simplifies all insertions and unlinking operations and avoids costly 

bus_to_virt()-calls.

2.2. URB structure and linking to QH/TDs

During assembly of the QH and TDs of the requested action, these descriptors

are stored in urb->urb_list, so the allocated QH/TD descriptors are bound to

this URB.

If the assembly was successful and the descriptors were added to the HW chain,

the corresponding URB is inserted into a global URB list for this controller.

This list stores all pending URBs.

2.3. Interrupt processing

Since UHCI provides no means to directly detect completed transactions, the

following is done in each UHCI interrupt (uhci_interrupt()):

For each URB in the pending queue (process_urb()), the ACTIVE-flag of the 

associated TDs are processed (depending on the transfer type 

process_{transfer|interrupt|iso}()). If the TDs are not active anymore, 

they indicate the completion of the transaction and the status is calculated. 

Inactive QH/TDs are removed from the HW chain (since the host controller

already removed the TDs from the QH, no atomic access is needed) and 

eventually the URB is marked as completed (OK or errors) and removed from the 

pending queue. Then the next linked URB is submitted. After (or immediately 

before) that, the completion handler is called.

2.4. Unlinking URBs

First, all QH/TDs stored in the URB are unlinked from the HW chain. 

To ensure that the host controller really left a vertical TD chain, we 

wait for one frame. After that, the TDs are physically destroyed.

2.5. URB linking and the consequences

Since URBs can be linked and the corresponding submit_urb is called in

the UHCI-interrupt, all work associated with URB/QH/TD assembly has to be

interrupt save. This forces kmalloc to use GFP_ATOMIC in the interrupt.

		dev_dbg(&usbhid->intf->dev, "resetting device\n");

		rc = rc_lock = usb_lock_device_for_reset(hid_to_usb_dev(hid), usbhid->intf);

		if (rc_lock >= 0) {

			rc = usb_reset_composite_device(hid_to_usb_dev(hid), usbhid->intf);

			rc = usb_reset_device(hid_to_usb_dev(hid));

			if (rc_lock)

				usb_unlock_device(hid_to_usb_dev(hid));

		}