[PATCH] USB OTG: doc updates (5/5)

Gadget API update.  Covers OTG support, lists a few more
types of hardware support, mentions gadget driver updates
including RNDIS, serial with CDC-ACM, and gadgetfs AIO.
Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: Greg Kroah-Hartman <greg@kroah.com>

Documentation/DocBook/gadget.tmpl

@@ -2,8 +2,8 @@
 <book id="USB-Gadget-API">
   <bookinfo>
     <title>USB Gadget API for Linux</title>
-    <date>02 June 2003</date>
-    <edition>02 June 2003</edition>
+    <date>20 August 2004</date>
+    <edition>20 August 2004</edition>
   
     <legalnotice>
        <para>
@@ -34,7 +34,7 @@
        </para>
     </legalnotice>
     <copyright>
-      <year>2003</year>
+      <year>2003-2004</year>
       <holder>David Brownell</holder>
     </copyright>
 
@@ -73,9 +73,13 @@ a number of important problems, including: </para>
 	composite devices,
 	and alternate interface settings.
 	</para></listitem>
+    <listitem><para>USB "On-The-Go" (OTG) support, in conjunction
+	with updates to the Linux-USB host side.
+	</para></listitem>
     <listitem><para>Sharing data structures and API models with the
-	Linux-USB host side API.  This looks forward to USB "On-The-Go"
-	(OTG) and similar more-symmetric frameworks.
+	Linux-USB host side API.  This helps the OTG support, and
+	looks forward to more-symmetric frameworks (where the same
+	I/O model is used by both host and device side drivers).
 	</para></listitem>
     <listitem><para>Minimalist, so it's easier to support new device
 	controller hardware.  I/O processing doesn't imply large
@@ -153,6 +157,7 @@ with the lowest level (which directly handles hardware).
 	the SA-11x0 or PXA-25x UDC (found within many PDAs),
 	and a variety of other products.
 	</para>
+
 	</listitem></varlistentry>
 
     <varlistentry>
@@ -162,10 +167,14 @@ with the lowest level (which directly handles hardware).
 	<para>The lower boundary of this driver implements hardware-neutral
 	USB functions, using calls to the controller driver.
 	Because such hardware varies widely in capabilities and restrictions,
-	the gadget driver is normally configured at compile time
+	and is used in embedded environments where space is at a premium,
+	the gadget driver is often configured at compile time
 	to work with endpoints supported by one particular controller.
 	Gadget drivers may be portable to several different controllers,
 	using conditional compilation.
+	(Recent kernels substantially simplify the work involved in
+	supporting new hardware, by <emphasis>autoconfiguring</emphasis>
+	endpoints automatically for many bulk-oriented drivers.)
 	Gadget driver responsibilities include:
 	</para>
 	<itemizedlist>
@@ -178,8 +187,9 @@ with the lowest level (which directly handles hardware).
 		altsettings, including enabling and configuring endpoints
 		</para></listitem>
 	    <listitem><para>handling life cycle events, such as managing
-		bindings
-	        to hardware, and disconnection from the USB host.
+		bindings to hardware,
+		USB suspend/resume, remote wakeup,
+		and disconnection from the USB host.
 		</para></listitem>
 	    <listitem><para>managing IN and OUT transfers on all currently
 		enabled endpoints
@@ -244,15 +254,38 @@ with the lowest level (which directly handles hardware).
 
 </variablelist>
 
-<para>Over time, reusable utilities should evolve to help make some
-gadget driver tasks simpler.  An example of particular interest
+<para>OTG-capable systems will also need to include a standard Linux-USB
+host side stack,
+with <emphasis>usbcore</emphasis>,
+one or more <emphasis>Host Controller Drivers</emphasis> (HCDs),
+<emphasis>USB Device Drivers</emphasis> to support
+the OTG "Targeted Peripheral List",
+and so forth.
+There will also be an <emphasis>OTG Controller Driver</emphasis>,
+which is visible to gadget and device driver developers only indirectly.
+That helps the host and device side USB controllers implement the
+two new OTG protocols (HNP and SRP).
+Roles switch (host to peripheral, or vice versa) using HNP
+during USB suspend processing, and SRP can be viewed as a
+more battery-friendly kind of device wakeup protocol.
+</para>
+
+<para>Over time, reusable utilities are evolving to help make some
+gadget driver tasks simpler.
+For example, building configuration descriptors from vectors of
+descriptors for the configurations interfaces and endpoints is
+now automated, and many drivers now use autoconfiguration to
+choose hardware endpoints and initialize their descriptors.
+
+A potential example of particular interest
 is code implementing standard USB-IF protocols for
 HID, networking, storage, or audio classes.
 Some developers are interested in KDB or KGDB hooks, to let
 target hardware be remotely debugged.
 Most such USB protocol code doesn't need to be hardware-specific,
 any more than network protocols like X11, HTTP, or NFS are.
