Merge tag 'docs-4.12' of git://git.lwn.net/linux

c58d4055 · Linus Torvalds <[email protected]> · 2017-05-02 10:21:17 -07:00

Pull documentation update from Jonathan Corbet:
 "A reasonably busy cycle for documentation this time around. There is a
  new guide for user-space API documents, rather sparsely populated at
  the moment, but it's a start. Markus improved the infrastructure for
  converting diagrams. Mauro has converted much of the USB documentation
  over to RST. Plus the usual set of fixes, improvements, and tweaks.

  There's a bit more than the usual amount of reaching out of
  Documentation/ to fix comments elsewhere in the tree; I have acks for
  those where I could get them"

* tag 'docs-4.12' of git://git.lwn.net/linux: (74 commits)
  docs: Fix a couple typos
  docs: Fix a spelling error in vfio-mediated-device.txt
  docs: Fix a spelling error in ioctl-number.txt
  MAINTAINERS: update file entry for HSI subsystem
  Documentation: allow installing man pages to a user defined directory
  Doc/PM: Sync with intel_powerclamp code behavior
  zr364xx.rst: usb/devices is now at /sys/kernel/debug/
  usb.rst: move documentation from proc_usb_info.txt to USB ReST book
  convert philips.txt to ReST and add to media docs
  docs-rst: usb: update old usbfs-related documentation
  arm: Documentation: update a path name
  docs: process/4.Coding.rst: Fix a couple of document refs
  docs-rst: fix usb cross-references
  usb: gadget.h: be consistent at kernel doc macros
  usb: composite.h: fix two warnings when building docs
  usb: get rid of some ReST doc build errors
  usb.rst: get rid of some Sphinx errors
  usb/URB.txt: convert to ReST and update it
  usb/persist.txt: convert to ReST and add to driver-api book
  usb/hotplug.txt: convert to ReST and add to driver-api book
  ...

Commit: c58d4055c054fc6dc72f1be8bc71bd6fff209e48
Parents: ceb198bb · 9bb0e9cb

Merge commit. Changes below are compared with the first parent: ceb198bb.

Changes

134 files changed · +6626 −5932

