diff options
Diffstat (limited to 'Documentation/DocBook/gadget.tmpl')
| -rw-r--r-- | Documentation/DocBook/gadget.tmpl | 793 |
1 files changed, 0 insertions, 793 deletions
diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl deleted file mode 100644 index 641629221176..000000000000 --- a/Documentation/DocBook/gadget.tmpl +++ /dev/null @@ -1,793 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="USB-Gadget-API"> - <bookinfo> - <title>USB Gadget API for Linux</title> - <date>20 August 2004</date> - <edition>20 August 2004</edition> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - <copyright> - <year>2003-2004</year> - <holder>David Brownell</holder> - </copyright> - - <author> - <firstname>David</firstname> - <surname>Brownell</surname> - <affiliation> - <address><email>dbrownell@users.sourceforge.net</email></address> - </affiliation> - </author> - </bookinfo> - -<toc></toc> - -<chapter id="intro"><title>Introduction</title> - -<para>This document presents a Linux-USB "Gadget" -kernel mode -API, for use within peripherals and other USB devices -that embed Linux. -It provides an overview of the API structure, -and shows how that fits into a system development project. -This is the first such API released on Linux to address -a number of important problems, including: </para> - -<itemizedlist> - <listitem><para>Supports USB 2.0, for high speed devices which - can stream data at several dozen megabytes per second. - </para></listitem> - <listitem><para>Handles devices with dozens of endpoints just as - well as ones with just two fixed-function ones. Gadget drivers - can be written so they're easy to port to new hardware. - </para></listitem> - <listitem><para>Flexible enough to expose more complex USB device - capabilities such as multiple configurations, multiple interfaces, - composite devices, - and alternate interface settings. - </para></listitem> - <listitem><para>USB "On-The-Go" (OTG) support, in conjunction - with updates to the Linux-USB host side. - </para></listitem> - <listitem><para>Sharing data structures and API models with the - Linux-USB host side API. This helps the OTG support, and - looks forward to more-symmetric frameworks (where the same - I/O model is used by both host and device side drivers). - </para></listitem> - <listitem><para>Minimalist, so it's easier to support new device - controller hardware. I/O processing doesn't imply large - demands for memory or CPU resources. - </para></listitem> -</itemizedlist> - - -<para>Most Linux developers will not be able to use this API, since they -have USB "host" hardware in a PC, workstation, or server. -Linux users with embedded systems are more likely to -have USB peripheral hardware. -To distinguish drivers running inside such hardware from the -more familiar Linux "USB device drivers", -which are host side proxies for the real USB devices, -a different term is used: -the drivers inside the peripherals are "USB gadget drivers". -In USB protocol interactions, the device driver is the master -(or "client driver") -and the gadget driver is the slave (or "function driver"). -</para> - -<para>The gadget API resembles the host side Linux-USB API in that both -use queues of request objects to package I/O buffers, and those requests -may be submitted or canceled. -They share common definitions for the standard USB -<emphasis>Chapter 9</emphasis> messages, structures, and constants. -Also, both APIs bind and unbind drivers to devices. -The APIs differ in detail, since the host side's current -URB framework exposes a number of implementation details -and assumptions that are inappropriate for a gadget API. -While the model for control transfers and configuration -management is necessarily different (one side is a hardware-neutral master, -the other is a hardware-aware slave), the endpoint I/0 API used here -should also be usable for an overhead-reduced host side API. -</para> - -</chapter> - -<chapter id="structure"><title>Structure of Gadget Drivers</title> - -<para>A system running inside a USB peripheral -normally has at least three layers inside the kernel to handle -USB protocol processing, and may have additional layers in -user space code. -The "gadget" API is used by the middle layer to interact -with the lowest level (which directly handles hardware). -</para> - -<para>In Linux, from the bottom up, these layers are: -</para> - -<variablelist> - - <varlistentry> - <term><emphasis>USB Controller Driver</emphasis></term> - - <listitem> - <para>This is the lowest software level. - It is the only layer that talks to hardware, - through registers, fifos, dma, irqs, and the like. - The <filename><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 ---> |