-Such interface drivers might be combined, to support composite devices.
+Such gadget-side interface drivers should eventually be combined,
+to implement composite devices.
 </para>
 
 </chapter>
@@ -284,7 +317,7 @@ data types and functions are described here.
 <para>However, docproc does not understand all the C constructs
 that are used, so some relevant information is likely omitted from
 what you are reading.  
-One example of such information is several per-request flags.
+One example of such information is endpoint autoconfiguration.
 You'll have to read the header file, and use example source
 code (such as that for "Gadget Zero"), to fully understand the API.
 </para>
@@ -292,7 +325,7 @@ code (such as that for "Gadget Zero"), to fully understand the API.
 <para>The part of the API implementing some basic
 driver capabilities is specific to the version of the
 Linux kernel that's in use.
-The 2.5 kernel includes a <emphasis>driver model</emphasis>
+The 2.6 kernel includes a <emphasis>driver model</emphasis>
 framework that has no analogue on earlier kernels;
 so those parts of the gadget API are not fully portable.
 (They are implemented on 2.4 kernels, but in a different way.)
@@ -308,17 +341,21 @@ There are significant hardware features, such as device-to-device DMA
 that would be added using hardware-specific APIs.
 </para>
 
-<para>This API expects drivers to use conditional compilation to handle
-endpoint capabilities of different hardware.
-Those tend to have arbitrary restrictions, relating to
+<para>This API allows drivers to use conditional compilation to handle
+endpoint capabilities of different hardware, but doesn't require that.
+Hardware tends to have arbitrary restrictions, relating to
 transfer types, addressing, packet sizes, buffering, and availability.
 As a rule, such differences only matter for "endpoint zero" logic
 that handles device configuration and management.
-The API only supports limited run-time
+The API supports limited run-time
 detection of capabilities, through naming conventions for endpoints.
-Although a gadget driver could scan the endpoints available to it and
-choose to map those capabilities onto driver functionality in some way,
-few drivers will want to reconfigure themselves at run-time.
+Many drivers will be able to at least partially autoconfigure
+themselves.
+In particular, driver init sections will often have endpoint
+autoconfiguration logic that scans the hardware's list of endpoints
+to find ones matching the driver requirements
+(relying on those conventions), to eliminate some of the most
+common reasons for conditional compilation.
 </para>
 
 <para>Like the Linux-USB host side API, this API exposes
@@ -355,10 +392,14 @@ and so on.
 At this point the device is logically in the USB ch9 initial state
 ("attached"), drawing no power and not usable
 (since it does not yet support enumeration).
+Any host should not see the device, since it's not
+activated the data line pullup used by the host to
+detect a device, even if VBUS power is available.
 </para></listitem>
 
 <listitem><para>Register a gadget driver that implements some higher level
-device function.  That will then bind() to a usb_gadget.
+device function.  That will then bind() to a usb_gadget, which
+activates the data line pullup sometime after detecting VBUS.
 </para></listitem>
 
 <listitem><para>The hardware driver can now start enumerating.
@@ -373,6 +414,8 @@ based both on what the bus interface hardware provides and on the
 functionality being implemented.
 That can involve alternate settings or configurations,
 unless the hardware prevents such operation.
+For OTG devices, each configuration descriptor includes
+an OTG descriptor.
 </para></listitem>
 
 <listitem><para>The gadget driver handles the last step of enumeration,
@@ -381,13 +424,18 @@ It enables all endpoints used in that configuration,
 with all interfaces in their default settings.
 That involves using a list of the hardware's endpoints, enabling each
 endpoint according to its descriptor.
+It may also involve using <function>usb_gadget_vbus_draw</function>
+to let more power be drawn from VBUS, as allowed by that configuration.
+For OTG devices, setting a configuration may also involve reporting
+HNP capabilities through a user interface.
 </para></listitem>
 
 <listitem><para>Do real work and perform data transfers, possibly involving
 changes to interface settings or switching to new configurations, until the
 device is disconnect()ed from the host.
 Queue any number of transfer requests to each endpoint.
-The drivers then go back to step 3 (above).
+It may be suspended and resumed several times before being disconnected.
+On disconnect, the drivers go back to step 3 (above).
 </para></listitem>
 
 <listitem><para>When the gadget driver module is being unloaded,
@@ -399,7 +447,9 @@ driver be unloaded.
 
 <para>Drivers will normally be arranged so that just loading the
 gadget driver module (or statically linking it into a Linux kernel)
-allows the peripheral device to be enumerated.
+allows the peripheral device to be enumerated, but some drivers
+will defer enumeration until some higher level component (like
+a user mode daemon) enables it.
 Note that at this lowest level there are no policies about how
 ep0 configuration logic is implemented,
 except that it should obey USB specifications.
