[PATCH v2 03/22] docs-rst: convert usb docbooks to ReST

Mauro Carvalho Chehab mchehab at s-opensource.com
Thu Mar 30 03:45:37 PDT 2017


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 at s-opensource.com>
---
 Documentation/DocBook/Makefile                     |   7 +-
 Documentation/DocBook/gadget.tmpl                  | 793 -------------------
 Documentation/DocBook/writing_musb_glue_layer.tmpl | 873 ---------------------
 Documentation/DocBook/writing_usb_driver.tmpl      | 412 ----------
 Documentation/driver-api/index.rst                 |   2 +-
 Documentation/driver-api/usb/gadget.rst            | 533 +++++++++++++
 Documentation/driver-api/usb/index.rst             |  17 +
 Documentation/driver-api/{ => usb}/usb.rst         | 168 ++--
 .../driver-api/usb/writing_musb_glue_layer.rst     | 737 +++++++++++++++++
 .../driver-api/usb/writing_usb_driver.rst          | 344 ++++++++
 10 files changed, 1719 insertions(+), 2167 deletions(-)
 delete mode 100644 Documentation/DocBook/gadget.tmpl
 delete mode 100644 Documentation/DocBook/writing_musb_glue_layer.tmpl
 delete mode 100644 Documentation/DocBook/writing_usb_driver.tmpl
 create mode 100644 Documentation/driver-api/usb/gadget.rst
 create mode 100644 Documentation/driver-api/usb/index.rst
 rename Documentation/driver-api/{ => usb}/usb.rst (87%)
 create mode 100644 Documentation/driver-api/usb/writing_musb_glue_layer.rst
 create mode 100644 Documentation/driver-api/usb/writing_usb_driver.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 164c1c76971f..7d94db2b53cd 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -8,12 +8,11 @@
 
 DOCBOOKS := z8530book.xml  \
 	    kernel-hacking.xml kernel-locking.xml \
-	    writing_usb_driver.xml networking.xml \
+	    networking.xml \
 	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