File	Status	Add	Del	Content
Documentation/ABI/stable/sysfs-bus-usb	modified	+1	−1	View file
Documentation/ABI/stable/vdso	modified	+2	−1	View file
Documentation/ABI/testing/sysfs-bus-pci	modified	+1	−1	View file
Documentation/DocBook/Makefile	modified	+13	−9	View file
Documentation/DocBook/gadget.tmpl	deleted	+0	−793	View before deletion
Documentation/DocBook/genericirq.tmpl	deleted	+0	−520	View before deletion
Documentation/DocBook/kernel-api.tmpl	deleted	+0	−331	View before deletion
Documentation/DocBook/writing_musb_glue_layer.tmpl	deleted	+0	−873	View before deletion
Documentation/DocBook/writing_usb_driver.tmpl	deleted	+0	−412	View before deletion
Documentation/PCI/pci-error-recovery.txt	modified	+6	−6	View file
Documentation/acpi/aml-debugger.txt	modified	+1	−1	View file
Documentation/acpi/enumeration.txt	modified	+3	−3	View file
Documentation/admin-guide/index.rst	modified	+1	−0	View file
Documentation/admin-guide/kernel-parameters.rst	modified	+3	−1	View file
Documentation/admin-guide/pm/cpufreq.rst	added	+700	−0	View file
Documentation/admin-guide/pm/index.rst	added	+15	−0	View file
Documentation/admin-guide/ras.rst	modified	+6	−6	View file
Documentation/admin-guide/security-bugs.rst	modified	+34	−5	View file
Documentation/admin-guide/sysrq.rst	modified	+2	−1	View file
Documentation/arm/mem_alignment	modified	+1	−1	View file
Documentation/conf.py	modified	+3	−3	View file
Documentation/core-api/flexible-arrays.rst	added	+130	−0	View file
Documentation/core-api/genericirq.rst	added	+440	−0	View file
Documentation/core-api/index.rst	modified	+3	−0	View file
Documentation/core-api/kernel-api.rst	added	+346	−0	View file
Documentation/cpu-freq/boost.txt	deleted	+0	−93	View before deletion
Documentation/cpu-freq/cpu-drivers.txt	modified	+1	−1	View file
Documentation/cpu-freq/governors.txt	deleted	+0	−301	View before deletion
Documentation/cpu-freq/index.txt	modified	+0	−7	View file
Documentation/cpu-freq/user-guide.txt	deleted	+0	−228	View before deletion
Documentation/cputopology.txt	modified	+1	−1	View file
Documentation/debugging-via-ohci1394.txt	modified	+2	−2	View file
Documentation/device-mapper/cache.txt	modified	+1	−1	View file
Documentation/doc-guide/hello.dot	added	+3	−0	View file
Documentation/doc-guide/sphinx.rst	modified	+112	−3	View file
Documentation/doc-guide/svg_image.svg	added	+10	−0	View file
Documentation/driver-api/basics.rst	modified	+6	−0	View file
Documentation/driver-api/firmware/index.rst	modified	+1	−0	View file
Documentation/driver-api/firmware/other_interfaces.rst	added	+15	−0	View file
Documentation/driver-api/index.rst	modified	+3	−1	View file
Documentation/driver-api/misc_devices.rst	added	+5	−0	View file
Documentation/driver-api/pci.rst	added	+50	−0	View file
Documentation/driver-api/usb/URB.rst	added	+290	−0	View file
Documentation/usb/anchors.txt → Documentation/driver-api/usb/anchors.rst	renamed	+20	−16	View file
Documentation/usb/bulk-streams.txt → Documentation/driver-api/usb/bulk-streams.rst	renamed	+9	−4	View file
Documentation/usb/callbacks.txt → Documentation/driver-api/usb/callbacks.rst	renamed	+44	−21	View file
Documentation/usb/dma.txt → Documentation/driver-api/usb/dma.rst	renamed	+27	−24	View file
Documentation/driver-api/usb/error-codes.rst	added	+207	−0	View file
Documentation/driver-api/usb/gadget.rst	added	+510	−0	View file
Documentation/usb/hotplug.txt → Documentation/driver-api/usb/hotplug.rst	renamed	+37	−31	View file
Documentation/driver-api/usb/index.rst	added	+26	−0	View file
Documentation/usb/persist.txt → Documentation/driver-api/usb/persist.rst	renamed	+14	−8	View file
Documentation/usb/power-management.txt → Documentation/driver-api/usb/power-management.rst	renamed	+213	−191	View file
Documentation/driver-api/usb.rst → Documentation/driver-api/usb/usb.rst	renamed	+563	−264	View file
Documentation/driver-api/usb/writing_musb_glue_layer.rst	added	+723	−0	View file
Documentation/driver-api/usb/writing_usb_driver.rst	added	+326	−0	View file
Documentation/early-userspace/README	modified	+1	−1	View file
Documentation/filesystems/ext4.txt	modified	+1	−1	View file
Documentation/filesystems/nfs/nfs-rdma.txt	modified	+2	−2	View file
Documentation/hid/hidraw.txt	modified	+1	−1	View file
Documentation/index.rst	modified	+20	−0	View file
Documentation/input/ff.txt	modified	+3	−3	View file
Documentation/input/input-programming.txt	modified	+2	−2	View file
Documentation/ioctl/ioctl-number.txt	modified	+1	−1	View file
Documentation/leds/leds-lp55xx.txt	modified	+1	−1	View file
Documentation/md/md-cluster.txt	modified	+1	−1	View file
Documentation/media/Makefile	modified	+1	−46	View file
Documentation/media/intro.rst	modified	+3	−3	View file
Documentation/media/uapi/dvb/intro.rst	modified	+3	−3	View file
Documentation/media/uapi/v4l/crop.rst	modified	+2	−2	View file
Documentation/media/uapi/v4l/dev-raw-vbi.rst	modified	+9	−13	View file
Documentation/media/uapi/v4l/dev-subdev.rst	modified	+11	−11	View file
Documentation/media/uapi/v4l/field-order.rst	modified	+7	−4	View file
Documentation/media/uapi/v4l/pixfmt-nv12mt.rst	modified	+4	−4	View file
Documentation/media/uapi/v4l/selection-api-003.rst	modified	+3	−3	View file
Documentation/media/uapi/v4l/subdev-formats.rst	modified	+2	−2	View file
Documentation/media/v4l-drivers/index.rst	modified	+1	−0	View file
drivers/media/usb/pwc/philips.txt → Documentation/media/v4l-drivers/philips.rst	renamed	+15	−6	View file
Documentation/media/v4l-drivers/zr364xx.rst	modified	+1	−1	View file
Documentation/mmc/mmc-dev-attrs.txt	modified	+2	−2	View file
Documentation/networking/cdc_mbim.txt	modified	+1	−1	View file
Documentation/networking/e100.txt	modified	+1	−1	View file
Documentation/networking/e1000.txt	modified	+1	−1	View file
Documentation/networking/e1000e.txt	modified	+1	−1	View file
Documentation/networking/igb.txt	modified	+1	−1	View file
Documentation/networking/igbvf.txt	modified	+1	−1	View file
Documentation/networking/ixgb.txt	modified	+1	−1	View file
Documentation/networking/ixgbe.txt	modified	+1	−1	View file
Documentation/phy.txt	modified	+1	−1	View file
Documentation/power/swsusp.txt	modified	+1	−1	View file
Documentation/process/4.Coding.rst	modified	+9	−8	View file
Documentation/process/applying-patches.rst	modified	+3	−9	View file
Documentation/process/changes.rst	modified	+9	−8	View file
Documentation/sphinx/cdomain.py	modified	+1	−1	View file
Documentation/sphinx/kfigure.py	added	+551	−0	View file
Documentation/sphinx/tmplcvt	modified	+11	−2	View file
Documentation/static-keys.txt	modified	+1	−1	View file
Documentation/sync_file.txt	modified	+1	−1	View file
Documentation/thermal/intel_powerclamp.txt	modified	+15	−5	View file
Documentation/translations/ja_JP/HOWTO	deleted	+0	−637	View before deletion
Documentation/translations/ja_JP/howto.rst	added	+661	−0	View file
Documentation/translations/ja_JP/index.rst	added	+12	−0	View file
Documentation/translations/zh_CN/sparse.txt	modified	+2	−2	View file
Documentation/usb/URB.txt	deleted	+0	−261	View before deletion
Documentation/usb/acm.txt	modified	+1	−1	View file
Documentation/usb/error-codes.txt	deleted	+0	−175	View before deletion
Documentation/usb/gadget_serial.txt	modified	+2	−2	View file
Documentation/usb/proc_usb_info.txt	deleted	+0	−390	View before deletion
Documentation/userspace-api/conf.py	added	+10	−0	View file
Documentation/userspace-api/index.rst	added	+26	−0	View file
Documentation/unshare.txt → Documentation/userspace-api/unshare.rst	renamed	+116	−79	View file
Documentation/vfio-mediated-device.txt	modified	+4	−4	View file
Documentation/zorro.txt	modified	+1	−1	View file
MAINTAINERS	modified	+1	−1	View file
Makefile	modified	+2	−2	View file
block/genhd.c	modified	+4	−3	View file
drivers/pci/irq.c	modified	+1	−1	View file
drivers/staging/most/hdm-usb/hdm_usb.c	modified	+1	−1	View file
drivers/usb/core/Kconfig	modified	+1	−1	View file
drivers/usb/core/message.c	modified	+1	−0	View file
include/linux/clk.h	modified	+2	−2	View file
include/linux/flex_array.h	modified	+67	−0	View file
include/linux/usb/composite.h	modified	+4	−2	View file
include/linux/usb/gadget.h	modified	+1	−1	View file
ipc/util.c	modified	+7	−5	View file
lib/Kconfig.debug	modified	+5	−4	View file
lib/bitmap.c	modified	+17	−11	View file
lib/string.c	modified	+1	−1	View file
lib/vsprintf.c	modified	+3	−3	View file
mm/filemap.c	modified	+10	−8	View file
mm/page_alloc.c	modified	+2	−1	View file
mm/vmalloc.c	modified	+1	−1	View file
scripts/kernel-doc	modified	+14	−5	View file
security/security.c	modified	+8	−4	View file

