1<html><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.78.1"><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="intro.html" title="Chapter 1. Introduction"><link rel="next" href="api.html" title="Chapter 3. Kernel Mode Gadget API"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><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="intro.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="structure"></a>Chapter 2. Structure of Gadget Drivers</h1></div></div></div><p>A system running inside a USB peripheral 2normally has at least three layers inside the kernel to handle 3USB protocol processing, and may have additional layers in 4user space code. 5The "gadget" API is used by the middle layer to interact 6with the lowest level (which directly handles hardware). 7</p><p>In Linux, from the bottom up, these layers are: 8</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="emphasis"><em>USB Controller Driver</em></span></span></dt><dd><p>This is the lowest software level. 9 It is the only layer that talks to hardware, 10 through registers, fifos, dma, irqs, and the like. 11 The <code class="filename"><linux/usb/gadget.h></code> API abstracts 12 the peripheral controller endpoint hardware. 13 That hardware is exposed through endpoint objects, which accept 14 streams of IN/OUT buffers, and through callbacks that interact 15 with gadget drivers. 16 Since normal USB devices only have one upstream 17 port, they only have one of these drivers. 18 The controller driver can support any number of different 19 gadget drivers, but only one of them can be used at a time. 20 </p><p>Examples of such controller hardware include 21 the PCI-based NetChip 2280 USB 2.0 high speed controller, 22 the SA-11x0 or PXA-25x UDC (found within many PDAs), 23 and a variety of other products. 24 </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 25 USB functions, using calls to the controller driver. 26 Because such hardware varies widely in capabilities and restrictions, 27 and is used in embedded environments where space is at a premium, 28 the gadget driver is often configured at compile time 29 to work with endpoints supported by one particular controller. 30 Gadget drivers may be portable to several different controllers, 31 using conditional compilation. 32 (Recent kernels substantially simplify the work involved in 33 supporting new hardware, by <span class="emphasis"><em>autoconfiguring</em></span> 34 endpoints automatically for many bulk-oriented drivers.) 35 Gadget driver responsibilities include: 36 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>handling setup requests (ep0 protocol responses) 37 possibly including class-specific functionality 38 </p></li><li class="listitem"><p>returning configuration and string descriptors 39 </p></li><li class="listitem"><p>(re)setting configurations and interface 40 altsettings, including enabling and configuring endpoints 41 </p></li><li class="listitem"><p>handling life cycle events, such as managing 42 bindings to hardware, 43 USB suspend/resume, remote wakeup, 44 and disconnection from the USB host. 45 </p></li><li class="listitem"><p>managing IN and OUT transfers on all currently 46 enabled endpoints 47 </p></li></ul></div><p> 48 Such drivers may be modules of proprietary code, although 49 that approach is discouraged in the Linux community. 50 </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 51 to some Linux driver or framework in Linux. 52 Through that boundary flows the data which the gadget driver 53 produces and/or consumes through protocol transfers over USB. 54 Examples include: 55 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>user mode code, using generic (gadgetfs) 56 or application specific files in 57 <code class="filename">/dev</code> 58 </p></li><li class="listitem"><p>networking subsystem (for network gadgets, 59 like the CDC Ethernet Model gadget driver) 60 </p></li><li class="listitem"><p>data capture drivers, perhaps video4Linux or 61 a scanner driver; or test and measurement hardware. 62 </p></li><li class="listitem"><p>input subsystem (for HID gadgets) 63 </p></li><li class="listitem"><p>sound subsystem (for audio gadgets) 64 </p></li><li class="listitem"><p>file system (for PTP gadgets) 65 </p></li><li class="listitem"><p>block i/o subsystem (for usb-storage gadgets) 66 </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. 67 These could include kernel layers, such as network protocol stacks, 68 as well as user mode applications building on standard POSIX 69 system call APIs such as 70 <span class="emphasis"><em>open()</em></span>, <span class="emphasis"><em>close()</em></span>, 71 <span class="emphasis"><em>read()</em></span> and <span class="emphasis"><em>write()</em></span>. 72 On newer systems, POSIX Async I/O calls may be an option. 73 Such user mode code will not necessarily be subject to 74 the GNU General Public License (GPL). 75 </p></dd></dl></div><p>OTG-capable systems will also need to include a standard Linux-USB 76host side stack, 77with <span class="emphasis"><em>usbcore</em></span>, 78one or more <span class="emphasis"><em>Host Controller Drivers</em></span> (HCDs), 79<span class="emphasis"><em>USB Device Drivers</em></span> to support 80the OTG "Targeted Peripheral List", 81and so forth. 82There will also be an <span class="emphasis"><em>OTG Controller Driver</em></span>, 83which is visible to gadget and device driver developers only indirectly. 84That helps the host and device side USB controllers implement the 85two new OTG protocols (HNP and SRP). 86Roles switch (host to peripheral, or vice versa) using HNP 87during USB suspend processing, and SRP can be viewed as a 88more battery-friendly kind of device wakeup protocol. 89</p><p>Over time, reusable utilities are evolving to help make some 90gadget driver tasks simpler. 91For example, building configuration descriptors from vectors of 92descriptors for the configurations interfaces and endpoints is 93now automated, and many drivers now use autoconfiguration to 94choose hardware endpoints and initialize their descriptors. 95 96A potential example of particular interest 97is code implementing standard USB-IF protocols for 98HID, networking, storage, or audio classes. 99Some developers are interested in KDB or KGDB hooks, to let 100target hardware be remotely debugged. 101Most such USB protocol code doesn't need to be hardware-specific, 102any more than network protocols like X11, HTTP, or NFS are. 103Such gadget-side interface drivers should eventually be combined, 104to implement composite devices. 105</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="api.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> 106