@@ -410,6 +460,18 @@ or understanding that composite devices might happen to
 be built by integrating reusable components.
 </para>
 
+<para>Note that the lifecycle above can be slightly different
+for OTG devices.
+Other than providing an additional OTG descriptor in each
+configuration, only the HNP-related differences are particularly
+visible to driver code.
+They involve reporting requirements during the SET_CONFIGURATION
+request, and the option to invoke HNP during some suspend callbacks.
+Also, SRP changes the semantics of
+<function>usb_gadget_wakeup</function>
+slightly.
+</para>
+
 </sect1>
 
 <sect1 id="ch9"><title>USB 2.0 Chapter 9 Types and Constants</title>
@@ -418,9 +480,9 @@ be built by integrating reusable components.
 rely on common USB structures and constants
 defined in the
 <filename>&lt;linux/usb_ch9.h&gt;</filename>
-header file, which is standard in Linux 2.5 kernels.
+header file, which is standard in Linux 2.6 kernels.
 These are the same types and constants used by host
-side drivers.
+side drivers (and usbcore).
 </para>
 
 !Iinclude/linux/usb_ch9.h
@@ -451,26 +513,38 @@ USB peripheral controller drivers.
 
 <para>The core API is sufficient for writing a USB Gadget Driver,
 but some optional utilities are provided to simplify common tasks.
+These utilities include endpoint autoconfiguration.
 </para>
 
 !Edrivers/usb/gadget/usbstring.c
 !Edrivers/usb/gadget/config.c
+<!-- !Edrivers/usb/gadget/epautoconf.c -->
 </sect1>
 
 </chapter>
 
 <chapter id="controllers"><title>Peripheral Controller Drivers</title>
 
-<para>The first hardware supporting this API is the NetChip 2280
+<para>The first hardware supporting this API was the NetChip 2280
 controller, which supports USB 2.0 high speed and is based on PCI.
 This is the <filename>net2280</filename> driver module.
-The driver supports Linux kernel versions 2.4 and 2.5;
+The driver supports Linux kernel versions 2.4 and 2.6;
 contact NetChip Technologies for development boards and product
 information.
 </para> 
 
-<para>For users of Intel's PXA 2xx series processors,
-a <filename>pxa2xx_udc</filename> driver is available.
+<para>Other hardware working in the "gadget" framework includes:
+Intel's PXA 25x and IXP42x series processors
+(<filename>pxa2xx_udc</filename>),
+Toshiba TC86c001 "Goku-S" (<filename>goku_udc</filename>),
+Renesas SH7705/7727 (<filename>sh_udc</filename>),
+MediaQ 11xx (<filename>mq11xx_udc</filename>),
+Hynix HMS30C7202 (<filename>h7202_udc</filename>),
+National 9303/4 (<filename>n9604_udc</filename>),
+Texas Instruments OMAP (<filename>omap_udc</filename>),
+Sharp LH7A40x (<filename>lh7a40x_udc</filename>),
+and more.
+Most of those are full speed controllers.
 </para>
 
 <para>At this writing, there are people at work on drivers in
@@ -526,6 +600,15 @@ subset of CDC Ethernet.
 to avoid creating problems.)
 </para>
 
+<para>Support for Microsoft's <emphasis>RNDIS</emphasis>
+protocol has been contributed by Pengutronix and Auerswald GmbH.
+This is like CDC Ethernet, but it runs on more slightly USB hardware
+(but less than the CDC subset).
+However, its main claim to fame is being able to connect directly to
+recent versions of Windows, using drivers that Microsoft bundles
+and supports, making it much simpler to network with Windows.
+</para>
+
 <para>There is also support for user mode gadget drivers,
 using <emphasis>gadgetfs</emphasis>.
 This provides a <emphasis>User Mode API</emphasis> that presents
@@ -535,6 +618,10 @@ Familiar tools like GDB and pthreads can be used to
 develop and debug user mode drivers, so that once a robust
 controller driver is available many applications for it
 won't require new kernel mode software.
+Linux 2.6 <emphasis>Async I/O (AIO)</emphasis>
+support is available, so that user mode software
+can stream data with only slightly more overhead
+than a kernel driver.
 </para>
 
 <para>There's a USB Mass Storage class driver, which provides
@@ -548,6 +635,16 @@ storage class specification, using transparent SCSI commands
 to access the data from the backing store.
 </para>
 
+<para>There's a "serial line" driver, useful for TTY style
+operation over USB.
+The latest version of that driver supports CDC ACM style
+operation, like a USB modem, and so on most hardware it can
+interoperate easily with MS-Windows.
+One interesting use of that driver is in boot firmware (like a BIOS),
+which can sometimes use that model with very small systems without
+real serial lines.
+</para>
+
 <para>Support for other kinds of gadget is expected to
 be developed and contributed
 over time, as this driver framework evolves.