-	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
+	    libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    genericirq.xml s390-drivers.xml scsi.xml \
-	    sh.xml w1.xml \
-	    writing_musb_glue_layer.xml
+	    sh.xml w1.xml
 
 ifeq ($(DOCBOOKS),)
 
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 at 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><linux/usb/gadget.h></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><linux/usb/ch9.h></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><linux/usb/gadget.h></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
--->
diff --git a/Documentation/DocBook/writing_musb_glue_layer.tmpl b/Documentation/DocBook/writing_musb_glue_layer.tmpl
deleted file mode 100644
index 837eca77f274..000000000000
--- a/Documentation/DocBook/writing_musb_glue_layer.tmpl
+++ /dev/null
@@ -1,873 +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="Writing-MUSB-Glue-Layer">
- <bookinfo>
-  <title>Writing an MUSB Glue Layer</title>
-
-  <authorgroup>
-   <author>
-    <firstname>Apelete</firstname>
-    <surname>Seketeli</surname>
-    <affiliation>
-     <address>
-      <email>apelete at seketeli.net</email>
-     </address>
-    </affiliation>
-   </author>
-  </authorgroup>
-
-  <copyright>
-   <year>2014</year>
-   <holder>Apelete Seketeli</holder>
-  </copyright>
-
-  <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 documentation 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 documentation; 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 Linux kernel source
-     tree.
-   </para>
-  </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
-  <chapter id="introduction">
-    <title>Introduction</title>
-    <para>
-      The Linux MUSB subsystem is part of the larger Linux USB
-      subsystem. It provides support for embedded USB Device Controllers
-      (UDC) that do not use Universal Host Controller Interface (UHCI)
-      or Open Host Controller Interface (OHCI).
-    </para>
-    <para>
-      Instead, these embedded UDC rely on the USB On-the-Go (OTG)
-      specification which they implement at least partially. The silicon
-      reference design used in most cases is the Multipoint USB
-      Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor
-      Graphics Inventra™ design.
-    </para>
-    <para>
-      As a self-taught exercise I have written an MUSB glue layer for
-      the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers
-      in the kernel source tree. This layer can be found at
-      drivers/usb/musb/jz4740.c. In this documentation I will walk
-      through the basics of the jz4740.c glue layer, explaining the
-      different pieces and what needs to be done in order to write your
-      own device glue layer.
-    </para>
-  </chapter>
-
-  <chapter id="linux-musb-basics">
-    <title>Linux MUSB Basics</title>
-    <para>
-      To get started on the topic, please read USB On-the-Go Basics (see
-      Resources) which provides an introduction of USB OTG operation at
-      the hardware level. A couple of wiki pages by Texas Instruments
-      and Analog Devices also provide an overview of the Linux kernel
-      MUSB configuration, albeit focused on some specific devices
-      provided by these companies. Finally, getting acquainted with the
-      USB specification at USB home page may come in handy, with
-      practical instance provided through the Writing USB Device Drivers
-      documentation (again, see Resources).
-    </para>
-    <para>
-      Linux USB stack is a layered architecture in which the MUSB
-      controller hardware sits at the lowest. The MUSB controller driver
-      abstract the MUSB controller hardware to the Linux USB stack.
-    </para>
-    <programlisting>
-      ------------------------
-      |                      | <------- drivers/usb/gadget
-      | Linux USB Core Stack | <------- drivers/usb/host
-      |                      | <------- drivers/usb/core
-      ------------------------
-                 ⬍
-     --------------------------
-     |                        | <------ drivers/usb/musb/musb_gadget.c
-     | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c
-     |                        | <------ drivers/usb/musb/musb_core.c
-     --------------------------
-                 ⬍
-  ---------------------------------
-  | MUSB Platform Specific Driver |
-  |                               | <-- drivers/usb/musb/jz4740.c
-  |       aka "Glue Layer"        |
-  ---------------------------------
-                 ⬍
-  ---------------------------------
-  |   MUSB Controller Hardware    |
-  ---------------------------------
-    </programlisting>
-    <para>
-      As outlined above, the glue layer is actually the platform
-      specific code sitting in between the controller driver and the
-      controller hardware.
-    </para>
-    <para>
-      Just like a Linux USB driver needs to register itself with the
-      Linux USB subsystem, the MUSB glue layer needs first to register
-      itself with the MUSB controller driver. This will allow the
-      controller driver to know about which device the glue layer
-      supports and which functions to call when a supported device is
-      detected or released; remember we are talking about an embedded
-      controller chip here, so no insertion or removal at run-time.
-    </para>
-    <para>
-      All of this information is passed to the MUSB controller driver
-      through a platform_driver structure defined in the glue layer as:
-    </para>
-    <programlisting linenumbering="numbered">
-static struct platform_driver jz4740_driver = {
-	.probe		= jz4740_probe,
-	.remove		= jz4740_remove,
-	.driver		= {
-		.name	= "musb-jz4740",
-	},
-};
-    </programlisting>
-    <para>
-      The probe and remove function pointers are called when a matching
-      device is detected and, respectively, released. The name string
-      describes the device supported by this glue layer. In the current
-      case it matches a platform_device structure declared in
-      arch/mips/jz4740/platform.c. Note that we are not using device
-      tree bindings here.
-    </para>
-    <para>
-      In order to register itself to the controller driver, the glue
-      layer goes through a few steps, basically allocating the
-      controller hardware resources and initialising a couple of
-      circuits. To do so, it needs to keep track of the information used
-      throughout these steps. This is done by defining a private
-      jz4740_glue structure:
-    </para>
-    <programlisting linenumbering="numbered">
-struct jz4740_glue {
-	struct device           *dev;
-	struct platform_device  *musb;
-	struct clk		*clk;
-};
-    </programlisting>
-    <para>
-      The dev and musb members are both device structure variables. The
-      first one holds generic information about the device, since it's
-      the basic device structure, and the latter holds information more
-      closely related to the subsystem the device is registered to. The
-      clk variable keeps information related to the device clock
-      operation.
-    </para>
-    <para>
-      Let's go through the steps of the probe function that leads the
-      glue layer to register itself to the controller driver.
-    </para>
-    <para>
-      N.B.: For the sake of readability each function will be split in
-      logical parts, each part being shown as if it was independent from
-      the others.
-    </para>
-    <programlisting linenumbering="numbered">
-static int jz4740_probe(struct platform_device *pdev)
-{
-	struct platform_device		*musb;
-	struct jz4740_glue		*glue;
-	struct clk                      *clk;
-	int				ret;
-
-	glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL);
-	if (!glue)
-		return -ENOMEM;
-
-	musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
-	if (!musb) {
-		dev_err(&pdev->dev, "failed to allocate musb device\n");
-		return -ENOMEM;
-	}
-
-	clk = devm_clk_get(&pdev->dev, "udc");
-	if (IS_ERR(clk)) {
-		dev_err(&pdev->dev, "failed to get clock\n");
-		ret = PTR_ERR(clk);
-		goto err_platform_device_put;
-	}
-
-	ret = clk_prepare_enable(clk);
-	if (ret) {
-		dev_err(&pdev->dev, "failed to enable clock\n");
-		goto err_platform_device_put;
-	}
-
-	musb->dev.parent		= &pdev->dev;
-
-	glue->dev			= &pdev->dev;
-	glue->musb			= musb;
-	glue->clk			= clk;
-
-	return 0;
-
-err_platform_device_put:
-	platform_device_put(musb);
-	return ret;
-}
-    </programlisting>
-    <para>
-      The first few lines of the probe function allocate and assign the
-      glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows
-      the allocation process to sleep and wait for memory, thus being
-      usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line
-      12) allows automatic allocation and management of device IDs in
-      order to avoid device namespace collisions with explicit IDs. With
-      devm_clk_get() (line 18) the glue layer allocates the clock -- the
-      <literal>devm_</literal> prefix indicates that clk_get() is
-      managed: it automatically frees the allocated clock resource data
-      when the device is released -- and enable it.
-    </para>
-    <para>
-      Then comes the registration steps:
-    </para>
-    <programlisting linenumbering="numbered">
-static int jz4740_probe(struct platform_device *pdev)
-{
-	struct musb_hdrc_platform_data	*pdata = &jz4740_musb_platform_data;
-
-	pdata->platform_ops		= &jz4740_musb_ops;
-
-	platform_set_drvdata(pdev, glue);
-
-	ret = platform_device_add_resources(musb, pdev->resource,
-					    pdev->num_resources);
-	if (ret) {
-		dev_err(&pdev->dev, "failed to add resources\n");
-		goto err_clk_disable;
-	}
-
-	ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
-	if (ret) {
-		dev_err(&pdev->dev, "failed to add platform_data\n");
-		goto err_clk_disable;
-	}
-
-	return 0;
-
-err_clk_disable:
-	clk_disable_unprepare(clk);
-err_platform_device_put:
-	platform_device_put(musb);
-	return ret;
-}
-    </programlisting>
-    <para>
-      The first step is to pass the device data privately held by the
-      glue layer on to the controller driver through
-      platform_set_drvdata() (line 7). Next is passing on the device
-      resources information, also privately held at that point, through
-      platform_device_add_resources() (line 9).
-    </para>
-    <para>
-      Finally comes passing on the platform specific data to the
-      controller driver (line 16). Platform data will be discussed in
-      <link linkend="device-platform-data">Chapter 4</link>, but here
-      we are looking at the platform_ops function pointer (line 5) in
-      musb_hdrc_platform_data structure (line 3).  This function
-      pointer allows the MUSB controller driver to know which function
-      to call for device operation:
-    </para>
-    <programlisting linenumbering="numbered">
-static const struct musb_platform_ops jz4740_musb_ops = {
-	.init		= jz4740_musb_init,
-	.exit		= jz4740_musb_exit,
-};
-    </programlisting>
-    <para>
-      Here we have the minimal case where only init and exit functions
-      are called by the controller driver when needed. Fact is the
-      JZ4740 MUSB controller is a basic controller, lacking some
-      features found in other controllers, otherwise we may also have
-      pointers to a few other functions like a power management function
-      or a function to switch between OTG and non-OTG modes, for
-      instance.
-    </para>
-    <para>
-      At that point of the registration process, the controller driver
-      actually calls the init function:
-    </para>
-    <programlisting linenumbering="numbered">
-static int jz4740_musb_init(struct musb *musb)
-{
-	musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
-	if (!musb->xceiv) {
-		pr_err("HS UDC: no transceiver configured\n");
-		return -ENODEV;
-	}
-
-	/* Silicon does not implement ConfigData register.
-	 * Set dyn_fifo to avoid reading EP config from hardware.
-	 */
-	musb->dyn_fifo = true;
-
-	musb->isr = jz4740_musb_interrupt;
-
-	return 0;
-}
-    </programlisting>
-    <para>
-      The goal of jz4740_musb_init() is to get hold of the transceiver
-      driver data of the MUSB controller hardware and pass it on to the
-      MUSB controller driver, as usual. The transceiver is the circuitry
-      inside the controller hardware responsible for sending/receiving
-      the USB data. Since it is an implementation of the physical layer
-      of the OSI model, the transceiver is also referred to as PHY.
-    </para>
-    <para>
-      Getting hold of the MUSB PHY driver data is done with
-      usb_get_phy() which returns a pointer to the structure
-      containing the driver instance data. The next couple of
-      instructions (line 12 and 14) are used as a quirk and to setup
-      IRQ handling respectively. Quirks and IRQ handling will be
-      discussed later in <link linkend="device-quirks">Chapter
-      5</link> and <link linkend="handling-irqs">Chapter 3</link>.
-    </para>
-    <programlisting linenumbering="numbered">
-static int jz4740_musb_exit(struct musb *musb)
-{
-	usb_put_phy(musb->xceiv);
-
-	return 0;
-}
-    </programlisting>
-    <para>
-      Acting as the counterpart of init, the exit function releases the
-      MUSB PHY driver when the controller hardware itself is about to be
-      released.
-    </para>
-    <para>
-      Again, note that init and exit are fairly simple in this case due
-      to the basic set of features of the JZ4740 controller hardware.
-      When writing an musb glue layer for a more complex controller
-      hardware, you might need to take care of more processing in those
-      two functions.
-    </para>
-    <para>
-      Returning from the init function, the MUSB controller driver jumps
-      back into the probe function:
-    </para>
-    <programlisting linenumbering="numbered">
-static int jz4740_probe(struct platform_device *pdev)
-{
-	ret = platform_device_add(musb);
-	if (ret) {
-		dev_err(&pdev->dev, "failed to register musb device\n");
-		goto err_clk_disable;
-	}
-
-	return 0;
-
-err_clk_disable:
-	clk_disable_unprepare(clk);
-err_platform_device_put:
-	platform_device_put(musb);
-	return ret;
-}
-    </programlisting>
-    <para>
-      This is the last part of the device registration process where the
-      glue layer adds the controller hardware device to Linux kernel
-      device hierarchy: at this stage, all known information about the
-      device is passed on to the Linux USB core stack.
-    </para>
-    <programlisting linenumbering="numbered">
-static int jz4740_remove(struct platform_device *pdev)
-{
-	struct jz4740_glue	*glue = platform_get_drvdata(pdev);
-
-	platform_device_unregister(glue->musb);
-	clk_disable_unprepare(glue->clk);
-
-	return 0;
-}
-    </programlisting>
-    <para>
-      Acting as the counterpart of probe, the remove function unregister
-      the MUSB controller hardware (line 5) and disable the clock (line
-      6), allowing it to be gated.
-    </para>
-  </chapter>
-
-  <chapter id="handling-irqs">
-    <title>Handling IRQs</title>
-    <para>
-      Additionally to the MUSB controller hardware basic setup and
-      registration, the glue layer is also responsible for handling the
-      IRQs:
-    </para>
-    <programlisting linenumbering="numbered">
-static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
-{
-	unsigned long   flags;
-	irqreturn_t     retval = IRQ_NONE;
-	struct musb     *musb = __hci;
-
-	spin_lock_irqsave(&musb->lock, flags);
-
-	musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
-	musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
-	musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
-
-	/*
-	 * The controller is gadget only, the state of the host mode IRQ bits is
-	 * undefined. Mask them to make sure that the musb driver core will
-	 * never see them set
-	 */
-	musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
-	    MUSB_INTR_RESET | MUSB_INTR_SOF;
-
-	if (musb->int_usb || musb->int_tx || musb->int_rx)
-		retval = musb_interrupt(musb);
-
-	spin_unlock_irqrestore(&musb->lock, flags);
-
-	return retval;
-}
-    </programlisting>
-    <para>
-      Here the glue layer mostly has to read the relevant hardware
-      registers and pass their values on to the controller driver which
-      will handle the actual event that triggered the IRQ.
-    </para>
-    <para>
-      The interrupt handler critical section is protected by the
-      spin_lock_irqsave() and counterpart spin_unlock_irqrestore()
-      functions (line 7 and 24 respectively), which prevent the
-      interrupt handler code to be run by two different threads at the
-      same time.
-    </para>
-    <para>
-      Then the relevant interrupt registers are read (line 9 to 11):
-    </para>
-    <itemizedlist>
-      <listitem>
-        <para>
-          MUSB_INTRUSB: indicates which USB interrupts are currently
-          active,
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          MUSB_INTRTX: indicates which of the interrupts for TX
-          endpoints are currently active,
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          MUSB_INTRRX: indicates which of the interrupts for TX
-          endpoints are currently active.
-        </para>
-      </listitem>
-    </itemizedlist>
-    <para>
-      Note that musb_readb() is used to read 8-bit registers at most,
-      while musb_readw() allows us to read at most 16-bit registers.
-      There are other functions that can be used depending on the size
-      of your device registers. See musb_io.h for more information.
-    </para>
-    <para>
-      Instruction on line 18 is another quirk specific to the JZ4740
-      USB device controller, which will be discussed later in <link
-      linkend="device-quirks">Chapter 5</link>.
-    </para>
-    <para>
-      The glue layer still needs to register the IRQ handler though.
-      Remember the instruction on line 14 of the init function:
-    </para>
-    <programlisting linenumbering="numbered">
-static int jz4740_musb_init(struct musb *musb)
-{
-	musb->isr = jz4740_musb_interrupt;
-
-	return 0;
-}
-    </programlisting>
-    <para>
-      This instruction sets a pointer to the glue layer IRQ handler
-      function, in order for the controller hardware to call the handler
-      back when an IRQ comes from the controller hardware. The interrupt
-      handler is now implemented and registered.
-    </para>
-  </chapter>
-
-  <chapter id="device-platform-data">
-    <title>Device Platform Data</title>
-    <para>
-      In order to write an MUSB glue layer, you need to have some data
-      describing the hardware capabilities of your controller hardware,
-      which is called the platform data.
-    </para>
-    <para>
-      Platform data is specific to your hardware, though it may cover a
-      broad range of devices, and is generally found somewhere in the
-      arch/ directory, depending on your device architecture.
-    </para>
-    <para>
-      For instance, platform data for the JZ4740 SoC is found in
-      arch/mips/jz4740/platform.c. In the platform.c file each device of
-      the JZ4740 SoC is described through a set of structures.
-    </para>
-    <para>
-      Here is the part of arch/mips/jz4740/platform.c that covers the
-      USB Device Controller (UDC):
-    </para>
-    <programlisting linenumbering="numbered">
-/* USB Device Controller */
-struct platform_device jz4740_udc_xceiv_device = {
-	.name = "usb_phy_gen_xceiv",
-	.id   = 0,
-};
-
-static struct resource jz4740_udc_resources[] = {
-	[0] = {
-		.start = JZ4740_UDC_BASE_ADDR,
-		.end   = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
-		.flags = IORESOURCE_MEM,
-	},
-	[1] = {
-		.start = JZ4740_IRQ_UDC,
-		.end   = JZ4740_IRQ_UDC,
-		.flags = IORESOURCE_IRQ,
-		.name  = "mc",
-	},
-};
-
-struct platform_device jz4740_udc_device = {
-	.name = "musb-jz4740",
-	.id   = -1,
-	.dev  = {
-		.dma_mask          = &jz4740_udc_device.dev.coherent_dma_mask,
-		.coherent_dma_mask = DMA_BIT_MASK(32),
-	},
-	.num_resources = ARRAY_SIZE(jz4740_udc_resources),
-	.resource      = jz4740_udc_resources,
-};
-    </programlisting>
-    <para>
-      The jz4740_udc_xceiv_device platform device structure (line 2)
-      describes the UDC transceiver with a name and id number.
-    </para>
-    <para>
-      At the time of this writing, note that
-      "usb_phy_gen_xceiv" is the specific name to be used for
-      all transceivers that are either built-in with reference USB IP or
-      autonomous and doesn't require any PHY programming. You will need
-      to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make
-      use of the corresponding transceiver driver. The id field could be
-      set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to
-      PLATFORM_DEVID_AUTO) or start with 0 for the first device of this
-      kind if we want a specific id number.
-    </para>
-    <para>
-      The jz4740_udc_resources resource structure (line 7) defines the
-      UDC registers base addresses.
-    </para>
-    <para>
-      The first array (line 9 to 11) defines the UDC registers base
-      memory addresses: start points to the first register memory
-      address, end points to the last register memory address and the
-      flags member defines the type of resource we are dealing with. So
-      IORESOURCE_MEM is used to define the registers memory addresses.
-      The second array (line 14 to 17) defines the UDC IRQ registers
-      addresses. Since there is only one IRQ register available for the
-      JZ4740 UDC, start and end point at the same address. The
-      IORESOURCE_IRQ flag tells that we are dealing with IRQ resources,
-      and the name "mc" is in fact hard-coded in the MUSB core
-      in order for the controller driver to retrieve this IRQ resource
-      by querying it by its name.
-    </para>
-    <para>
-      Finally, the jz4740_udc_device platform device structure (line 21)
-      describes the UDC itself.
-    </para>
-    <para>
-      The "musb-jz4740" name (line 22) defines the MUSB
-      driver that is used for this device; remember this is in fact
-      the name that we used in the jz4740_driver platform driver
-      structure in <link linkend="linux-musb-basics">Chapter
-      2</link>. The id field (line 23) is set to -1 (equivalent to
-      PLATFORM_DEVID_NONE) since we do not need an id for the device:
-      the MUSB controller driver was already set to allocate an
-      automatic id in <link linkend="linux-musb-basics">Chapter
-      2</link>. In the dev field we care for DMA related information
-      here. The dma_mask field (line 25) defines the width of the DMA
-      mask that is going to be used, and coherent_dma_mask (line 26)
-      has the same purpose but for the alloc_coherent DMA mappings: in
-      both cases we are using a 32 bits mask. Then the resource field
-      (line 29) is simply a pointer to the resource structure defined
-      before, while the num_resources field (line 28) keeps track of
-      the number of arrays defined in the resource structure (in this
-      case there were two resource arrays defined before).
-    </para>
-    <para>
-      With this quick overview of the UDC platform data at the arch/
-      level now done, let's get back to the MUSB glue layer specific
-      platform data in drivers/usb/musb/jz4740.c:
-    </para>
-    <programlisting linenumbering="numbered">
-static struct musb_hdrc_config jz4740_musb_config = {
-	/* Silicon does not implement USB OTG. */
-	.multipoint = 0,
-	/* Max EPs scanned, driver will decide which EP can be used. */
-	.num_eps    = 4,
-	/* RAMbits needed to configure EPs from table */
-	.ram_bits   = 9,
-	.fifo_cfg = jz4740_musb_fifo_cfg,
-	.fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg),
-};
-
-static struct musb_hdrc_platform_data jz4740_musb_platform_data = {
-	.mode   = MUSB_PERIPHERAL,
-	.config = &jz4740_musb_config,
-};
-    </programlisting>
-    <para>
-      First the glue layer configures some aspects of the controller
-      driver operation related to the controller hardware specifics.
-      This is done through the jz4740_musb_config musb_hdrc_config
-      structure.
-    </para>
-    <para>
-      Defining the OTG capability of the controller hardware, the
-      multipoint member (line 3) is set to 0 (equivalent to false)
-      since the JZ4740 UDC is not OTG compatible. Then num_eps (line
-      5) defines the number of USB endpoints of the controller
-      hardware, including endpoint 0: here we have 3 endpoints +
-      endpoint 0. Next is ram_bits (line 7) which is the width of the
-      RAM address bus for the MUSB controller hardware. This
-      information is needed when the controller driver cannot
-      automatically configure endpoints by reading the relevant
-      controller hardware registers. This issue will be discussed when
-      we get to device quirks in <link linkend="device-quirks">Chapter
-      5</link>. Last two fields (line 8 and 9) are also about device
-      quirks: fifo_cfg points to the USB endpoints configuration table
-      and fifo_cfg_size keeps track of the size of the number of
-      entries in that configuration table. More on that later in <link
-      linkend="device-quirks">Chapter 5</link>.
-    </para>
-    <para>
-      Then this configuration is embedded inside
-      jz4740_musb_platform_data musb_hdrc_platform_data structure (line
-      11): config is a pointer to the configuration structure itself,
-      and mode tells the controller driver if the controller hardware
-      may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG
-      which is a dual mode.
-    </para>
-    <para>
-      Remember that jz4740_musb_platform_data is then used to convey
-      platform data information as we have seen in the probe function
-      in <link linkend="linux-musb-basics">Chapter 2</link>
-    </para>
-  </chapter>
-
-  <chapter id="device-quirks">
-    <title>Device Quirks</title>
-    <para>
-      Completing the platform data specific to your device, you may also
-      need to write some code in the glue layer to work around some
-      device specific limitations. These quirks may be due to some
-      hardware bugs, or simply be the result of an incomplete
-      implementation of the USB On-the-Go specification.
-    </para>
-    <para>
-      The JZ4740 UDC exhibits such quirks, some of which we will discuss
-      here for the sake of insight even though these might not be found
-      in the controller hardware you are working on.
-    </para>
-    <para>
-      Let's get back to the init function first:
-    </para>
-    <programlisting linenumbering="numbered">
-static int jz4740_musb_init(struct musb *musb)
-{
-	musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
-	if (!musb->xceiv) {
-		pr_err("HS UDC: no transceiver configured\n");
-		return -ENODEV;
-	}
-
-	/* Silicon does not implement ConfigData register.
-	 * Set dyn_fifo to avoid reading EP config from hardware.
-	 */
-	musb->dyn_fifo = true;
-
-	musb->isr = jz4740_musb_interrupt;
-
-	return 0;
-}
-    </programlisting>
-    <para>
-      Instruction on line 12 helps the MUSB controller driver to work
-      around the fact that the controller hardware is missing registers
-      that are used for USB endpoints configuration.
-    </para>
-    <para>
-      Without these registers, the controller driver is unable to read
-      the endpoints configuration from the hardware, so we use line 12
-      instruction to bypass reading the configuration from silicon, and
-      rely on a hard-coded table that describes the endpoints
-      configuration instead:
-    </para>
-    <programlisting linenumbering="numbered">
-static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = {
-{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
-{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
-{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
-};
-    </programlisting>
-    <para>
-      Looking at the configuration table above, we see that each
-      endpoints is described by three fields: hw_ep_num is the endpoint
-      number, style is its direction (either FIFO_TX for the controller
-      driver to send packets in the controller hardware, or FIFO_RX to
-      receive packets from hardware), and maxpacket defines the maximum
-      size of each data packet that can be transmitted over that
-      endpoint. Reading from the table, the controller driver knows that
-      endpoint 1 can be used to send and receive USB data packets of 512
-      bytes at once (this is in fact a bulk in/out endpoint), and
-      endpoint 2 can be used to send data packets of 64 bytes at once
-      (this is in fact an interrupt endpoint).
-    </para>
-    <para>
-      Note that there is no information about endpoint 0 here: that one
-      is implemented by default in every silicon design, with a
-      predefined configuration according to the USB specification. For
-      more examples of endpoint configuration tables, see musb_core.c.
-    </para>
-    <para>
-      Let's now get back to the interrupt handler function:
-    </para>
-    <programlisting linenumbering="numbered">
-static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
-{
-	unsigned long   flags;
-	irqreturn_t     retval = IRQ_NONE;
-	struct musb     *musb = __hci;
-
-	spin_lock_irqsave(&musb->lock, flags);
-
-	musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
-	musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
-	musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
-
-	/*
-	 * The controller is gadget only, the state of the host mode IRQ bits is
-	 * undefined. Mask them to make sure that the musb driver core will
-	 * never see them set
-	 */
-	musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
-	    MUSB_INTR_RESET | MUSB_INTR_SOF;
-
-	if (musb->int_usb || musb->int_tx || musb->int_rx)
-		retval = musb_interrupt(musb);
-
-	spin_unlock_irqrestore(&musb->lock, flags);
-
-	return retval;
-}
-    </programlisting>
-    <para>
-      Instruction on line 18 above is a way for the controller driver to
-      work around the fact that some interrupt bits used for USB host
-      mode operation are missing in the MUSB_INTRUSB register, thus left
-      in an undefined hardware state, since this MUSB controller
-      hardware is used in peripheral mode only. As a consequence, the
-      glue layer masks these missing bits out to avoid parasite
-      interrupts by doing a logical AND operation between the value read
-      from MUSB_INTRUSB and the bits that are actually implemented in
-      the register.
-    </para>
-    <para>
-      These are only a couple of the quirks found in the JZ4740 USB
-      device controller. Some others were directly addressed in the MUSB
-      core since the fixes were generic enough to provide a better
-      handling of the issues for others controller hardware eventually.
-    </para>
-  </chapter>
-
-  <chapter id="conclusion">
-    <title>Conclusion</title>
-    <para>
-      Writing a Linux MUSB glue layer should be a more accessible task,
-      as this documentation tries to show the ins and outs of this
-      exercise.
-    </para>
-    <para>
-      The JZ4740 USB device controller being fairly simple, I hope its
-      glue layer serves as a good example for the curious mind. Used
-      with the current MUSB glue layers, this documentation should
-      provide enough guidance to get started; should anything gets out
-      of hand, the linux-usb mailing list archive is another helpful
-      resource to browse through.
-    </para>
-  </chapter>
-
-  <chapter id="acknowledgements">
-    <title>Acknowledgements</title>
-    <para>
-      Many thanks to Lars-Peter Clausen and Maarten ter Huurne for
-      answering my questions while I was writing the JZ4740 glue layer
-      and for helping me out getting the code in good shape.
-    </para>
-    <para>
-      I would also like to thank the Qi-Hardware community at large for
-      its cheerful guidance and support.
-    </para>
-  </chapter>
-
-  <chapter id="resources">
-    <title>Resources</title>
-    <para>
-      USB Home Page:
-      <ulink url="http://www.usb.org">http://www.usb.org</ulink>
-    </para>
-    <para>
-      linux-usb Mailing List Archives:
-      <ulink url="http://marc.info/?l=linux-usb">http://marc.info/?l=linux-usb</ulink>
-    </para>
-    <para>
-      USB On-the-Go Basics:
-      <ulink url="http://www.maximintegrated.com/app-notes/index.mvp/id/1822">http://www.maximintegrated.com/app-notes/index.mvp/id/1822</ulink>
-    </para>
-    <para>
-      Writing USB Device Drivers:
-      <ulink url="https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html">https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html</ulink>
-    </para>
-    <para>
-      Texas Instruments USB Configuration Wiki Page:
-      <ulink url="http://processors.wiki.ti.com/index.php/Usbgeneralpage">http://processors.wiki.ti.com/index.php/Usbgeneralpage</ulink>
-    </para>
-    <para>
-      Analog Devices Blackfin MUSB Configuration:
-      <ulink url="http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb">http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb</ulink>
-    </para>
-  </chapter>
-
-</book>
diff --git a/Documentation/DocBook/writing_usb_driver.tmpl b/Documentation/DocBook/writing_usb_driver.tmpl
deleted file mode 100644
index 3210dcf741c9..000000000000
--- a/Documentation/DocBook/writing_usb_driver.tmpl
+++ /dev/null
@@ -1,412 +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="USBDeviceDriver">
- <bookinfo>
-  <title>Writing USB Device Drivers</title>
-  
-  <authorgroup>
-   <author>
-    <firstname>Greg</firstname>
-    <surname>Kroah-Hartman</surname>
-    <affiliation>
-     <address>
-      <email>greg at kroah.com</email>
-     </address>
-    </affiliation>
-   </author>
-  </authorgroup>
-
-  <copyright>
-   <year>2001-2002</year>
-   <holder>Greg Kroah-Hartman</holder>
-  </copyright>
-
-  <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>
-
-   <para>
-     This documentation is based on an article published in 
-     Linux Journal Magazine, October 2001, Issue 90.
-   </para>
-  </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
-  <chapter id="intro">
-      <title>Introduction</title>
-  <para>
-      The Linux USB subsystem has grown from supporting only two different
-      types of devices in the 2.2.7 kernel (mice and keyboards), to over 20
-      different types of devices in the 2.4 kernel. Linux currently supports
-      almost all USB class devices (standard types of devices like keyboards,
-      mice, modems, printers and speakers) and an ever-growing number of
-      vendor-specific devices (such as USB to serial converters, digital
-      cameras, Ethernet devices and MP3 players). For a full list of the
-      different USB devices currently supported, see Resources.
-  </para>
-  <para>
-      The remaining kinds of USB devices that do not have support on Linux are
-      almost all vendor-specific devices. Each vendor decides to implement a
-      custom protocol to talk to their device, so a custom driver usually needs
-      to be created. Some vendors are open with their USB protocols and help
-      with the creation of Linux drivers, while others do not publish them, and
-      developers are forced to reverse-engineer. See Resources for some links
-      to handy reverse-engineering tools.
-  </para>
-  <para>
-      Because each different protocol causes a new driver to be created, I have
-      written a generic USB driver skeleton, modelled after the pci-skeleton.c
-      file in the kernel source tree upon which many PCI network drivers have
-      been based. This USB skeleton can be found at drivers/usb/usb-skeleton.c
-      in the kernel source tree. In this article I will walk through the basics
-      of the skeleton driver, explaining the different pieces and what needs to
-      be done to customize it to your specific device.
-  </para>
-  </chapter>
-
-  <chapter id="basics">
-      <title>Linux USB Basics</title>
-  <para>
-      If you are going to write a Linux USB driver, please become familiar with
-      the USB protocol specification. It can be found, along with many other
-      useful documents, at the USB home page (see Resources). An excellent
-      introduction to the Linux USB subsystem can be found at the USB Working
-      Devices List (see Resources). It explains how the Linux USB subsystem is
-      structured and introduces the reader to the concept of USB urbs
-      (USB Request Blocks), which are essential to USB drivers.
-  </para>
-  <para>
-      The first thing a Linux USB driver needs to do is register itself with
-      the Linux USB subsystem, giving it some information about which devices
-      the driver supports and which functions to call when a device supported
-      by the driver is inserted or removed from the system. All of this
-      information is passed to the USB subsystem in the usb_driver structure.
-      The skeleton driver declares a usb_driver as:
-  </para>
-  <programlisting>
-static struct usb_driver skel_driver = {
-        .name        = "skeleton",
-        .probe       = skel_probe,
-        .disconnect  = skel_disconnect,
-        .fops        = &skel_fops,
-        .minor       = USB_SKEL_MINOR_BASE,
-        .id_table    = skel_table,
-};
-  </programlisting>
-  <para>
-      The variable name is a string that describes the driver. It is used in
-      informational messages printed to the system log. The probe and
-      disconnect function pointers are called when a device that matches the
-      information provided in the id_table variable is either seen or removed.
-  </para>
-  <para>
-      The fops and minor variables are optional. Most USB drivers hook into
-      another kernel subsystem, such as the SCSI, network or TTY subsystem.
-      These types of drivers register themselves with the other kernel
-      subsystem, and any user-space interactions are provided through that
-      interface. But for drivers that do not have a matching kernel subsystem,
-      such as MP3 players or scanners, a method of interacting with user space
-      is needed. The USB subsystem provides a way to register a minor device
-      number and a set of file_operations function pointers that enable this
-      user-space interaction. The skeleton driver needs this kind of interface,
-      so it provides a minor starting number and a pointer to its
-      file_operations functions.
-  </para>
-  <para>
-      The USB driver is then registered with a call to usb_register, usually in
-      the driver's init function, as shown here:
-  </para>
-  <programlisting>
-static int __init usb_skel_init(void)
-{
-        int result;
-
-        /* register this driver with the USB subsystem */
-        result = usb_register(&skel_driver);
-        if (result < 0) {
-                err("usb_register failed for the "__FILE__ "driver."
-                    "Error number %d", result);
-                return -1;
-        }
-
-        return 0;
-}
-module_init(usb_skel_init);
-  </programlisting>
-  <para>
-      When the driver is unloaded from the system, it needs to deregister
-      itself with the USB subsystem. This is done with the usb_deregister
-      function:
-  </para>
-  <programlisting>
-static void __exit usb_skel_exit(void)
-{
-        /* deregister this driver with the USB subsystem */
-        usb_deregister(&skel_driver);
-}
-module_exit(usb_skel_exit);
-  </programlisting>
-  <para>
-     To enable the linux-hotplug system to load the driver automatically when
-     the device is plugged in, you need to create a MODULE_DEVICE_TABLE. The
-     following code tells the hotplug scripts that this module supports a
-     single device with a specific vendor and product ID:
-  </para>
-  <programlisting>
-/* table of devices that work with this driver */
-static struct usb_device_id skel_table [] = {
-        { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
-        { }                      /* Terminating entry */
-};
-MODULE_DEVICE_TABLE (usb, skel_table);
-  </programlisting>
-  <para>
-     There are other macros that can be used in describing a usb_device_id for
-     drivers that support a whole class of USB drivers. See usb.h for more
-     information on this.
-  </para>
-  </chapter>
-
-  <chapter id="device">
-      <title>Device operation</title>
-  <para>
-     When a device is plugged into the USB bus that matches the device ID
-     pattern that your driver registered with the USB core, the probe function
-     is called. The usb_device structure, interface number and the interface ID
-     are passed to the function:
-  </para>
-  <programlisting>
-static int skel_probe(struct usb_interface *interface,
-    const struct usb_device_id *id)
-  </programlisting>
-  <para>
-     The driver now needs to verify that this device is actually one that it
-     can accept. If so, it returns 0.
-     If not, or if any error occurs during initialization, an errorcode
-     (such as <literal>-ENOMEM</literal> or <literal>-ENODEV</literal>)
-     is returned from the probe function.
-  </para>
-  <para>
-     In the skeleton driver, we determine what end points are marked as bulk-in
-     and bulk-out. We create buffers to hold the data that will be sent and
-     received from the device, and a USB urb to write data to the device is
-     initialized.
-  </para>
-  <para>
-     Conversely, when the device is removed from the USB bus, the disconnect
-     function is called with the device pointer. The driver needs to clean any
-     private data that has been allocated at this time and to shut down any
-     pending urbs that are in the USB system.
-  </para>
-  <para>
-     Now that the device is plugged into the system and the driver is bound to
-     the device, any of the functions in the file_operations structure that
-     were passed to the USB subsystem will be called from a user program trying
-     to talk to the device. The first function called will be open, as the
-     program tries to open the device for I/O. We increment our private usage
-     count and save a pointer to our internal structure in the file
-     structure. This is done so that future calls to file operations will
-     enable the driver to determine which device the user is addressing.  All
-     of this is done with the following code:
-  </para>
-  <programlisting>
-/* increment our usage count for the module */
-++skel->open_count;
-
-/* save our object in the file's private structure */
-file->private_data = dev;
-  </programlisting>
-  <para>
-     After the open function is called, the read and write functions are called
-     to receive and send data to the device. In the skel_write function, we
-     receive a pointer to some data that the user wants to send to the device
-     and the size of the data. The function determines how much data it can
-     send to the device based on the size of the write urb it has created (this
-     size depends on the size of the bulk out end point that the device has).
-     Then it copies the data from user space to kernel space, points the urb to
-     the data and submits the urb to the USB subsystem.  This can be seen in
-     the following code:
-  </para>
-  <programlisting>
-/* we can only write as much as 1 urb will hold */
-bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count;
-
-/* copy the data from user space into our urb */
-copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written);
-
-/* set up our urb */
-usb_fill_bulk_urb(skel->write_urb,
-                  skel->dev,
-                  usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr),
-                  skel->write_urb->transfer_buffer,
-                  bytes_written,
-                  skel_write_bulk_callback,
-                  skel);
-
-/* send the data out the bulk port */
-result = usb_submit_urb(skel->write_urb);
-if (result) {
-        err("Failed submitting write urb, error %d", result);
-}
-  </programlisting>
-  <para>
-     When the write urb is filled up with the proper information using the
-     usb_fill_bulk_urb function, we point the urb's completion callback to call our
-     own skel_write_bulk_callback function. This function is called when the
-     urb is finished by the USB subsystem. The callback function is called in
-     interrupt context, so caution must be taken not to do very much processing
-     at that time. Our implementation of skel_write_bulk_callback merely
-     reports if the urb was completed successfully or not and then returns.
-  </para>
-  <para>
-     The read function works a bit differently from the write function in that
-     we do not use an urb to transfer data from the device to the driver.
-     Instead we call the usb_bulk_msg function, which can be used to send or
-     receive data from a device without having to create urbs and handle
-     urb completion callback functions. We call the usb_bulk_msg function,
-     giving it a buffer into which to place any data received from the device
-     and a timeout value. If the timeout period expires without receiving any
-     data from the device, the function will fail and return an error message.
-     This can be shown with the following code:
-  </para>
-  <programlisting>
-/* do an immediate bulk read to get data from the device */
-retval = usb_bulk_msg (skel->dev,
-                       usb_rcvbulkpipe (skel->dev,
-                       skel->bulk_in_endpointAddr),
-                       skel->bulk_in_buffer,
-                       skel->bulk_in_size,
-                       &count, HZ*10);
-/* if the read was successful, copy the data to user space */
-if (!retval) {
-        if (copy_to_user (buffer, skel->bulk_in_buffer, count))
-                retval = -EFAULT;
-        else
-                retval = count;
-}
-  </programlisting>
-  <para>
-     The usb_bulk_msg function can be very useful for doing single reads or
-     writes to a device; however, if you need to read or write constantly to a
-     device, it is recommended to set up your own urbs and submit them to the
-     USB subsystem.
-  </para>
-  <para>
-     When the user program releases the file handle that it has been using to
-     talk to the device, the release function in the driver is called. In this
-     function we decrement our private usage count and wait for possible
-     pending writes:
-  </para>
-  <programlisting>
-/* decrement our usage count for the device */
---skel->open_count;
-  </programlisting>
-  <para>
-     One of the more difficult problems that USB drivers must be able to handle
-     smoothly is the fact that the USB device may be removed from the system at
-     any point in time, even if a program is currently talking to it. It needs
-     to be able to shut down any current reads and writes and notify the
-     user-space programs that the device is no longer there. The following
-     code (function <function>skel_delete</function>)
-     is an example of how to do this: </para>
-  <programlisting>
-static inline void skel_delete (struct usb_skel *dev)
-{
-    kfree (dev->bulk_in_buffer);
-    if (dev->bulk_out_buffer != NULL)
-        usb_free_coherent (dev->udev, dev->bulk_out_size,
-            dev->bulk_out_buffer,
-            dev->write_urb->transfer_dma);
-    usb_free_urb (dev->write_urb);
-    kfree (dev);
-}
-  </programlisting>
-  <para>
-     If a program currently has an open handle to the device, we reset the flag
-     <literal>device_present</literal>. For
-     every read, write, release and other functions that expect a device to be
-     present, the driver first checks this flag to see if the device is
-     still present. If not, it releases that the device has disappeared, and a
-     -ENODEV error is returned to the user-space program. When the release
-     function is eventually called, it determines if there is no device
-     and if not, it does the cleanup that the skel_disconnect
-     function normally does if there are no open files on the device (see
-     Listing 5).
-  </para>
-  </chapter>
-
-  <chapter id="iso">
-      <title>Isochronous Data</title>
-  <para>
-     This usb-skeleton driver does not have any examples of interrupt or
-     isochronous data being sent to or from the device. Interrupt data is sent
-     almost exactly as bulk data is, with a few minor exceptions.  Isochronous
-     data works differently with continuous streams of data being sent to or
-     from the device. The audio and video camera drivers are very good examples
-     of drivers that handle isochronous data and will be useful if you also
-     need to do this.
-  </para>
-  </chapter>
-  
-  <chapter id="Conclusion">
-      <title>Conclusion</title>
-  <para>
-     Writing Linux USB device drivers is not a difficult task as the
-     usb-skeleton driver shows. This driver, combined with the other current
-     USB drivers, should provide enough examples to help a beginning author
-     create a working driver in a minimal amount of time. The linux-usb-devel
-     mailing list archives also contain a lot of helpful information.
-  </para>
-  </chapter>
-
-  <chapter id="resources">
-      <title>Resources</title>
-  <para>
-     The Linux USB Project: <ulink url="http://www.linux-usb.org">http://www.linux-usb.org/</ulink>
-  </para>
-  <para>
-     Linux Hotplug Project: <ulink url="http://linux-hotplug.sourceforge.net">http://linux-hotplug.sourceforge.net/</ulink>
-  </para>
-  <para>
-     Linux USB Working Devices List: <ulink url="http://www.qbik.ch/usb/devices">http://www.qbik.ch/usb/devices/</ulink>
-  </para>
-  <para>
-     linux-usb-devel Mailing List Archives: <ulink url="http://marc.theaimsgroup.com/?l=linux-usb-devel">http://marc.theaimsgroup.com/?l=linux-usb-devel</ulink>
-  </para>
-  <para>
-     Programming Guide for Linux USB Device Drivers: <ulink url="http://usb.cs.tum.edu/usbdoc">http://usb.cs.tum.edu/usbdoc</ulink>
-  </para>
-  <para>
-     USB Home Page: <ulink url="http://www.usb.org">http://www.usb.org</ulink>
-  </para>
-  </chapter>
-
-</book>
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 60db00d1532b..90e742577dfc 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -26,7 +26,7 @@ available subsections can be seen below.
    regulator
    iio/index
    input
-   usb
+   usb/index
    spi
    i2c
    hsi
diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
new file mode 100644
index 000000000000..52b299b1ca6d
--- /dev/null
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -0,0 +1,533 @@
+========================
+USB Gadget API for Linux
+========================
+
+:Author: David Brownell
+:Date:   20 August 2004
+
+Introduction
+============
+
+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:
+
+-  Supports USB 2.0, for high speed devices which can stream data at
+   several dozen megabytes per second.
+
+-  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.
+
+-  Flexible enough to expose more complex USB device capabilities such
+   as multiple configurations, multiple interfaces, composite devices,
+   and alternate interface settings.
+
+-  USB "On-The-Go" (OTG) support, in conjunction with updates to the
+   Linux-USB host side.
+
+-  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).
+
+-  Minimalist, so it's easier to support new device controller hardware.
+   I/O processing doesn't imply large demands for memory or CPU
+   resources.
+
+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").
+
+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 *Chapter 9* 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.
+
+Structure of Gadget Drivers
+===========================
+
+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).
+
+In Linux, from the bottom up, these layers are:
+
+*USB Controller Driver*
+    This is the lowest software level. It is the only layer that talks
+    to hardware, through registers, fifos, dma, irqs, and the like. The
+    ``<linux/usb/gadget.h>`` 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.
+
+    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.
+
+*Gadget Driver*
+    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 *autoconfiguring* endpoints
+    automatically for many bulk-oriented drivers.) Gadget driver
+    responsibilities include:
+
+    -  handling setup requests (ep0 protocol responses) possibly
+       including class-specific functionality
+
+    -  returning configuration and string descriptors
+
+    -  (re)setting configurations and interface altsettings, including
+       enabling and configuring endpoints
+
+    -  handling life cycle events, such as managing bindings to
+       hardware, USB suspend/resume, remote wakeup, and disconnection
+       from the USB host.
+
+    -  managing IN and OUT transfers on all currently enabled endpoints
+
+    Such drivers may be modules of proprietary code, although that
+    approach is discouraged in the Linux community.
+
+*Upper Level*
+    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:
+
+    -  user mode code, using generic (gadgetfs) or application specific
+       files in ``/dev``
+
+    -  networking subsystem (for network gadgets, like the CDC Ethernet
+       Model gadget driver)
+
+    -  data capture drivers, perhaps video4Linux or a scanner driver; or
+       test and measurement hardware.
+
+    -  input subsystem (for HID gadgets)
+
+    -  sound subsystem (for audio gadgets)
+
+    -  file system (for PTP gadgets)
+
+    -  block i/o subsystem (for usb-storage gadgets)
+
+    -  ... and more
+
+*Additional Layers*
+    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 *open()*, *close()*,
+    *read()* and *write()*. 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).
+
+OTG-capable systems will also need to include a standard Linux-USB host
+side stack, with *usbcore*, one or more *Host Controller Drivers*
+(HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
+List", and so forth. There will also be an *OTG Controller Driver*,
+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.
+
+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.
+
+Kernel Mode Gadget API
+======================
+
+Gadget drivers declare themselves through a *struct
+usb_gadget_driver*, which is responsible for most parts of enumeration
+for a *struct usb_gadget*. The response to a set_configuration usually
+involves enabling one or more of the *struct usb_ep* objects exposed by
+the gadget, and submitting one or more *struct usb_request* buffers to
+transfer data. Understand those four data types, and their operations,
+and you will understand how this API works.
+
+    **Note**
+
+    This documentation was prepared using the standard Linux kernel
+    ``docproc`` 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.
+
+    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.
+
+    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 *driver model* 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.
+
+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.
+
+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.
+
+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.
+
+Driver Life Cycle
+-----------------
+
+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:
+
+1. 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.
+
+2. 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.
+
+3. 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.
+
+4. 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.
+
+5. 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
+   :c:func:`usb_gadget_vbus_draw()` 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.
+
+6. 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).
+
+7. When the gadget driver module is being unloaded, the driver unbind()
+   callback is issued. That lets the controller driver be unloaded.
+
+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.
+
+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 :c:func:`usb_gadget_wakeup()`
+slightly.
+
+USB 2.0 Chapter 9 Types and Constants
+-------------------------------------
+
+Gadget drivers rely on common USB structures and constants defined in
+the ``<linux/usb/ch9.h>`` header file, which is standard in Linux 2.6
+kernels. These are the same types and constants used by host side
+drivers (and usbcore).
+
+.. kernel-doc:: include/linux/usb/ch9.h
+   :internal:
+
+Core Objects and Methods
+------------------------
+
+These are declared in ``<linux/usb/gadget.h>``, and are used by gadget
+drivers to interact with USB peripheral controller drivers.
+
+.. kernel-doc:: include/linux/usb/gadget.h
+   :internal:
+
+Optional Utilities
+------------------
+
+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.
+
+.. kernel-doc:: drivers/usb/gadget/usbstring.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/config.c
+   :export:
+
+Composite Device Framework
+--------------------------
+
+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.
+
+Devices using this framework provide a *struct usb_composite_driver*,
+which in turn provides one or more *struct usb_configuration*
+instances. Each such configuration includes at least one *struct
+usb_function*, which packages a user visible role such as "network
+link" or "mass storage device". Management functions may also exist,
+such as "Device Firmware Upgrade".
+
+.. kernel-doc:: include/linux/usb/composite.h
+   :internal:
+
+.. kernel-doc:: drivers/usb/gadget/composite.c
+   :export:
+
+Composite Device Functions
+--------------------------
+
+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".
+
+.. kernel-doc:: drivers/usb/gadget/function/f_acm.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_ecm.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_subset.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_obex.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_serial.c
+   :export:
+
+Peripheral Controller Drivers
+=============================
+
+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
+``net2280`` driver module. The driver supports Linux kernel versions 2.4
+and 2.6; contact NetChip Technologies for development boards and product
+information.
+
+Other hardware working in the "gadget" framework includes: Intel's PXA
+25x and IXP42x series processors (``pxa2xx_udc``), Toshiba TC86c001
+"Goku-S" (``goku_udc``), Renesas SH7705/7727 (``sh_udc``), MediaQ 11xx
+(``mq11xx_udc``), Hynix HMS30C7202 (``h7202_udc``), National 9303/4
+(``n9604_udc``), Texas Instruments OMAP (``omap_udc``), Sharp LH7A40x
+(``lh7a40x_udc``), and more. Most of those are full speed controllers.
+
+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.
+
+A partial USB simulator, the ``dummy_hcd`` 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.
+
+Support for other controllers is expected to be developed and
+contributed over time, as this driver framework evolves.
+
+Gadget Drivers
+==============
+
+In addition to *Gadget Zero* (used primarily for testing and development
+with drivers for usb controller hardware), other gadget drivers exist.
+
+There's an *ethernet* gadget driver, which implements one of the most
+useful *Communications Device Class* (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.)
+
+Support for Microsoft's *RNDIS* 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.
+
+There is also support for user mode gadget drivers, using *gadgetfs*.
+This provides a *User Mode API* that presents each endpoint as a single
+file descriptor. I/O is done using normal *read()* and *read()* 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 *Async I/O (AIO)* support is available, so that user mode software
+can stream data with only slightly more overhead than a kernel driver.
+
+There's a USB Mass Storage class driver, which provides a different
+solution for interoperability with systems such as MS-Windows and MacOS.
+That *Mass Storage* driver uses a file or block device as backing store
+for a drive, like the ``loop`` 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.
+
+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.
+
+Support for other kinds of gadget is expected to be developed and
+contributed over time, as this driver framework evolves.
+
+USB On-The-GO (OTG)
+===================
+
+USB OTG support on Linux 2.6 was initially developed by Texas
+Instruments for `OMAP <http://www.omap.com>`__ 16xx and 17xx series
+processors. Other OTG systems should work in similar ways, but the
+hardware level details could be very different.
+
+Systems need specialized hardware support to implement OTG, notably
+including a special *Mini-AB* jack and associated transceiver to support
+*Dual-Role* 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 (*usb_bus* or *usb_gadget*). Such drivers
+need at most minor changes, and most of the calls added to support OTG
+can also benefit non-OTG products.
+
+-  Gadget drivers test the *is_otg* flag, and use it to determine
+   whether or not to include an OTG descriptor in each of their
+   configurations.
+
+-  Gadget drivers may need changes to support the two new OTG protocols,
+   exposed in new gadget attributes such as *b_hnp_enable* 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.
+
+-  On the host side, USB device drivers need to be taught to trigger HNP
+   at appropriate moments, using :c:func:`usb_suspend_device()`.
+   That also conserves battery power, which is useful even for non-OTG
+   configurations.
+
+-  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. *This whitelist is
+   product-specific; each product must modify ``otg_whitelist.h`` to
+   match its interoperability specification.*
+
+   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.
+
+Additional changes are needed below those hardware-neutral *usb_bus*
+and *usb_gadget* 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
+*OTG Controller Driver*, 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.
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
new file mode 100644
index 000000000000..cf2fa2e8d236
--- /dev/null
+++ b/Documentation/driver-api/usb/index.rst
@@ -0,0 +1,17 @@
+=============
+Linux USB API
+=============
+
+.. toctree::
+
+   usb
+   gadget
+   writing_usb_driver
+   writing_musb_glue_layer
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/driver-api/usb.rst b/Documentation/driver-api/usb/usb.rst
similarity index 87%
rename from Documentation/driver-api/usb.rst
rename to Documentation/driver-api/usb/usb.rst
index 851cc40b66b5..b856abb3200e 100644
--- a/Documentation/driver-api/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -329,11 +329,11 @@ to detect when devices are added or removed:
     fd = open("/proc/bus/usb/devices", O_RDONLY);
     pfd = { fd, POLLIN, 0 };
     for (;;) {
-        /* The first time through, this call will return immediately. */
-        poll(&pfd, 1, -1);
+	/* The first time through, this call will return immediately. */
+	poll(&pfd, 1, -1);
 
-        /* To see what's changed, compare the file's previous and current
-           contents or scan the filesystem.  (Scanning is more precise.) */
+	/* To see what's changed, compare the file's previous and current
+	   contents or scan the filesystem.  (Scanning is more precise.) */
     }
 
 Note that this behavior is intended to be used for informational and