Only the first 600 diff lines are shown. Download the complete patch.

Documentation/ABI/stable/sysfs-bus-usb

View file

diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb
index 831f15d..b832eef 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -9,7 +9,7 @@ Description:
 		hubs this facility is always enabled and their device
 		directories will not contain this file.
 
-		For more information, see Documentation/usb/persist.txt.
+		For more information, see Documentation/driver-api/usb/persist.rst.
 
 What:		/sys/bus/usb/devices/.../power/autosuspend
 Date:		March 2007

Documentation/ABI/stable/vdso

View file

diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso
index 7cdfc28..55406ec 100644
--- a/Documentation/ABI/stable/vdso
+++ b/Documentation/ABI/stable/vdso
@@ -16,7 +16,8 @@ The vDSO uses symbol versioning; whenever you request a symbol from the
 vDSO, specify the version you are expecting.
 
 Programs that dynamically link to glibc will use the vDSO automatically.
-Otherwise, you can use the reference parser in Documentation/vDSO/parse_vdso.c.
+Otherwise, you can use the reference parser in
+tools/testing/selftests/vDSO/parse_vdso.c.
 
 Unless otherwise noted, the set of symbols with any given version and the
 ABI of those symbols is considered stable.  It may vary across architectures,

Documentation/ABI/testing/sysfs-bus-pci