@@ -555,6 +652,96 @@ over time, as this driver framework evolves.
 
 </chapter>
 
+<chapter id="otg"><title>USB On-The-GO (OTG)</title>
+
+<para>USB OTG support on Linux 2.6 was initially developed
+by Texas Instruments for
+<ulink url="http://www.omap.com">OMAP</ulink> 16xx and 17xx
+series processors.
+Other OTG systems should work in similar ways, but the
+hardware level details could be very different.
+</para> 
+
+<para>Systems need specialized hardware support to implement OTG,
+notably including a special <emphasis>Mini-AB</emphasis> jack
+and associated transciever to support <emphasis>Dual-Role</emphasis>
+operation:
+they can act either as a host, using the standard
+Linux-USB host side driver stack,
+or as a peripheral, using this "gadget" framework.
+To do that, the system software relies on small additions
+to those programming interfaces,
+and on a new internal component (here called an "OTG Controller")
+affecting which driver stack connects to the OTG port.
+In each role, the system can re-use the existing pool of
+hardware-neutral drivers, layered on top of the controller
+driver interfaces (<emphasis>usb_bus</emphasis> or
+<emphasis>usb_gadget</emphasis>).
+Such drivers need at most minor changes, and most of the calls
+added to support OTG can also benefit non-OTG products.
+</para>
+
+<itemizedlist>
+    <listitem><para>Gadget drivers test the <emphasis>is_otg</emphasis>
+	flag, and use it to determine whether or not to include
+	an OTG descriptor in each of their configurations.
+	</para></listitem>
+    <listitem><para>Gadget drivers may need changes to support the
+	two new OTG protocols, exposed in new gadget attributes
+	such as <emphasis>b_hnp_enable</emphasis> flag.
+	HNP support should be reported through a user interface
+	(two LEDs could suffice), and is triggered in some cases
+	when the host suspends the peripheral.
+	SRP support can be user-initiated just like remote wakeup,
+	probably by pressing the same button.
+	</para></listitem>
+    <listitem><para>On the host side, USB device drivers need
+	to be taught to trigger HNP at appropriate moments, using
+	<function>usb_suspend_device()</function>.
+	That also conserves battery power, which is useful even
+	for non-OTG configurations.
+	</para></listitem>
+    <listitem><para>Also on the host side, a driver must support the
+	OTG "Targeted Peripheral List".  That's just a whitelist,
+	used to reject peripherals not supported with a given
+	Linux OTG host.
+	<emphasis>This whitelist is product-specific;
+	each product must modify <filename>otg_whitelist.h</filename>
+	to match its interoperability specification.
+	</emphasis>
+	</para>
+	<para>Non-OTG Linux hosts, like PCs and workstations,
+	normally have some solution for adding drivers, so that
+	peripherals that aren't recognized can eventually be supported.
+	That approach is unreasonable for consumer products that may
+	never have their firmware upgraded, and where it's usually
+	unrealistic to expect traditional PC/workstation/server kinds
+	of support model to work.
+	For example, it's often impractical to change device firmware
+	once the product has been distributed, so driver bugs can't
+	normally be fixed if they're found after shipment.
+	</para></listitem>
+</itemizedlist>
+
+<para>
+Additional changes are needed below those hardware-neutral
+<emphasis>usb_bus</emphasis> and <emphasis>usb_gadget</emphasis>
+driver interfaces; those aren't discussed here in any detail.
+Those affect the hardware-specific code for each USB Host or Peripheral
+controller, and how the HCD initializes (since OTG can be active only
+on a single port).
+They also involve what may be called an <emphasis>OTG Controller
+Driver</emphasis>, managing the OTG transceiver and the OTG state
+machine logic as well as much of the root hub behavior for the
+OTG port.
+The OTG controller driver needs to activate and deactivate USB
+controllers depending on the relevant device role.
+Some related changes were needed inside usbcore, so that it
+can identify OTG-capable devices and respond appropriately
+to HNP or SRP protocols.
+</para> 
+
+</chapter>
 
 </book>
 <!--

include/linux/usb_gadget.h

@@ -767,12 +767,6 @@ usb_gadget_disconnect (struct usb_gadget *gadget)
  * the (remote) host can't do that any longer; or an error state might
  * be cleared, to make the device behave identically whether or not
  * power is maintained.
- *
- * If the OTG b_hnp_enabled flag is set during a suspend() call, the
- * device may use HNP to switch from "B-Peripheral" to "B-Host" mode
- * (or back from "A-Peripheral" mode to the original "A-Host") if
- * the gadget driver calls usb_gadget_disconnect() before the device
- * is resumed.
  */
 struct usb_gadget_driver {
 	char			*function;