@@ -462,10 +462,10 @@ USBDEVFS_CONNECTINFO
 
     ::
 
-        struct usbdevfs_connectinfo {
-                unsigned int   devnum;
-                unsigned char  slow;
-        };
+	struct usbdevfs_connectinfo {
+		unsigned int   devnum;
+		unsigned char  slow;
+	};
 
     File modification time is not updated by this request.
 
@@ -481,10 +481,10 @@ USBDEVFS_GETDRIVER
 
     ::
 
-        struct usbdevfs_getdriver {
-                unsigned int  interface;
-                char          driver[USBDEVFS_MAXDRIVERNAME + 1];
-        };
+	struct usbdevfs_getdriver {
+		unsigned int  interface;
+		char          driver[USBDEVFS_MAXDRIVERNAME + 1];
+	};
 
     File modification time is not updated by this request.
 
@@ -494,28 +494,28 @@ USBDEVFS_IOCTL
 
     ::
 
-        struct usbdevfs_ioctl {
-                int     ifno;
-                int     ioctl_code;
-                void    *data;
-        };
+	struct usbdevfs_ioctl {
+		int     ifno;
+		int     ioctl_code;
+		void    *data;
+	};
 
-        /* user mode call looks like this.
-         * 'request' becomes the driver->ioctl() 'code' parameter.
-         * the size of 'param' is encoded in 'request', and that data
-         * is copied to or from the driver->ioctl() 'buf' parameter.
-         */
-        static int
-        usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
-        {
-                struct usbdevfs_ioctl   wrapper;
+	/* user mode call looks like this.
+	 * 'request' becomes the driver->ioctl() 'code' parameter.
+	 * the size of 'param' is encoded in 'request', and that data
+	 * is copied to or from the driver->ioctl() 'buf' parameter.
+	 */
+	static int
+	usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
+	{
+		struct usbdevfs_ioctl   wrapper;
 
-                wrapper.ifno = ifno;
-                wrapper.ioctl_code = request;
-                wrapper.data = param;
+		wrapper.ifno = ifno;
+		wrapper.ioctl_code = request;
+		wrapper.data = param;
 
-                return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
-        }
+		return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
+	}
 
     File modification time is not updated by this request.
 
