docs-rst: convert usb docbooks to ReST

As we're moving out of DocBook, let's convert the remaining
USB docbooks to ReST.

The transformation itself on this patch is a no-brainer
conversion using pandoc via this script:
	Documentation/sphinx/tmplcvt

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

1 files changed, 0 insertions, 793 deletions

diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl
deleted file mode 100644
index 641629221176..000000000000
--- a/Documentation/DocBook/gadget.tmpl
+++ /dev/null
@@ -1,793 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="USB-Gadget-API">
-  <bookinfo>
-    <title>USB Gadget API for Linux</title>
-    <date>20 August 2004</date>
-    <edition>20 August 2004</edition>
-  
-    <legalnotice>
-       <para>
-	 This documentation is free software; you can redistribute
-	 it and/or modify it under the terms of the GNU General Public
-	 License as published by the Free Software Foundation; either
-	 version 2 of the License, or (at your option) any later
-	 version.
-       </para>
-	  
-       <para>
-	 This program is distributed in the hope that it will be
-	 useful, but WITHOUT ANY WARRANTY; without even the implied
-	 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-	 See the GNU General Public License for more details.
-       </para>
-	  
-       <para>
-	 You should have received a copy of the GNU General Public
-	 License along with this program; if not, write to the Free
-	 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-	 MA 02111-1307 USA
-       </para>
-	  
-       <para>
-	 For more details see the file COPYING in the source
-	 distribution of Linux.
-       </para>
-    </legalnotice>
-    <copyright>
-      <year>2003-2004</year>
-      <holder>David Brownell</holder>
-    </copyright>
-
-    <author>
-      <firstname>David</firstname> 
-      <surname>Brownell</surname>
-      <affiliation>
-        <address><email>dbrownell@users.sourceforge.net</email></address>
-      </affiliation>
-    </author>
-  </bookinfo>
-
-<toc></toc>
-
-<chapter id="intro"><title>Introduction</title>
-
-<para>This document presents a Linux-USB "Gadget"
-kernel mode
-API, for use within peripherals and other USB devices
-that embed Linux.
-It provides an overview of the API structure,
-and shows how that fits into a system development project.
-This is the first such API released on Linux to address
-a number of important problems, including: </para>
-
-<itemizedlist>
-    <listitem><para>Supports USB 2.0, for high speed devices which
-	can stream data at several dozen megabytes per second.
-	</para></listitem>
-    <listitem><para>Handles devices with dozens of endpoints just as
-	well as ones with just two fixed-function ones.  Gadget drivers
-	can be written so they're easy to port to new hardware.
-	</para></listitem>
-    <listitem><para>Flexible enough to expose more complex USB device
-	capabilities such as multiple configurations, multiple interfaces,
-	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 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
-	demands for memory or CPU resources.
-	</para></listitem>
-</itemizedlist>
-
-
-<para>Most Linux developers will not be able to use this API, since they
-have USB "host" hardware in a PC, workstation, or server.
-Linux users with embedded systems are more likely to
-have USB peripheral hardware.
-To distinguish drivers running inside such hardware from the
-more familiar Linux "USB device drivers",
-which are host side proxies for the real USB devices,
-a different term is used:
-the drivers inside the peripherals are "USB gadget drivers".
-In USB protocol interactions, the device driver is the master
-(or "client driver")
-and the gadget driver is the slave (or "function driver").
-</para>
-
-<para>The gadget API resembles the host side Linux-USB API in that both
-use queues of request objects to package I/O buffers, and those requests
-may be submitted or canceled.
-They share common definitions for the standard USB
-<emphasis>Chapter 9</emphasis> messages, structures, and constants.
-Also, both APIs bind and unbind drivers to devices.
-The APIs differ in detail, since the host side's current
-URB framework exposes a number of implementation details
-and assumptions that are inappropriate for a gadget API.
-While the model for control transfers and configuration
-management is necessarily different (one side is a hardware-neutral master,
-the other is a hardware-aware slave), the endpoint I/0 API used here
-should also be usable for an overhead-reduced host side API.
-</para>
-
-</chapter>
-
-<chapter id="structure"><title>Structure of Gadget Drivers</title>
-
-<para>A system running inside a USB peripheral
-normally has at least three layers inside the kernel to handle
-USB protocol processing, and may have additional layers in
-user space code.
-The "gadget" API is used by the middle layer to interact
-with the lowest level (which directly handles hardware).
-</para>
-
-<para>In Linux, from the bottom up, these layers are:
-</para>
-
-<variablelist>
-
-    <varlistentry>
-        <term><emphasis>USB Controller Driver</emphasis></term>
-
-	<listitem>
-	<para>This is the lowest software level.
-	It is the only layer that talks to hardware,
-	through registers, fifos, dma, irqs, and the like.
-	The <filename>&lt;linux/usb/gadget.h&gt;</filename> API abstracts
-	the peripheral controller endpoint hardware.
-	That hardware is exposed through endpoint objects, which accept
-	streams of IN/OUT buffers, and through callbacks that interact
-	with gadget drivers.
-	Since normal USB devices only have one upstream
-	port, they only have one of these drivers.
-	The controller driver can support any number of different
-	gadget drivers, but only one of them can be used at a time.
-	</para>
-
-	<para>Examples of such controller hardware include
-	the PCI-based NetChip 2280 USB 2.0 high speed controller,
-	the SA-11x0 or PXA-25x UDC (found within many PDAs),
-	and a variety of other products.
-	</para>
-
-	</listitem></varlistentry>
-
-    <varlistentry>
-	<term><emphasis>Gadget Driver</emphasis></term>
-
-	<listitem>
-	<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,
-	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>
-	    <listitem><para>handling setup requests (ep0 protocol responses)
-		possibly including class-specific functionality
-		</para></listitem>
-	    <listitem><para>returning configuration and string descriptors
-		</para></listitem>
-	    <listitem><para>(re)setting configurations and interface
-		altsettings, including enabling and configuring endpoints
-		</para></listitem>
-	    <listitem><para>handling life cycle events, such as managing
-		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
-		</para></listitem>
-	</itemizedlist>
-
-	<para>
-	Such drivers may be modules of proprietary code, although
-	that approach is discouraged in the Linux community.
-	</para>
-	</listitem></varlistentry>
-
-    <varlistentry>
-	<term><emphasis>Upper Level</emphasis></term>
-
-	<listitem>
-	<para>Most gadget drivers have an upper boundary that connects
-	to some Linux driver or framework in Linux.
-	Through that boundary flows the data which the gadget driver
-	produces and/or consumes through protocol transfers over USB.
-	Examples include:
-	</para>
-	<itemizedlist>
-	    <listitem><para>user mode code, using generic (gadgetfs)
-	        or application specific files in
-		<filename>/dev</filename>
-		</para></listitem>
-	    <listitem><para>networking subsystem (for network gadgets,
-		like the CDC Ethernet Model gadget driver)
-		</para></listitem>
-	    <listitem><para>data capture drivers, perhaps video4Linux or
-		 a scanner driver; or test and measurement hardware.
-		 </para></listitem>
-	    <listitem><para>input subsystem (for HID gadgets)
-		</para></listitem>
-	    <listitem><para>sound subsystem (for audio gadgets)
-		</para></listitem>
-	    <listitem><para>file system (for PTP gadgets)
-		</para></listitem>
-	    <listitem><para>block i/o subsystem (for usb-storage gadgets)
-		</para></listitem>
-	    <listitem><para>... and more </para></listitem>
-	</itemizedlist>
-	</listitem></varlistentry>
-
-    <varlistentry>
-	<term><emphasis>Additional Layers</emphasis></term>
-
-	<listitem>
-	<para>Other layers may exist.
-	These could include kernel layers, such as network protocol stacks,
-	as well as user mode applications building on standard POSIX
-	system call APIs such as
-	<emphasis>open()</emphasis>, <emphasis>close()</emphasis>,
-	<emphasis>read()</emphasis> and <emphasis>write()</emphasis>.
-	On newer systems, POSIX Async I/O calls may be an option.
-	Such user mode code will not necessarily be subject to
-	the GNU General Public License (GPL).
-	</para>
-	</listitem></varlistentry>
-
-
-</variablelist>
-
-<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 gadget-side interface drivers should eventually be combined,
-to implement composite devices.
-</para>
-
-</chapter>
-
-
-<chapter id="api"><title>Kernel Mode Gadget API</title>
-
-<para>Gadget drivers declare themselves through a
-<emphasis>struct usb_gadget_driver</emphasis>, which is responsible for
-most parts of enumeration for a <emphasis>struct usb_gadget</emphasis>.
-The response to a set_configuration usually involves
-enabling one or more of the <emphasis>struct usb_ep</emphasis> objects
-exposed by the gadget, and submitting one or more
-<emphasis>struct usb_request</emphasis> buffers to transfer data.
-Understand those four data types, and their operations, and
-you will understand how this API works.
-</para> 
-
-<note><title>Incomplete Data Type Descriptions</title>
-
-<para>This documentation was prepared using the standard Linux
-kernel <filename>docproc</filename> tool, which turns text
-and in-code comments into SGML DocBook and then into usable
-formats such as HTML or PDF.
-Other than the "Chapter 9" data types, most of the significant
-data types and functions are described here.
-</para>
-
-<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 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>
-
-<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.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.)
-The driver model state is another part of this API that is
-ignored by the kerneldoc tools.
-</para>
-</note>
-
-<para>The core API does not expose
-every possible hardware feature, only the most widely available ones.
-There are significant hardware features, such as device-to-device DMA
-(without temporary storage in a memory buffer)
-that would be added using hardware-specific APIs.
-</para>
-
-<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 supports limited run-time
-detection of capabilities, through naming conventions for endpoints.
-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
-the "chunky" nature of USB messages:  I/O requests are in terms
-of one or more "packets", and packet boundaries are visible to drivers.
-Compared to RS-232 serial protocols, USB resembles
-synchronous protocols like HDLC
-(N bytes per frame, multipoint addressing, host as the primary
-station and devices as secondary stations)
-more than asynchronous ones
-(tty style:  8 data bits per frame, no parity, one stop bit).
-So for example the controller drivers won't buffer
-two single byte writes into a single two-byte USB IN packet,
-although gadget drivers may do so when they implement
-protocols where packet boundaries (and "short packets")
-are not significant.
-</para>
-
-<sect1 id="lifecycle"><title>Driver Life Cycle</title>
-
-<para>Gadget drivers make endpoint I/O requests to hardware without
-needing to know many details of the hardware, but driver
-setup/configuration code needs to handle some differences.
-Use the API like this:
-</para>
-
-<orderedlist numeration='arabic'>
-
-<listitem><para>Register a driver for the particular device side
-usb controller hardware,
-such as the net2280 on PCI (USB 2.0),
-sa11x0 or pxa25x as found in Linux PDAs,
-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, which
-activates the data line pullup sometime after detecting VBUS.
-</para></listitem>
-
-<listitem><para>The hardware driver can now start enumerating.
-The steps it handles are to accept USB power and set_address requests.
-Other steps are handled by the gadget driver.
-If the gadget driver module is unloaded before the host starts to
-enumerate, steps before step 7 are skipped.
-</para></listitem>
-
-<listitem><para>The gadget driver's setup() call returns usb descriptors,
-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,
-when the USB host issues a set_configuration call.
-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.
-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,
-the driver unbind() callback is issued.  That lets the controller
-driver be unloaded.
-</para></listitem>
-
-</orderedlist>
-
-<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, 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.
-Such issues are in the domain of gadget drivers,
-including knowing about implementation constraints
-imposed by some USB controllers
-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>
-
-<para>Gadget drivers
-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.6 kernels.
-These are the same types and constants used by host
-side drivers (and usbcore).
-</para>
-
-!Iinclude/linux/usb/ch9.h
-</sect1>
-
-<sect1 id="core"><title>Core Objects and Methods</title>
-
-<para>These are declared in
-<filename>&lt;linux/usb/gadget.h&gt;</filename>,
-and are used by gadget drivers to interact with
-USB peripheral controller drivers.
-</para>
-
-	<!-- yeech, this is ugly in nsgmls PDF output.
-
-	     the PDF bookmark and refentry output nesting is wrong,
-	     and the member/argument documentation indents ugly.
-
-	     plus something (docproc?) adds whitespace before the
-	     descriptive paragraph text, so it can't line up right
-	     unless the explanations are trivial.
-	  -->
-
-!Iinclude/linux/usb/gadget.h
-</sect1>
-
-<sect1 id="utils"><title>Optional Utilities</title>
-
-<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>
-
-<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/function/f_acm.c
-!Edrivers/usb/gadget/function/f_ecm.c
-!Edrivers/usb/gadget/function/f_subset.c
-!Edrivers/usb/gadget/function/f_obex.c
-!Edrivers/usb/gadget/function/f_serial.c
-
-</sect1>
-
-
-</chapter>
-
-<chapter id="controllers"><title>Peripheral Controller Drivers</title>
-
-<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.6;
-contact NetChip Technologies for development boards and product
-information.
-</para> 
-
-<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
-this framework for several other USB device controllers,
-with plans to make many of them be widely available.
-</para>
-
-<!-- !Edrivers/usb/gadget/net2280.c -->
-
-<para>A partial USB simulator,
-the <filename>dummy_hcd</filename> driver, is available.
-It can act like a net2280, a pxa25x, or an sa11x0 in terms
-of available endpoints and device speeds; and it simulates
-control, bulk, and to some extent interrupt transfers.
-That lets you develop some parts of a gadget driver on a normal PC,
-without any special hardware, and perhaps with the assistance
-of tools such as GDB running with User Mode Linux.
-At least one person has expressed interest in adapting that
-approach, hooking it up to a simulator for a microcontroller.
-Such simulators can help debug subsystems where the runtime hardware
-is unfriendly to software development, or is not yet available.
-</para>
-
-<para>Support for other controllers is expected to be developed
-and contributed
-over time, as this driver framework evolves.
-</para>
-
-</chapter>
-
-<chapter id="gadget"><title>Gadget Drivers</title>
-
-<para>In addition to <emphasis>Gadget Zero</emphasis>
-(used primarily for testing and development with drivers
-for usb controller hardware), other gadget drivers exist.
-</para>
-
-<para>There's an <emphasis>ethernet</emphasis> gadget
-driver, which implements one of the most useful
-<emphasis>Communications Device Class</emphasis> (CDC) models.  
-One of the standards for cable modem interoperability even
-specifies the use of this ethernet model as one of two
-mandatory options.
-Gadgets using this code look to a USB host as if they're
-an Ethernet adapter.
-It provides access to a network where the gadget's CPU is one host,
-which could easily be bridging, routing, or firewalling
-access to other networks.
-Since some hardware can't fully implement the CDC Ethernet
-requirements, this driver also implements a "good parts only"
-subset of CDC Ethernet.
-(That subset doesn't advertise itself as 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
-each endpoint as a single file descriptor.  I/O is done using
-normal <emphasis>read()</emphasis> and <emphasis>read()</emphasis> calls.
-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
-a different solution for interoperability with systems such
-as MS-Windows and MacOS.
-That <emphasis>Mass Storage</emphasis> driver uses a
-file or block device as backing store for a drive,
-like the <filename>loop</filename> driver.
-The USB host uses the BBB, CB, or CBI versions of the mass
-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.
-</para>
-
-</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 transceiver 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>
-<!--
-	vim:syntax=sgml:sw=4
--->