<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>Chapter 2. Structure of Gadget Drivers</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="USB Gadget API for Linux" /><link rel="up" href="index.html" title="USB Gadget API for Linux" /><link rel="prev" href="ch01.html" title="Chapter 1. Introduction" /><link rel="next" href="ch03.html" title="Chapter 3. Kernel Mode Gadget API" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Structure of Gadget Drivers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch01.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch03.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 2. Structure of Gadget Drivers"><div class="titlepage"><div><div><h2 class="title"><a id="structure"></a>Chapter 2. Structure of Gadget Drivers</h2></div></div></div><p>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). </p><p>In Linux, from the bottom up, these layers are: </p><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>USB Controller Driver</em></span></span></dt><dd><p>This is the lowest software level. It is the only layer that talks to hardware, through registers, fifos, dma, irqs, and the like. The <code class="filename"><linux/usb/gadget.h></code> 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. </p><p>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. </p></dd><dt><span class="term"><span class="emphasis"><em>Gadget Driver</em></span></span></dt><dd><p>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 <span class="emphasis"><em>autoconfiguring</em></span> endpoints automatically for many bulk-oriented drivers.) Gadget driver responsibilities include: </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>handling setup requests (ep0 protocol responses) possibly including class-specific functionality </p></li><li class="listitem"><p>returning configuration and string descriptors </p></li><li class="listitem"><p>(re)setting configurations and interface altsettings, including enabling and configuring endpoints </p></li><li class="listitem"><p>handling life cycle events, such as managing bindings to hardware, USB suspend/resume, remote wakeup, and disconnection from the USB host. </p></li><li class="listitem"><p>managing IN and OUT transfers on all currently enabled endpoints </p></li></ul></div><p> Such drivers may be modules of proprietary code, although that approach is discouraged in the Linux community. </p></dd><dt><span class="term"><span class="emphasis"><em>Upper Level</em></span></span></dt><dd><p>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: </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>user mode code, using generic (gadgetfs) or application specific files in <code class="filename">/dev</code> </p></li><li class="listitem"><p>networking subsystem (for network gadgets, like the CDC Ethernet Model gadget driver) </p></li><li class="listitem"><p>data capture drivers, perhaps video4Linux or a scanner driver; or test and measurement hardware. </p></li><li class="listitem"><p>input subsystem (for HID gadgets) </p></li><li class="listitem"><p>sound subsystem (for audio gadgets) </p></li><li class="listitem"><p>file system (for PTP gadgets) </p></li><li class="listitem"><p>block i/o subsystem (for usb-storage gadgets) </p></li><li class="listitem"><p>... and more </p></li></ul></div></dd><dt><span class="term"><span class="emphasis"><em>Additional Layers</em></span></span></dt><dd><p>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 <span class="emphasis"><em>open()</em></span>, <span class="emphasis"><em>close()</em></span>, <span class="emphasis"><em>read()</em></span> and <span class="emphasis"><em>write()</em></span>. 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). </p></dd></dl></div><p>OTG-capable systems will also need to include a standard Linux-USB host side stack, with <span class="emphasis"><em>usbcore</em></span>, one or more <span class="emphasis"><em>Host Controller Drivers</em></span> (HCDs), <span class="emphasis"><em>USB Device Drivers</em></span> to support the OTG "Targeted Peripheral List", and so forth. There will also be an <span class="emphasis"><em>OTG Controller Driver</em></span>, 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. </p><p>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. </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Kernel Mode Gadget API</td></tr></table></div></body></html>