@@ -534,11 +534,11 @@ USBDEVFS_RELEASEINTERFACE
     the number of the interface (bInterfaceNumber from descriptor); File
     modification time is not updated by this request.
 
-        **Warning**
+	**Warning**
 
-        *No security check is made to ensure that the task which made
-        the claim is the one which is releasing it. This means that user
-        mode driver may interfere other ones.*
+	*No security check is made to ensure that the task which made
+	the claim is the one which is releasing it. This means that user
+	mode driver may interfere other ones.*
 
 USBDEVFS_RESETEP
     Resets the data toggle value for an endpoint (bulk or interrupt) to
@@ -546,13 +546,13 @@ USBDEVFS_RESETEP
     as identified in the endpoint descriptor), with USB_DIR_IN added
     if the device's endpoint sends data to the host.
 
-        **Warning**
+	**Warning**
 
-        *Avoid using this request. It should probably be removed.* Using
-        it typically means the device and driver will lose toggle
-        synchronization. If you really lost synchronization, you likely
-        need to completely handshake with the device, using a request
-        like CLEAR_HALT or SET_INTERFACE.
+	*Avoid using this request. It should probably be removed.* Using
+	it typically means the device and driver will lose toggle
+	synchronization. If you really lost synchronization, you likely
+	need to completely handshake with the device, using a request
+	like CLEAR_HALT or SET_INTERFACE.
 
 USBDEVFS_DROP_PRIVILEGES
     This is used to relinquish the ability to do certain operations