View file

diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci
index 5a1732b..e4e9010 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci
+++ b/Documentation/ABI/testing/sysfs-bus-pci
@@ -299,5 +299,5 @@ What:		/sys/bus/pci/devices/.../revision
 Date:		November 2016
 Contact:	Emil Velikov <[email protected]>
 Description:
-		This file contains the revision field of the the PCI device.
+		This file contains the revision field of the PCI device.
 		The value comes from device config space. The file is read only.

Documentation/DocBook/Makefile

View file

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 164c1c7..85916f1 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 \
-	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
-	    gadget.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
+	    networking.xml \
+	    filesystems.xml lsm.xml kgdb.xml \
+	    libata.xml mtdnand.xml librs.xml rapidio.xml \
+	    s390-drivers.xml scsi.xml \
+	    sh.xml w1.xml
 
 ifeq ($(DOCBOOKS),)
 
@@ -62,11 +61,14 @@ MAN := $(patsubst %.xml, %.9, $(BOOKS))
 mandocs: $(MAN)
 	find $(obj)/man -name '*.9' | xargs gzip -nf
 
+# Default location for installed man pages
+export INSTALL_MAN_PATH = $(objtree)/usr
+
 installmandocs: mandocs
-	mkdir -p /usr/local/man/man9/
+	mkdir -p $(INSTALL_MAN_PATH)/man/man9/
 	find $(obj)/man -name '*.9.gz' -printf '%h %f\n' | \
 		sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \
-		xargs install -m 644 -t /usr/local/man/man9/
+		xargs install -m 644 -t $(INSTALL_MAN_PATH)/man/man9/
 
 # no-op for the DocBook toolchain
 epubdocs:
@@ -238,7 +240,9 @@ dochelp:
 	@echo  '  psdocs          - Postscript'
 	@echo  '  xmldocs         - XML DocBook'
 	@echo  '  mandocs         - man pages'
-	@echo  '  installmandocs  - install man pages generated by mandocs'
+	@echo  '  installmandocs  - install man pages generated by mandocs to INSTALL_MAN_PATH'; \
+	 echo  '                    (default: $(INSTALL_MAN_PATH))'; \
+	 echo  ''
 	@echo  '  cleandocs       - clean all generated DocBook files'
 	@echo
 	@echo  '  make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml'

Documentation/DocBook/gadget.tmpl

View before deletion

diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl
deleted file mode 100644
index 6416292..0000000
--- 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>[email protected]</email></address>
-      </affiliation>
-    </author>
-  </bookinfo>
-
-<toc></toc>
-
-<chapter id="intro"><title>Introduction</title>
-
-<para>This document presents a Linux-USB "Gadget"
-kernel mode
-API, for use within peripherals and other USB devices
-that embed Linux.
-It provides an overview of the API structure,
-and shows how that fits into a system development project.
-This is the first such API released on Linux to address
-a number of important problems, including: </para>
-
-<itemizedlist>
-    <listitem><para>Supports USB 2.0, for high speed devices which
-	can stream data at several dozen megabytes per second.
-	</para></listitem>
-    <listitem><para>Handles devices with dozens of endpoints just as
-	well as ones with just two fixed-function ones.  Gadget drivers
-	can be written so they're easy to port to new hardware.
-	</para></listitem>
-    <listitem><para>Flexible enough to expose more complex USB device
-	capabilities such as multiple configurations, multiple interfaces,
-	composite devices,
-	and alternate interface settings.
-	</para></listitem>
-    <listitem><para>USB "On-The-Go" (OTG) support, in conjunction
-	with updates to the Linux-USB host side.
-	</para></listitem>
-    <listitem><para>Sharing data structures and API models with the
-	Linux-USB host side API.  This helps the OTG support, and
-	looks forward to more-symmetric frameworks (where the same
-	I/O model is used by both host and device side drivers).
-	</para></listitem>
-    <listitem><para>Minimalist, so it's easier to support new device
-	controller hardware.  I/O processing doesn't imply large
-	demands for memory or CPU resources.
-	</para></listitem>
-</itemizedlist>
-
-
-<para>Most Linux developers will not be able to use this API, since they
-have USB "host" hardware in a PC, workstation, or server.
-Linux users with embedded systems are more likely to
-have USB peripheral hardware.
-To distinguish drivers running inside such hardware from the
-more familiar Linux "USB device drivers",
-which are host side proxies for the real USB devices,
-a different term is used:
-the drivers inside the peripherals are "USB gadget drivers".
-In USB protocol interactions, the device driver is the master
-(or "client driver")
-and the gadget driver is the slave (or "function driver").
-</para>
-
-<para>The gadget API resembles the host side Linux-USB API in that both
-use queues of request objects to package I/O buffers, and those requests
-may be submitted or canceled.
-They share common definitions for the standard USB
-<emphasis>Chapter 9</emphasis> messages, structures, and constants.
-Also, both APIs bind and unbind drivers to devices.
-The APIs differ in detail, since the host side's current
-URB framework exposes a number of implementation details
-and assumptions that are inappropriate for a gadget API.
-While the model for control transfers and configuration
-management is necessarily different (one side is a hardware-neutral master,
-the other is a hardware-aware slave), the endpoint I/0 API used here
-should also be usable for an overhead-reduced host side API.
-</para>
-
-</chapter>
-
-<chapter id="structure"><title>Structure of Gadget Drivers</title>
-
-<para>A system running inside a USB peripheral
-normally has at least three layers inside the kernel to handle
-USB protocol processing, and may have additional layers in
-user space code.
-The "gadget" API is used by the middle layer to interact
-with the lowest level (which directly handles hardware).
-</para>
-
-<para>In Linux, from the bottom up, these layers are:
-</para>
-
-<variablelist>
-
-    <varlistentry>
-        <term><emphasis>USB Controller Driver</emphasis></term>
-
-	<listitem>
-	<para>This is the lowest software level.
-	It is the only layer that talks to hardware,
-	through registers, fifos, dma, irqs, and the like.
-	The <filename>&lt;linux/usb/gadget.h&gt;</filename> API abstracts
-	the peripheral controller endpoint hardware.
-	That hardware is exposed through endpoint objects, which accept
-	streams of IN/OUT buffers, and through callbacks that interact
-	with gadget drivers.
-	Since normal USB devices only have one upstream
-	port, they only have one of these drivers.
-	The controller driver can support any number of different
-	gadget drivers, but only one of them can be used at a time.
-	</para>
-
-	<para>Examples of such controller hardware include
-	the PCI-based NetChip 2280 USB 2.0 high speed controller,
-	the SA-11x0 or PXA-25x UDC (found within many PDAs),
-	and a variety of other products.
-	</para>
-
-	</listitem></varlistentry>
-
-    <varlistentry>
-	<term><emphasis>Gadget Driver</emphasis></term>
-
-	<listitem>
-	<para>The lower boundary of this driver implements hardware-neutral
-	USB functions, using calls to the controller driver.
-	Because such hardware varies widely in capabilities and restrictions,
-	and is used in embedded environments where space is at a premium,
-	the gadget driver is often configured at compile time
-	to work with endpoints supported by one particular controller.
-	Gadget drivers may be portable to several different controllers,
-	using conditional compilation.
-	(Recent kernels substantially simplify the work involved in
-	supporting new hardware, by <emphasis>autoconfiguring</emphasis>
-	endpoints automatically for many bulk-oriented drivers.)
-	Gadget driver responsibilities include:
-	</para>
-	<itemizedlist>
-	    <listitem><para>handling setup requests (ep0 protocol responses)
-		possibly including class-specific functionality
-		</para></listitem>
-	    <listitem><para>returning configuration and string descriptors
-		</para></listitem>
-	    <listitem><para>(re)setting configurations and interface
-		altsettings, including enabling and configuring endpoints
-		</para></listitem>
-	    <listitem><para>handling life cycle events, such as managing
-		bindings to hardware,
-		USB suspend/resume, remote wakeup,
-		and disconnection from the USB host.
-		</para></listitem>
-	    <listitem><para>managing IN and OUT transfers on all currently
-		enabled endpoints
-		</para></listitem>
-	</itemizedlist>
-
-	<para>
-	Such drivers may be modules of proprietary code, although
-	that approach is discouraged in the Linux community.
-	</para>
-	</listitem></varlistentry>
-
-    <varlistentry>
-	<term><emphasis>Upper Level</emphasis></term>
-
-	<listitem>
-	<para>Most gadget drivers have an upper boundary that connects
-	to some Linux driver or framework in Linux.
-	Through that boundary flows the data which the gadget driver
-	produces and/or consumes through protocol transfers over USB.
-	Examples include:
-	</para>
-	<itemizedlist>
-	    <listitem><para>user mode code, using generic (gadgetfs)
-	        or application specific files in
-		<filename>/dev</filename>
-		</para></listitem>
-	    <listitem><para>networking subsystem (for network gadgets,
-		like the CDC Ethernet Model gadget driver)
-		</para></listitem>
-	    <listitem><para>data capture drivers, perhaps video4Linux or
-		 a scanner driver; or test and measurement hardware.
-		 </para></listitem>
-	    <listitem><para>input subsystem (for HID gadgets)
-		</para></listitem>
-	    <listitem><para>sound subsystem (for audio gadgets)
-		</para></listitem>
-	    <listitem><para>file system (for PTP gadgets)
-		</para></listitem>
-	    <listitem><para>block i/o subsystem (for usb-storage gadgets)
-		</para></listitem>
-	    <listitem><para>... and more </para></listitem>
-	</itemizedlist>
-	</listitem></varlistentry>
-
-    <varlistentry>
-	<term><emphasis>Additional Layers</emphasis></term>
-
-	<listitem>
-	<para>Other layers may exist.
-	These could include kernel layers, such as network protocol stacks,
-	as well as user mode applications building on standard POSIX
-	system call APIs such as
-	<emphasis>open()</emphasis>, <emphasis>close()</emphasis>,
-	<emphasis>read()</emphasis> and <emphasis>write()</emphasis>.
-	On newer systems, POSIX Async I/O calls may be an option.
-	Such user mode code will not necessarily be subject to
-	the GNU General Public License (GPL).
-	</para>
-	</listitem></varlistentry>
-
-
-</variablelist>
-
-<para>OTG-capable systems will also need to include a standard Linux-USB
-host side stack,
-with <emphasis>usbcore</emphasis>,
-one or more <emphasis>Host Controller Drivers</emphasis> (HCDs),
-<emphasis>USB Device Drivers</emphasis> to support
-the OTG "Targeted Peripheral List",
-and so forth.
-There will also be an <emphasis>OTG Controller Driver</emphasis>,
-which is visible to gadget and device driver developers only indirectly.
-That helps the host and device side USB controllers implement the
-two new OTG protocols (HNP and SRP).
-Roles switch (host to peripheral, or vice versa) using HNP
-during USB suspend processing, and SRP can be viewed as a
-more battery-friendly kind of device wakeup protocol.
-</para>
-
-<para>Over time, reusable utilities are evolving to help make some
-gadget driver tasks simpler.
-For example, building configuration descriptors from vectors of
-descriptors for the configurations interfaces and endpoints is
-now automated, and many drivers now use autoconfiguration to
-choose hardware endpoints and initialize their descriptors.
-
-A potential example of particular interest
-is code implementing standard USB-IF protocols for
-HID, networking, storage, or audio classes.
-Some developers are interested in KDB or KGDB hooks, to let
-target hardware be remotely debugged.
-Most such USB protocol code doesn't need to be hardware-specific,
-any more than network protocols like X11, HTTP, or NFS are.
-Such gadget-side interface drivers should eventually be combined,
-to implement composite devices.
-</para>
-
-</chapter>
-
-
-<chapter id="api"><title>Kernel Mode Gadget API</title>
-
-<para>Gadget drivers declare themselves through a
-<emphasis>struct usb_gadget_driver</emphasis>, which is responsible for
-most parts of enumeration for a <emphasis>struct usb_gadget</emphasis>.
-The response to a set_configuration usually involves
-enabling one or more of the <emphasis>struct usb_ep</emphasis> objects
-exposed by the gadget, and submitting one or more
-<emphasis>struct usb_request</emphasis> buffers to transfer data.
-Understand those four data types, and their operations, and
-you will understand how this API works.
-</para> 
-
-<note><title>Incomplete Data Type Descriptions</title>
-
-<para>This documentation was prepared using the standard Linux
-kernel <filename>docproc</filename> tool, which turns text
-and in-code comments into SGML DocBook and then into usable
-formats such as HTML or PDF.
-Other than the "Chapter 9" data types, most of the significant
-data types and functions are described here.
-</para>
-
-<para>However, docproc does not understand all the C constructs
-that are used, so some relevant information is likely omitted from
-what you are reading.  
-One example of such information is endpoint autoconfiguration.
-You'll have to read the header file, and use example source
-code (such as that for "Gadget Zero"), to fully understand the API.
-</para>
-
-<para>The part of the API implementing some basic
-driver capabilities is specific to the version of the
-Linux kernel that's in use.
-The 2.6 kernel includes a <emphasis>driver model</emphasis>
-framework that has no analogue on earlier kernels;
-so those parts of the gadget API are not fully portable.
-(They are implemented on 2.4 kernels, but in a different way.)
-The driver model state is another part of this API that is
-ignored by the kerneldoc tools.
-</para>
-</note>
-
-<para>The core API does not expose
-every possible hardware feature, only the most widely available ones.
-There are significant hardware features, such as device-to-device DMA
-(without temporary storage in a memory buffer)
-that would be added using hardware-specific APIs.
-</para>
-
-<para>This API allows drivers to use conditional compilation to handle
-endpoint capabilities of different hardware, but doesn't require that.
-Hardware tends to have arbitrary restrictions, relating to
-transfer types, addressing, packet sizes, buffering, and availability.
-As a rule, such differences only matter for "endpoint zero" logic
-that handles device configuration and management.
-The API supports limited run-time
-detection of capabilities, through naming conventions for endpoints.
-Many drivers will be able to at least partially autoconfigure
-themselves.
-In particular, driver init sections will often have endpoint
-autoconfiguration logic that scans the hardware's list of endpoints
-to find ones matching the driver requirements
-(relying on those conventions), to eliminate some of the most
-common reasons for conditional compilation.
-</para>
-
-<para>Like the Linux-USB host side API, this API exposes
-the "chunky" nature of USB messages:  I/O requests are in terms
-of one or more "packets", and packet boundaries are visible to drivers.
-Compared to RS-232 serial protocols, USB resembles
-synchronous protocols like HDLC
-(N bytes per frame, multipoint addressing, host as the primary
-station and devices as secondary stations)
-more than asynchronous ones
-(tty style:  8 data bits per frame, no parity, one stop bit).
-So for example the controller drivers won't buffer
-two single byte writes into a single two-byte USB IN packet,
-although gadget drivers may do so when they implement
-protocols where packet boundaries (and "short packets")
-are not significant.
-</para>
-
-<sect1 id="lifecycle"><title>Driver Life Cycle</title>
-
-<para>Gadget drivers make endpoint I/O requests to hardware without
-needing to know many details of the hardware, but driver
-setup/configuration code needs to handle some differences.
-Use the API like this:
-</para>
-
-<orderedlist numeration='arabic'>
-
-<listitem><para>Register a driver for the particular device side
-usb controller hardware,
-such as the net2280 on PCI (USB 2.0),
-sa11x0 or pxa25x as found in Linux PDAs,
-and so on.
-At this point the device is logically in the USB ch9 initial state
-("attached"), drawing no power and not usable
-(since it does not yet support enumeration).
-Any host should not see the device, since it's not
-activated the data line pullup used by the host to
-detect a device, even if VBUS power is available.
-</para></listitem>
-
-<listitem><para>Register a gadget driver that implements some higher level
-device function.  That will then bind() to a usb_gadget, which
-activates the data line pullup sometime after detecting VBUS.
-</para></listitem>
-
-<listitem><para>The hardware driver can now start enumerating.
-The steps it handles are to accept USB power and set_address requests.
-Other steps are handled by the gadget driver.
-If the gadget driver module is unloaded before the host starts to
-enumerate, steps before step 7 are skipped.
-</para></listitem>
-
-<listitem><para>The gadget driver's setup() call returns usb descriptors,
-based both on what the bus interface hardware provides and on the
-functionality being implemented.
-That can involve alternate settings or configurations,
-unless the hardware prevents such operation.
-For OTG devices, each configuration descriptor includes
-an OTG descriptor.
-</para></listitem>
-
-<listitem><para>The gadget driver handles the last step of enumeration,
-when the USB host issues a set_configuration call.
-It enables all endpoints used in that configuration,
-with all interfaces in their default settings.
-That involves using a list of the hardware's endpoints, enabling each
-endpoint according to its descriptor.
-It may also involve using <function>usb_gadget_vbus_draw</function>
-to let more power be drawn from VBUS, as allowed by that configuration.
-For OTG devices, setting a configuration may also involve reporting
-HNP capabilities through a user interface.
-</para></listitem>
-
-<listitem><para>Do real work and perform data transfers, possibly involving
-changes to interface settings or switching to new configurations, until the
-device is disconnect()ed from the host.
-Queue any number of transfer requests to each endpoint.
-It may be suspended and resumed several times before being disconnected.
-On disconnect, the drivers go back to step 3 (above).
-</para></listitem>
-
-<listitem><para>When the gadget driver module is being unloaded,
-the driver unbind() callback is issued.  That lets the controller
-driver be unloaded.
-</para></listitem>
-
-</orderedlist>
-
-<para>Drivers will normally be arranged so that just loading the
-gadget driver module (or statically linking it into a Linux kernel)
-allows the peripheral device to be enumerated, but some drivers
-will defer enumeration until some higher level component (like
-a user mode daemon) enables it.
-Note that at this lowest level there are no policies about how
-ep0 configuration logic is implemented,
-except that it should obey USB specifications.
-Such issues are in the domain of gadget drivers,
-including knowing about implementation constraints
-imposed by some USB controllers
-or understanding that composite devices might happen to
-be built by integrating reusable components.
-</para>
-
-<para>Note that the lifecycle above can be slightly different
-for OTG devices.
-Other than providing an additional OTG descriptor in each
-configuration, only the HNP-related differences are particularly
-visible to driver code.
-They involve reporting requirements during the SET_CONFIGURATION
-request, and the option to invoke HNP during some suspend callbacks.
-Also, SRP changes the semantics of
-<function>usb_gadget_wakeup</function>
-slightly.
-</para>
-
-</sect1>
-
-<sect1 id="ch9"><title>USB 2.0 Chapter 9 Types and Constants</title>
-
-<para>Gadget drivers
-rely on common USB structures and constants
-defined in the
-<filename>&lt;linux/usb/ch9.h&gt;</filename>
-header file, which is standard in Linux 2.6 kernels.
-These are the same types and constants used by host
-side drivers (and usbcore).
-</para>
-
-!Iinclude/linux/usb/ch9.h
-</sect1>
-
-<sect1 id="core"><title>Core Objects and Methods</title>
-
-<para>These are declared in
-<filename>&lt;linux/usb/gadget.h&gt;</filename>,
-and are used by gadget drivers to interact with
-USB peripheral controller drivers.
-</para>
-
-	<!-- yeech, this is ugly in nsgmls PDF output.
-
-	     the PDF bookmark and refentry output nesting is wrong,
-	     and the member/argument documentation indents ugly.
-