Documentation/DocBook/gadget.tmpl

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
5 <book id="USB-Gadget-API">
31 	 MA 02111-1307 USA
40       <year>2003-2004</year>
57 <para>This document presents a Linux-USB "Gadget"
71 	well as ones with just two fixed-function ones.  Gadget drivers
79     <listitem><para>USB "On-The-Go" (OTG) support, in conjunction
80 	with updates to the Linux-USB host side.
83 	Linux-USB host side API.  This helps the OTG support, and
84 	looks forward to more-symmetric frameworks (where the same
108 <para>The gadget API resembles the host side Linux-USB API in that both
118 management is necessarily different (one side is a hardware-neutral master,
119 the other is a hardware-aware slave), the endpoint I/0 API used here
120 should also be usable for an overhead-reduced host side API.
159 	the PCI-based NetChip 2280 USB 2.0 high speed controller,
160 	the SA-11x0 or PXA-25x UDC (found within many PDAs),
170 	<para>The lower boundary of this driver implements hardware-neutral
180 	endpoints automatically for many bulk-oriented drivers.)
185 		possibly including class-specific functionality
235 	    <listitem><para>block i/o subsystem (for usb-storage gadgets)
260 <para>OTG-capable systems will also need to include a standard Linux-USB
273 more battery-friendly kind of device wakeup protocol.
284 is code implementing standard USB-IF protocols for
288 Most such USB protocol code doesn't need to be hardware-specific,
290 Such gadget-side interface drivers should eventually be combined,
314 and in-code comments into SGML DocBook and then into usable
340 <para>The core API does not expose
342 There are significant hardware features, such as device-to-device DMA
344 that would be added using hardware-specific APIs.
353 The API supports limited run-time
364 <para>Like the Linux-USB host side API, this API exposes
367 Compared to RS-232 serial protocols, USB resembles
374 two single byte writes into a single two-byte USB IN packet,
469 configuration, only the HNP-related differences are particularly
494 <sect1 id="core"><title>Core Objects and Methods</title>
502 	<!-- yeech, this is ugly in nsgmls PDF output.
510 	  -->
517 <para>The core API is sufficient for writing a USB Gadget Driver,
524 <!-- !Edrivers/usb/gadget/epautoconf.c -->
529 <para>The core API is sufficient for writing drivers for composite
531 and also multi-configuration devices (also more than one function,
556 Near-term plans include converting all of them, except for "gadgetfs".
583 Toshiba TC86c001 "Goku-S" (<filename>goku_udc</filename>),
599 <!-- !Edrivers/usb/gadget/net2280.c -->
673 as MS-Windows and MacOS.
674 That <emphasis>File-backed Storage</emphasis> driver uses a
686 interoperate easily with MS-Windows.
699 <chapter id="otg"><title>USB On-The-GO (OTG)</title>
710 notably including a special <emphasis>Mini-AB</emphasis> jack
711 and associated transciever to support <emphasis>Dual-Role</emphasis>
714 Linux-USB host side driver stack,
720 In each role, the system can re-use the existing pool of
721 hardware-neutral drivers, layered on top of the controller
725 added to support OTG can also benefit non-OTG products.
739 	SRP support can be user-initiated just like remote wakeup,
746 	for non-OTG configurations.
752 	<emphasis>This whitelist is product-specific;
757 	<para>Non-OTG Linux hosts, like PCs and workstations,
771 Additional changes are needed below those hardware-neutral
774 Those affect the hardware-specific code for each USB Host or Peripheral
784 can identify OTG-capable devices and respond appropriately
791 <!--
793 -->