@@ -578,12 +578,12 @@ USBDEVFS_BULK
 
     ::
 
-        struct usbdevfs_bulktransfer {
-                unsigned int  ep;
-                unsigned int  len;
-                unsigned int  timeout; /* in milliseconds */
-                void          *data;
-        };
+	struct usbdevfs_bulktransfer {
+		unsigned int  ep;
+		unsigned int  len;
+		unsigned int  timeout; /* in milliseconds */
+		void          *data;
+	};
 
     The "ep" value identifies a bulk endpoint number (1 to 15, as
     identified in an endpoint descriptor), masked with USB_DIR_IN when
@@ -610,15 +610,15 @@ USBDEVFS_CONTROL
 
     ::
 
-        struct usbdevfs_ctrltransfer {
-                __u8   bRequestType;
-                __u8   bRequest;
-                __u16  wValue;
-                __u16  wIndex;
-                __u16  wLength;
-                __u32  timeout;  /* in milliseconds */
-                void   *data;
-        };
+	struct usbdevfs_ctrltransfer {
+		__u8   bRequestType;
+		__u8   bRequest;
+		__u16  wValue;
+		__u16  wIndex;
+		__u16  wLength;
+		__u32  timeout;  /* in milliseconds */
+		void   *data;
+	};
 
     The first eight bytes of this structure are the contents of the
     SETUP packet to be sent to the device; see the USB 2.0 specification
@@ -638,11 +638,11 @@ USBDEVFS_RESET
     the reset, this rebinds all device interfaces. File modification
     time is not updated by this request.
 
-        **Warning**
+	**Warning**
 
-        *Avoid using this call* until some usbcore bugs get fixed, since
-        it does not fully synchronize device, interface, and driver (not
-        just usbfs) state.
+	*Avoid using this call* until some usbcore bugs get fixed, since
+	it does not fully synchronize device, interface, and driver (not
+	just usbfs) state.
 
 USBDEVFS_SETINTERFACE
     Sets the alternate setting for an interface. The ioctl parameter is
@@ -650,10 +650,10 @@ USBDEVFS_SETINTERFACE
 
     ::
 
-        struct usbdevfs_setinterface {
-                unsigned int  interface;
-                unsigned int  altsetting;
-        };
+	struct usbdevfs_setinterface {
+		unsigned int  interface;
+		unsigned int  altsetting;
+	};
 
     File modification time is not updated by this request.
 
@@ -669,11 +669,11 @@ USBDEVFS_SETCONFIGURATION
     configuration (bConfigurationValue from descriptor). File
     modification time is not updated by this request.
 
-        **Warning**
+	**Warning**
 
-        *Avoid using this call* until some usbcore bugs get fixed, since
-        it does not fully synchronize device, interface, and driver (not
-        just usbfs) state.
+	*Avoid using this call* until some usbcore bugs get fixed, since
+	it does not fully synchronize device, interface, and driver (not
+	just usbfs) state.
 
 Asynchronous I/O Support
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -707,25 +707,25 @@ fewer bytes were read than were requested then you get an error report.
 ::
 
     struct usbdevfs_iso_packet_desc {
-            unsigned int                     length;
-            unsigned int                     actual_length;
-            unsigned int                     status;
+	    unsigned int                     length;
+	    unsigned int                     actual_length;
+	    unsigned int                     status;
     };
 
     struct usbdevfs_urb {
-            unsigned char                    type;
-            unsigned char                    endpoint;
-            int                              status;
-            unsigned int                     flags;
-            void                             *buffer;
-            int                              buffer_length;
-            int                              actual_length;
-            int                              start_frame;
-            int                              number_of_packets;
-            int                              error_count;
-            unsigned int                     signr;
-            void                             *usercontext;
-            struct usbdevfs_iso_packet_desc  iso_frame_desc[];
+	    unsigned char                    type;
+	    unsigned char                    endpoint;
+	    int                              status;
+	    unsigned int                     flags;
+	    void                             *buffer;
+	    int                              buffer_length;
+	    int                              actual_length;
+	    int                              start_frame;
+	    int                              number_of_packets;
+	    int                              error_count;
+	    unsigned int                     signr;
+	    void                             *usercontext;
+	    struct usbdevfs_iso_packet_desc  iso_frame_desc[];
     };
 
 For these asynchronous requests, the file modification time reflects
diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
new file mode 100644
index 000000000000..52700c7031f9
--- /dev/null
+++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst
@@ -0,0 +1,737 @@
+==========================
+Writing an MUSB Glue Layer
+==========================
+
+:Author: Apelete Seketeli
+
+Introduction
+============
+
+The Linux MUSB subsystem is part of the larger Linux USB subsystem. It
+provides support for embedded USB Device Controllers (UDC) that do not
+use Universal Host Controller Interface (UHCI) or Open Host Controller
+Interface (OHCI).
+
+Instead, these embedded UDC rely on the USB On-the-Go (OTG)
+specification which they implement at least partially. The silicon
+reference design used in most cases is the Multipoint USB Highspeed
+Dual-Role Controller (MUSB HDRC) found in the Mentor Graphics Inventra™
+design.
+
+As a self-taught exercise I have written an MUSB glue layer for the
+Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the
+kernel source tree. This layer can be found at
+drivers/usb/musb/jz4740.c. In this documentation I will walk through the
+basics of the jz4740.c glue layer, explaining the different pieces and
+what needs to be done in order to write your own device glue layer.
+
+Linux MUSB Basics
+=================
+
+To get started on the topic, please read USB On-the-Go Basics (see
+Resources) which provides an introduction of USB OTG operation at the
+hardware level. A couple of wiki pages by Texas Instruments and Analog
+Devices also provide an overview of the Linux kernel MUSB configuration,
+albeit focused on some specific devices provided by these companies.
+Finally, getting acquainted with the USB specification at USB home page
+may come in handy, with practical instance provided through the Writing
+USB Device Drivers documentation (again, see Resources).
+
+Linux USB stack is a layered architecture in which the MUSB controller
+hardware sits at the lowest. The MUSB controller driver abstract the
+MUSB controller hardware to the Linux USB stack.
+
+::
+
+          ------------------------
+          |                      | <------- drivers/usb/gadget
+          | Linux USB Core Stack | <------- drivers/usb/host
+          |                      | <------- drivers/usb/core
+          ------------------------
+                     ⬍
+         --------------------------
+         |                        | <------ drivers/usb/musb/musb_gadget.c
+         | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c
+         |                        | <------ drivers/usb/musb/musb_core.c
+         --------------------------
+                     ⬍
+      ---------------------------------
+      | MUSB Platform Specific Driver |
+      |                               | <-- drivers/usb/musb/jz4740.c
+      |       aka "Glue Layer"        |
+      ---------------------------------
+                     ⬍
+      ---------------------------------
+      |   MUSB Controller Hardware    |
+      ---------------------------------
+
+
+As outlined above, the glue layer is actually the platform specific code
+sitting in between the controller driver and the controller hardware.
+
+Just like a Linux USB driver needs to register itself with the Linux USB
+subsystem, the MUSB glue layer needs first to register itself with the
+MUSB controller driver. This will allow the controller driver to know
+about which device the glue layer supports and which functions to call
+when a supported device is detected or released; remember we are talking
+about an embedded controller chip here, so no insertion or removal at
+run-time.
+
+All of this information is passed to the MUSB controller driver through
+a platform_driver structure defined in the glue layer as:
+
+::
+
+    static struct platform_driver jz4740_driver = {
+        .probe      = jz4740_probe,
+        .remove     = jz4740_remove,
+        .driver     = {
+            .name   = "musb-jz4740",
+        },
+    };
+
+
+The probe and remove function pointers are called when a matching device
+is detected and, respectively, released. The name string describes the
+device supported by this glue layer. In the current case it matches a
+platform_device structure declared in arch/mips/jz4740/platform.c. Note
+that we are not using device tree bindings here.
+
+In order to register itself to the controller driver, the glue layer
+goes through a few steps, basically allocating the controller hardware
+resources and initialising a couple of circuits. To do so, it needs to
+keep track of the information used throughout these steps. This is done
+by defining a private jz4740_glue structure:
+
+::
+
+    struct jz4740_glue {
+        struct device           *dev;
+        struct platform_device  *musb;
+        struct clk      *clk;
+    };
+
+
+The dev and musb members are both device structure variables. The first
+one holds generic information about the device, since it's the basic
+device structure, and the latter holds information more closely related
+to the subsystem the device is registered to. The clk variable keeps
+information related to the device clock operation.
+
+Let's go through the steps of the probe function that leads the glue
+layer to register itself to the controller driver.
+
+N.B.: For the sake of readability each function will be split in logical
+parts, each part being shown as if it was independent from the others.
+
+::
+
+    static int jz4740_probe(struct platform_device *pdev)
+    {
+        struct platform_device      *musb;
+        struct jz4740_glue      *glue;
+        struct clk                      *clk;
+        int             ret;
+
+        glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL);
+        if (!glue)
+            return -ENOMEM;
+
+        musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
+        if (!musb) {
+            dev_err(&pdev->dev, "failed to allocate musb device\n");
+            return -ENOMEM;
+        }
+
+        clk = devm_clk_get(&pdev->dev, "udc");
+        if (IS_ERR(clk)) {
+            dev_err(&pdev->dev, "failed to get clock\n");
+            ret = PTR_ERR(clk);
+            goto err_platform_device_put;
+        }
+
+        ret = clk_prepare_enable(clk);
+        if (ret) {
+            dev_err(&pdev->dev, "failed to enable clock\n");
+            goto err_platform_device_put;
+        }
+
+        musb->dev.parent        = &pdev->dev;
+
+        glue->dev           = &pdev->dev;
+        glue->musb          = musb;
+        glue->clk           = clk;
+
+        return 0;
+
+    err_platform_device_put:
+        platform_device_put(musb);
+        return ret;
+    }
+
+
+The first few lines of the probe function allocate and assign the glue,
+musb and clk variables. The GFP_KERNEL flag (line 8) allows the
+allocation process to sleep and wait for memory, thus being usable in a
+blocking situation. The PLATFORM_DEVID_AUTO flag (line 12) allows
+automatic allocation and management of device IDs in order to avoid
+device namespace collisions with explicit IDs. With devm_clk_get()
+(line 18) the glue layer allocates the clock -- the ``devm_`` prefix
+indicates that clk_get() is managed: it automatically frees the
+allocated clock resource data when the device is released -- and enable
+it.
+
+Then comes the registration steps:
+
+::
+
+    static int jz4740_probe(struct platform_device *pdev)
+    {
+        struct musb_hdrc_platform_data  *pdata = &jz4740_musb_platform_data;
+
+        pdata->platform_ops     = &jz4740_musb_ops;
+
+        platform_set_drvdata(pdev, glue);
+
+        ret = platform_device_add_resources(musb, pdev->resource,
+                            pdev->num_resources);
+        if (ret) {
+            dev_err(&pdev->dev, "failed to add resources\n");
+            goto err_clk_disable;
+        }
+
+        ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
+        if (ret) {
+            dev_err(&pdev->dev, "failed to add platform_data\n");
+            goto err_clk_disable;
+        }
+
+        return 0;
+
+    err_clk_disable:
+        clk_disable_unprepare(clk);
+    err_platform_device_put:
+        platform_device_put(musb);
+        return ret;
+    }
+
+
+The first step is to pass the device data privately held by the glue
+layer on to the controller driver through platform_set_drvdata() (line
+7). Next is passing on the device resources information, also privately
+held at that point, through platform_device_add_resources() (line 9).
+
+Finally comes passing on the platform specific data to the controller
+driver (line 16). Platform data will be discussed in `Chapter
+4 <#device-platform-data>`__, but here we are looking at the
+platform_ops function pointer (line 5) in musb_hdrc_platform_data
+structure (line 3). This function pointer allows the MUSB controller
+driver to know which function to call for device operation:
+
+::
+
+    static const struct musb_platform_ops jz4740_musb_ops = {
+        .init       = jz4740_musb_init,
+        .exit       = jz4740_musb_exit,
+    };
+
+
+Here we have the minimal case where only init and exit functions are
+called by the controller driver when needed. Fact is the JZ4740 MUSB
+controller is a basic controller, lacking some features found in other
+controllers, otherwise we may also have pointers to a few other
+functions like a power management function or a function to switch
+between OTG and non-OTG modes, for instance.
+
+At that point of the registration process, the controller driver
+actually calls the init function:
+
+::
+
+    static int jz4740_musb_init(struct musb *musb)
+    {
+        musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
+        if (!musb->xceiv) {
+            pr_err("HS UDC: no transceiver configured\n");
+            return -ENODEV;
+        }
+
+        /* Silicon does not implement ConfigData register.
+         * Set dyn_fifo to avoid reading EP config from hardware.
+         */
+        musb->dyn_fifo = true;
+
+        musb->isr = jz4740_musb_interrupt;
+
+        return 0;
+    }
+
+
+The goal of jz4740_musb_init() is to get hold of the transceiver
+driver data of the MUSB controller hardware and pass it on to the MUSB
+controller driver, as usual. The transceiver is the circuitry inside the
+controller hardware responsible for sending/receiving the USB data.
+Since it is an implementation of the physical layer of the OSI model,
+the transceiver is also referred to as PHY.
+
+Getting hold of the MUSB PHY driver data is done with usb_get_phy()
+which returns a pointer to the structure containing the driver instance
+data. The next couple of instructions (line 12 and 14) are used as a
+quirk and to setup IRQ handling respectively. Quirks and IRQ handling
+will be discussed later in `Chapter 5 <#device-quirks>`__ and `Chapter
+3 <#handling-irqs>`__.
+
+::
+
+    static int jz4740_musb_exit(struct musb *musb)
+    {
+        usb_put_phy(musb->xceiv);
+
+        return 0;
+    }
+
+
+Acting as the counterpart of init, the exit function releases the MUSB
+PHY driver when the controller hardware itself is about to be released.
+
+Again, note that init and exit are fairly simple in this case due to the
+basic set of features of the JZ4740 controller hardware. When writing an
+musb glue layer for a more complex controller hardware, you might need
+to take care of more processing in those two functions.
+
+Returning from the init function, the MUSB controller driver jumps back
+into the probe function:
+
+::
+
+    static int jz4740_probe(struct platform_device *pdev)
+    {
+        ret = platform_device_add(musb);
+        if (ret) {
+            dev_err(&pdev->dev, "failed to register musb device\n");
+            goto err_clk_disable;
+        }
+
+        return 0;
+
+    err_clk_disable:
+        clk_disable_unprepare(clk);
+    err_platform_device_put:
+        platform_device_put(musb);
+        return ret;
+    }
+
+
+This is the last part of the device registration process where the glue
+layer adds the controller hardware device to Linux kernel device
+hierarchy: at this stage, all known information about the device is
+passed on to the Linux USB core stack.
+
+::
+
+    static int jz4740_remove(struct platform_device *pdev)
+    {
+        struct jz4740_glue  *glue = platform_get_drvdata(pdev);
+
+        platform_device_unregister(glue->musb);
+        clk_disable_unprepare(glue->clk);
+
+        return 0;
+    }
+
+
+Acting as the counterpart of probe, the remove function unregister the
+MUSB controller hardware (line 5) and disable the clock (line 6),
+allowing it to be gated.
+
+Handling IRQs
+=============
+
+Additionally to the MUSB controller hardware basic setup and
+registration, the glue layer is also responsible for handling the IRQs:
+
+::
+
+    static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
+    {
+        unsigned long   flags;
+        irqreturn_t     retval = IRQ_NONE;
+        struct musb     *musb = __hci;
+
+        spin_lock_irqsave(&musb->lock, flags);
+
+        musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
+        musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
+        musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
+
+        /*
+         * The controller is gadget only, the state of the host mode IRQ bits is
+         * undefined. Mask them to make sure that the musb driver core will
+         * never see them set
+         */
+        musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
+            MUSB_INTR_RESET | MUSB_INTR_SOF;
+
+        if (musb->int_usb || musb->int_tx || musb->int_rx)
+            retval = musb_interrupt(musb);
+
+        spin_unlock_irqrestore(&musb->lock, flags);
+
+        return retval;
+    }
+
+
+Here the glue layer mostly has to read the relevant hardware registers
+and pass their values on to the controller driver which will handle the
+actual event that triggered the IRQ.
+
+The interrupt handler critical section is protected by the
+spin_lock_irqsave() and counterpart spin_unlock_irqrestore()
+functions (line 7 and 24 respectively), which prevent the interrupt
+handler code to be run by two different threads at the same time.
+
+Then the relevant interrupt registers are read (line 9 to 11):
+
+-  MUSB_INTRUSB: indicates which USB interrupts are currently active,
+
+-  MUSB_INTRTX: indicates which of the interrupts for TX endpoints are
+   currently active,
+
+-  MUSB_INTRRX: indicates which of the interrupts for TX endpoints are
+   currently active.
+
+Note that musb_readb() is used to read 8-bit registers at most, while
+musb_readw() allows us to read at most 16-bit registers. There are
+other functions that can be used depending on the size of your device
+registers. See musb_io.h for more information.
+
+Instruction on line 18 is another quirk specific to the JZ4740 USB
+device controller, which will be discussed later in `Chapter
+5 <#device-quirks>`__.
+
+The glue layer still needs to register the IRQ handler though. Remember
+the instruction on line 14 of the init function:
+
+::
+
+    static int jz4740_musb_init(struct musb *musb)
+    {
+        musb->isr = jz4740_musb_interrupt;
+
+        return 0;
+    }
+
+
+This instruction sets a pointer to the glue layer IRQ handler function,
+in order for the controller hardware to call the handler back when an
+IRQ comes from the controller hardware. The interrupt handler is now
+implemented and registered.
+
+Device Platform Data
+====================
+
+In order to write an MUSB glue layer, you need to have some data
+describing the hardware capabilities of your controller hardware, which
+is called the platform data.
+
+Platform data is specific to your hardware, though it may cover a broad
+range of devices, and is generally found somewhere in the arch/
+directory, depending on your device architecture.
+
+For instance, platform data for the JZ4740 SoC is found in
+arch/mips/jz4740/platform.c. In the platform.c file each device of the
+JZ4740 SoC is described through a set of structures.
+
+Here is the part of arch/mips/jz4740/platform.c that covers the USB
+Device Controller (UDC):
+
+::
+
+    /* USB Device Controller */
+    struct platform_device jz4740_udc_xceiv_device = {
+        .name = "usb_phy_gen_xceiv",
+        .id   = 0,
+    };
+
+    static struct resource jz4740_udc_resources[] = {
+        [0] = {
+            .start = JZ4740_UDC_BASE_ADDR,
+            .end   = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
+            .flags = IORESOURCE_MEM,
+        },
+        [1] = {
+            .start = JZ4740_IRQ_UDC,
+            .end   = JZ4740_IRQ_UDC,
+            .flags = IORESOURCE_IRQ,
+            .name  = "mc",
+        },
+    };
+
+    struct platform_device jz4740_udc_device = {
+        .name = "musb-jz4740",
+        .id   = -1,
+        .dev  = {
+            .dma_mask          = &jz4740_udc_device.dev.coherent_dma_mask,
+            .coherent_dma_mask = DMA_BIT_MASK(32),
+        },
+        .num_resources = ARRAY_SIZE(jz4740_udc_resources),
+        .resource      = jz4740_udc_resources,
+    };
+
+
+The jz4740_udc_xceiv_device platform device structure (line 2)
+describes the UDC transceiver with a name and id number.
+
+At the time of this writing, note that "usb_phy_gen_xceiv" is the
+specific name to be used for all transceivers that are either built-in
+with reference USB IP or autonomous and doesn't require any PHY
+programming. You will need to set CONFIG_NOP_USB_XCEIV=y in the
+kernel configuration to make use of the corresponding transceiver
+driver. The id field could be set to -1 (equivalent to
+PLATFORM_DEVID_NONE), -2 (equivalent to PLATFORM_DEVID_AUTO) or
+start with 0 for the first device of this kind if we want a specific id
+number.
+
+The jz4740_udc_resources resource structure (line 7) defines the UDC
+registers base addresses.
+
+The first array (line 9 to 11) defines the UDC registers base memory
+addresses: start points to the first register memory address, end points
+to the last register memory address and the flags member defines the
+type of resource we are dealing with. So IORESOURCE_MEM is used to
+define the registers memory addresses. The second array (line 14 to 17)
+defines the UDC IRQ registers addresses. Since there is only one IRQ
+register available for the JZ4740 UDC, start and end point at the same
+address. The IORESOURCE_IRQ flag tells that we are dealing with IRQ
+resources, and the name "mc" is in fact hard-coded in the MUSB core in
+order for the controller driver to retrieve this IRQ resource by
+querying it by its name.
+
+Finally, the jz4740_udc_device platform device structure (line 21)
+describes the UDC itself.
+
+The "musb-jz4740" name (line 22) defines the MUSB driver that is used
+for this device; remember this is in fact the name that we used in the
+jz4740_driver platform driver structure in `Chapter
+2 <#linux-musb-basics>`__. The id field (line 23) is set to -1
+(equivalent to PLATFORM_DEVID_NONE) since we do not need an id for the
+device: the MUSB controller driver was already set to allocate an
+automatic id in `Chapter 2 <#linux-musb-basics>`__. In the dev field we
+care for DMA related information here. The dma_mask field (line 25)
+defines the width of the DMA mask that is going to be used, and
+coherent_dma_mask (line 26) has the same purpose but for the
+alloc_coherent DMA mappings: in both cases we are using a 32 bits mask.
+Then the resource field (line 29) is simply a pointer to the resource
+structure defined before, while the num_resources field (line 28) keeps
+track of the number of arrays defined in the resource structure (in this
+case there were two resource arrays defined before).
+
+With this quick overview of the UDC platform data at the arch/ level now
+done, let's get back to the MUSB glue layer specific platform data in
+drivers/usb/musb/jz4740.c:
+
+::
+
+    static struct musb_hdrc_config jz4740_musb_config = {
+        /* Silicon does not implement USB OTG. */
+        .multipoint = 0,
+        /* Max EPs scanned, driver will decide which EP can be used. */
+        .num_eps    = 4,
+        /* RAMbits needed to configure EPs from table */
+        .ram_bits   = 9,
+        .fifo_cfg = jz4740_musb_fifo_cfg,
+        .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg),
+    };
+
+    static struct musb_hdrc_platform_data jz4740_musb_platform_data = {
+        .mode   = MUSB_PERIPHERAL,
+        .config = &jz4740_musb_config,
+    };
+
+
+First the glue layer configures some aspects of the controller driver
+operation related to the controller hardware specifics. This is done
+through the jz4740_musb_config musb_hdrc_config structure.
+
+Defining the OTG capability of the controller hardware, the multipoint
+member (line 3) is set to 0 (equivalent to false) since the JZ4740 UDC
+is not OTG compatible. Then num_eps (line 5) defines the number of USB
+endpoints of the controller hardware, including endpoint 0: here we have
+3 endpoints + endpoint 0. Next is ram_bits (line 7) which is the width
+of the RAM address bus for the MUSB controller hardware. This
+information is needed when the controller driver cannot automatically
+configure endpoints by reading the relevant controller hardware
+registers. This issue will be discussed when we get to device quirks in
+`Chapter 5 <#device-quirks>`__. Last two fields (line 8 and 9) are also
+about device quirks: fifo_cfg points to the USB endpoints configuration
+table and fifo_cfg_size keeps track of the size of the number of
+entries in that configuration table. More on that later in `Chapter
+5 <#device-quirks>`__.
+
+Then this configuration is embedded inside jz4740_musb_platform_data
+musb_hdrc_platform_data structure (line 11): config is a pointer to
+the configuration structure itself, and mode tells the controller driver
+if the controller hardware may be used as MUSB_HOST only,
+MUSB_PERIPHERAL only or MUSB_OTG which is a dual mode.
+
+Remember that jz4740_musb_platform_data is then used to convey
+platform data information as we have seen in the probe function in
+`Chapter 2 <#linux-musb-basics>`__
+
+Device Quirks
+=============
+
+Completing the platform data specific to your device, you may also need
+to write some code in the glue layer to work around some device specific
+limitations. These quirks may be due to some hardware bugs, or simply be
+the result of an incomplete implementation of the USB On-the-Go
+specification.
+
+The JZ4740 UDC exhibits such quirks, some of which we will discuss here
+for the sake of insight even though these might not be found in the
+controller hardware you are working on.
+
+Let's get back to the init function first:
+
+::
+
+    static int jz4740_musb_init(struct musb *musb)
+    {
+        musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
+        if (!musb->xceiv) {
+            pr_err("HS UDC: no transceiver configured\n");
+            return -ENODEV;
+        }
+
+        /* Silicon does not implement ConfigData register.
+         * Set dyn_fifo to avoid reading EP config from hardware.
+         */
+        musb->dyn_fifo = true;
+
+        musb->isr = jz4740_musb_interrupt;
+
+        return 0;
+    }
+
+
+Instruction on line 12 helps the MUSB controller driver to work around
+the fact that the controller hardware is missing registers that are used
+for USB endpoints configuration.
+
+Without these registers, the controller driver is unable to read the
+endpoints configuration from the hardware, so we use line 12 instruction
+to bypass reading the configuration from silicon, and rely on a
+hard-coded table that describes the endpoints configuration instead:
+
+::
+
+    static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = {
+    { .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
+    { .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
+    { .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
+    };
+
+
+Looking at the configuration table above, we see that each endpoints is
+described by three fields: hw_ep_num is the endpoint number, style is
+its direction (either FIFO_TX for the controller driver to send packets
+in the controller hardware, or FIFO_RX to receive packets from
+hardware), and maxpacket defines the maximum size of each data packet
+that can be transmitted over that endpoint. Reading from the table, the
+controller driver knows that endpoint 1 can be used to send and receive
+USB data packets of 512 bytes at once (this is in fact a bulk in/out
+endpoint), and endpoint 2 can be used to send data packets of 64 bytes
+at once (this is in fact an interrupt endpoint).
+
+Note that there is no information about endpoint 0 here: that one is
+implemented by default in every silicon design, with a predefined
+configuration according to the USB specification. For more examples of
+endpoint configuration tables, see musb_core.c.
+
+Let's now get back to the interrupt handler function:
+
+::
+
+    static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
+    {
+        unsigned long   flags;
+        irqreturn_t     retval = IRQ_NONE;
+        struct musb     *musb = __hci;
+
+        spin_lock_irqsave(&musb->lock, flags);
+
+        musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
+        musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
+        musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
+
+        /*
+         * The controller is gadget only, the state of the host mode IRQ bits is
+         * undefined. Mask them to make sure that the musb driver core will
+         * never see them set
+         */
+        musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
+            MUSB_INTR_RESET | MUSB_INTR_SOF;
+
+        if (musb->int_usb || musb->int_tx || musb->int_rx)
+            retval = musb_interrupt(musb);
+
+        spin_unlock_irqrestore(&musb->lock, flags);
+
+        return retval;
+    }
+
+
+Instruction on line 18 above is a way for the controller driver to work
+around the fact that some interrupt bits used for USB host mode
+operation are missing in the MUSB_INTRUSB register, thus left in an
+undefined hardware state, since this MUSB controller hardware is used in
+peripheral mode only. As a consequence, the glue layer masks these
+missing bits out to avoid parasite interrupts by doing a logical AND
+operation between the value read from MUSB_INTRUSB and the bits that
+are actually implemented in the register.
+
+These are only a couple of the quirks found in the JZ4740 USB device
+controller. Some others were directly addressed in the MUSB core since
+the fixes were generic enough to provide a better handling of the issues
+for others controller hardware eventually.
+
+Conclusion
+==========
+
+Writing a Linux MUSB glue layer should be a more accessible task, as
+this documentation tries to show the ins and outs of this exercise.
+
+The JZ4740 USB device controller being fairly simple, I hope its glue
+layer serves as a good example for the curious mind. Used with the
+current MUSB glue layers, this documentation should provide enough
+guidance to get started; should anything gets out of hand, the linux-usb
+mailing list archive is another helpful resource to browse through.
+
+Acknowledgements
+================
+
+Many thanks to Lars-Peter Clausen and Maarten ter Huurne for answering
+my questions while I was writing the JZ4740 glue layer and for helping
+me out getting the code in good shape.
+
+I would also like to thank the Qi-Hardware community at large for its
+cheerful guidance and support.
+
+Resources
+=========
+
+USB Home Page: http://www.usb.org
+
+linux-usb Mailing List Archives: http://marc.info/?l=linux-usb
+
+USB On-the-Go Basics:
+http://www.maximintegrated.com/app-notes/index.mvp/id/1822
+
+Writing USB Device Drivers:
+https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html
+
+Texas Instruments USB Configuration Wiki Page:
+http://processors.wiki.ti.com/index.php/Usbgeneralpage
+
+Analog Devices Blackfin MUSB Configuration:
+http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb
diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst
new file mode 100644
index 000000000000..c18dbd74152b
--- /dev/null
+++ b/Documentation/driver-api/usb/writing_usb_driver.rst
@@ -0,0 +1,344 @@
+==========================
+Writing USB Device Drivers
+==========================
+
+:Author: Greg Kroah-Hartman
+
+Introduction
+============
+
+The Linux USB subsystem has grown from supporting only two different
+types of devices in the 2.2.7 kernel (mice and keyboards), to over 20
+different types of devices in the 2.4 kernel. Linux currently supports
+almost all USB class devices (standard types of devices like keyboards,
+mice, modems, printers and speakers) and an ever-growing number of
+vendor-specific devices (such as USB to serial converters, digital
+cameras, Ethernet devices and MP3 players). For a full list of the
+different USB devices currently supported, see Resources.
+
+The remaining kinds of USB devices that do not have support on Linux are
+almost all vendor-specific devices. Each vendor decides to implement a
+custom protocol to talk to their device, so a custom driver usually
+needs to be created. Some vendors are open with their USB protocols and
+help with the creation of Linux drivers, while others do not publish
+them, and developers are forced to reverse-engineer. See Resources for
+some links to handy reverse-engineering tools.
+
+Because each different protocol causes a new driver to be created, I
+have written a generic USB driver skeleton, modelled after the
+pci-skeleton.c file in the kernel source tree upon which many PCI
+network drivers have been based. This USB skeleton can be found at
+drivers/usb/usb-skeleton.c in the kernel source tree. In this article I
+will walk through the basics of the skeleton driver, explaining the
+different pieces and what needs to be done to customize it to your
+specific device.
+
+Linux USB Basics
+================
+
+If you are going to write a Linux USB driver, please become familiar
+with the USB protocol specification. It can be found, along with many
+other useful documents, at the USB home page (see Resources). An
+excellent introduction to the Linux USB subsystem can be found at the
+USB Working Devices List (see Resources). It explains how the Linux USB
+subsystem is structured and introduces the reader to the concept of USB
+urbs (USB Request Blocks), which are essential to USB drivers.
+
+The first thing a Linux USB driver needs to do is register itself with
+the Linux USB subsystem, giving it some information about which devices
+the driver supports and which functions to call when a device supported
+by the driver is inserted or removed from the system. All of this
+information is passed to the USB subsystem in the usb_driver structure.
+The skeleton driver declares a usb_driver as:
+
+::
+
+    static struct usb_driver skel_driver = {
+            .name        = "skeleton",
+            .probe       = skel_probe,
+            .disconnect  = skel_disconnect,
+            .fops        = &skel_fops,
+            .minor       = USB_SKEL_MINOR_BASE,
+            .id_table    = skel_table,
+    };
+
+
+The variable name is a string that describes the driver. It is used in
+informational messages printed to the system log. The probe and
+disconnect function pointers are called when a device that matches the
+information provided in the id_table variable is either seen or
+removed.
+
+The fops and minor variables are optional. Most USB drivers hook into
+another kernel subsystem, such as the SCSI, network or TTY subsystem.
+These types of drivers register themselves with the other kernel
+subsystem, and any user-space interactions are provided through that
+interface. But for drivers that do not have a matching kernel subsystem,
+such as MP3 players or scanners, a method of interacting with user space
+is needed. The USB subsystem provides a way to register a minor device
+number and a set of file_operations function pointers that enable this
+user-space interaction. The skeleton driver needs this kind of
+interface, so it provides a minor starting number and a pointer to its
+file_operations functions.
+
+The USB driver is then registered with a call to usb_register, usually
+in the driver's init function, as shown here:
+
+::
+
+    static int __init usb_skel_init(void)
+    {
+            int result;
+
+            /* register this driver with the USB subsystem */
+            result = usb_register(&skel_driver);
+            if (result < 0) {
+                    err("usb_register failed for the "__FILE__ "driver."
+                        "Error number %d", result);
+                    return -1;
+            }
+
+            return 0;
+    }
+    module_init(usb_skel_init);
+
+
+When the driver is unloaded from the system, it needs to deregister
+itself with the USB subsystem. This is done with the usb_deregister
+function:
+
+::
+
+    static void __exit usb_skel_exit(void)
+    {
+            /* deregister this driver with the USB subsystem */
+            usb_deregister(&skel_driver);
+    }
+    module_exit(usb_skel_exit);
+
+
+To enable the linux-hotplug system to load the driver automatically when
+the device is plugged in, you need to create a MODULE_DEVICE_TABLE.
+The following code tells the hotplug scripts that this module supports a
+single device with a specific vendor and product ID:
+
+::
+
+    /* table of devices that work with this driver */
+    static struct usb_device_id skel_table [] = {
+            { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
+            { }                      /* Terminating entry */
+    };
+    MODULE_DEVICE_TABLE (usb, skel_table);
+
+
+There are other macros that can be used in describing a usb_device_id
+for drivers that support a whole class of USB drivers. See usb.h for
+more information on this.
+
+Device operation
+================
+
+When a device is plugged into the USB bus that matches the device ID
+pattern that your driver registered with the USB core, the probe
+function is called. The usb_device structure, interface number and the
+interface ID are passed to the function:
+
+::
+
+    static int skel_probe(struct usb_interface *interface,
+        const struct usb_device_id *id)
+
+
+The driver now needs to verify that this device is actually one that it
+can accept. If so, it returns 0. If not, or if any error occurs during
+initialization, an errorcode (such as ``-ENOMEM`` or ``-ENODEV``) is
+returned from the probe function.
+
+In the skeleton driver, we determine what end points are marked as
+bulk-in and bulk-out. We create buffers to hold the data that will be
+sent and received from the device, and a USB urb to write data to the
+device is initialized.
+
+Conversely, when the device is removed from the USB bus, the disconnect
+function is called with the device pointer. The driver needs to clean
+any private data that has been allocated at this time and to shut down
+any pending urbs that are in the USB system.
+
+Now that the device is plugged into the system and the driver is bound
+to the device, any of the functions in the file_operations structure
+that were passed to the USB subsystem will be called from a user program
+trying to talk to the device. The first function called will be open, as
+the program tries to open the device for I/O. We increment our private
+usage count and save a pointer to our internal structure in the file
+structure. This is done so that future calls to file operations will
+enable the driver to determine which device the user is addressing. All
+of this is done with the following code:
+
+::
+
+    /* increment our usage count for the module */
+    ++skel->open_count;
+
+    /* save our object in the file's private structure */
+    file->private_data = dev;
+
+
+After the open function is called, the read and write functions are
+called to receive and send data to the device. In the skel_write
+function, we receive a pointer to some data that the user wants to send
+to the device and the size of the data. The function determines how much
+data it can send to the device based on the size of the write urb it has
+created (this size depends on the size of the bulk out end point that
+the device has). Then it copies the data from user space to kernel
+space, points the urb to the data and submits the urb to the USB
+subsystem. This can be seen in the following code:
+
+::
+
+    /* we can only write as much as 1 urb will hold */
+    bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count;
+
+    /* copy the data from user space into our urb */
+    copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written);
+
+    /* set up our urb */
+    usb_fill_bulk_urb(skel->write_urb,
+                      skel->dev,
+                      usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr),
+                      skel->write_urb->transfer_buffer,
+                      bytes_written,
+                      skel_write_bulk_callback,
+                      skel);
+
+    /* send the data out the bulk port */
+    result = usb_submit_urb(skel->write_urb);
+    if (result) {
+            err("Failed submitting write urb, error %d", result);
+    }
+
+
+When the write urb is filled up with the proper information using the
+usb_fill_bulk_urb function, we point the urb's completion callback to
+call our own skel_write_bulk_callback function. This function is
+called when the urb is finished by the USB subsystem. The callback
+function is called in interrupt context, so caution must be taken not to
+do very much processing at that time. Our implementation of
+skel_write_bulk_callback merely reports if the urb was completed
+successfully or not and then returns.
+
+The read function works a bit differently from the write function in
+that we do not use an urb to transfer data from the device to the
+driver. Instead we call the usb_bulk_msg function, which can be used
+to send or receive data from a device without having to create urbs and
+handle urb completion callback functions. We call the usb_bulk_msg
+function, giving it a buffer into which to place any data received from
+the device and a timeout value. If the timeout period expires without
+receiving any data from the device, the function will fail and return an
+error message. This can be shown with the following code:
+
+::
+
+    /* do an immediate bulk read to get data from the device */
+    retval = usb_bulk_msg (skel->dev,
+                           usb_rcvbulkpipe (skel->dev,
+                           skel->bulk_in_endpointAddr),
+                           skel->bulk_in_buffer,
+                           skel->bulk_in_size,
+                           &count, HZ*10);
+    /* if the read was successful, copy the data to user space */
+    if (!retval) {
+            if (copy_to_user (buffer, skel->bulk_in_buffer, count))
+                    retval = -EFAULT;
+            else
+                    retval = count;
+    }
+
+
+The usb_bulk_msg function can be very useful for doing single reads or
+writes to a device; however, if you need to read or write constantly to
+a device, it is recommended to set up your own urbs and submit them to
+the USB subsystem.
+
+When the user program releases the file handle that it has been using to
+talk to the device, the release function in the driver is called. In
+this function we decrement our private usage count and wait for possible
+pending writes:
+
+::
+
+    /* decrement our usage count for the device */
+    --skel->open_count;
+
+
+One of the more difficult problems that USB drivers must be able to
+handle smoothly is the fact that the USB device may be removed from the
+system at any point in time, even if a program is currently talking to
+it. It needs to be able to shut down any current reads and writes and
+notify the user-space programs that the device is no longer there. The
+following code (function :c:func:`skel_delete()`) is an example of
+how to do this:
+
+::
+
+    static inline void skel_delete (struct usb_skel *dev)
+    {
+        kfree (dev->bulk_in_buffer);
+        if (dev->bulk_out_buffer != NULL)
+            usb_free_coherent (dev->udev, dev->bulk_out_size,
+                dev->bulk_out_buffer,
+                dev->write_urb->transfer_dma);
+        usb_free_urb (dev->write_urb);
+        kfree (dev);
+    }
+
+
+If a program currently has an open handle to the device, we reset the
+flag ``device_present``. For every read, write, release and other
+functions that expect a device to be present, the driver first checks
+this flag to see if the device is still present. If not, it releases
+that the device has disappeared, and a -ENODEV error is returned to the
+user-space program. When the release function is eventually called, it
+determines if there is no device and if not, it does the cleanup that
+the skel_disconnect function normally does if there are no open files
+on the device (see Listing 5).
+
+Isochronous Data
+================
+
+This usb-skeleton driver does not have any examples of interrupt or
+isochronous data being sent to or from the device. Interrupt data is
+sent almost exactly as bulk data is, with a few minor exceptions.
+Isochronous data works differently with continuous streams of data being
+sent to or from the device. The audio and video camera drivers are very
+good examples of drivers that handle isochronous data and will be useful
+if you also need to do this.
+
+Conclusion
+==========
+
+Writing Linux USB device drivers is not a difficult task as the
+usb-skeleton driver shows. This driver, combined with the other current
+USB drivers, should provide enough examples to help a beginning author
+create a working driver in a minimal amount of time. The linux-usb-devel
+mailing list archives also contain a lot of helpful information.
+
+Resources
+=========
+
+The Linux USB Project:
+`http://www.linux-usb.org/ <http://www.linux-usb.org>`__
+
+Linux Hotplug Project:
+`http://linux-hotplug.sourceforge.net/ <http://linux-hotplug.sourceforge.net>`__
+
+Linux USB Working Devices List:
+`http://www.qbik.ch/usb/devices/ <http://www.qbik.ch/usb/devices>`__
+
+linux-usb-devel Mailing List Archives:
+http://marc.theaimsgroup.com/?l=linux-usb-devel
+
+Programming Guide for Linux USB Device Drivers:
+http://usb.cs.tum.edu/usbdoc
+
+USB Home Page: http://www.usb.org
-- 
2.9.3




More information about the linux-rpi-kernel mailing list