1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 3. Kernel Mode Gadget API</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="structure.html" title="Chapter 2. Structure of Gadget Drivers"><link rel="next" href="ch9.html" title="USB 2.0 Chapter 9 Types and Constants"></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 3. Kernel Mode Gadget API</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="structure.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch9.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="api"></a>Chapter 3. Kernel Mode Gadget API</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="api.html#lifecycle">Driver Life Cycle</a></span></dt><dt><span class="sect1"><a href="ch9.html">USB 2.0 Chapter 9 Types and Constants</a></span></dt><dt><span class="sect1"><a href="core.html">Core Objects and Methods</a></span></dt><dt><span class="sect1"><a href="utils.html">Optional Utilities</a></span></dt><dt><span class="sect1"><a href="composite.html">Composite Device Framework</a></span></dt><dt><span class="sect1"><a href="functions.html">Composite Device Functions</a></span></dt></dl></div><p>Gadget drivers declare themselves through a 2<span class="emphasis"><em>struct usb_gadget_driver</em></span>, which is responsible for 3most parts of enumeration for a <span class="emphasis"><em>struct usb_gadget</em></span>. 4The response to a set_configuration usually involves 5enabling one or more of the <span class="emphasis"><em>struct usb_ep</em></span> objects 6exposed by the gadget, and submitting one or more 7<span class="emphasis"><em>struct usb_request</em></span> buffers to transfer data. 8Understand those four data types, and their operations, and 9you will understand how this API works. 10</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Incomplete Data Type Descriptions</h3><p>This documentation was prepared using the standard Linux 11kernel <code class="filename">docproc</code> tool, which turns text 12and in-code comments into SGML DocBook and then into usable 13formats such as HTML or PDF. 14Other than the "Chapter 9" data types, most of the significant 15data types and functions are described here. 16</p><p>However, docproc does not understand all the C constructs 17that are used, so some relevant information is likely omitted from 18what you are reading. 19One example of such information is endpoint autoconfiguration. 20You'll have to read the header file, and use example source 21code (such as that for "Gadget Zero"), to fully understand the API. 22</p><p>The part of the API implementing some basic 23driver capabilities is specific to the version of the 24Linux kernel that's in use. 25The 2.6 kernel includes a <span class="emphasis"><em>driver model</em></span> 26framework that has no analogue on earlier kernels; 27so those parts of the gadget API are not fully portable. 28(They are implemented on 2.4 kernels, but in a different way.) 29The driver model state is another part of this API that is 30ignored by the kerneldoc tools. 31</p></div><p>The core API does not expose 32every possible hardware feature, only the most widely available ones. 33There are significant hardware features, such as device-to-device DMA 34(without temporary storage in a memory buffer) 35that would be added using hardware-specific APIs. 36</p><p>This API allows drivers to use conditional compilation to handle 37endpoint capabilities of different hardware, but doesn't require that. 38Hardware tends to have arbitrary restrictions, relating to 39transfer types, addressing, packet sizes, buffering, and availability. 40As a rule, such differences only matter for "endpoint zero" logic 41that handles device configuration and management. 42The API supports limited run-time 43detection of capabilities, through naming conventions for endpoints. 44Many drivers will be able to at least partially autoconfigure 45themselves. 46In particular, driver init sections will often have endpoint 47autoconfiguration logic that scans the hardware's list of endpoints 48to find ones matching the driver requirements 49(relying on those conventions), to eliminate some of the most 50common reasons for conditional compilation. 51</p><p>Like the Linux-USB host side API, this API exposes 52the "chunky" nature of USB messages: I/O requests are in terms 53of one or more "packets", and packet boundaries are visible to drivers. 54Compared to RS-232 serial protocols, USB resembles 55synchronous protocols like HDLC 56(N bytes per frame, multipoint addressing, host as the primary 57station and devices as secondary stations) 58more than asynchronous ones 59(tty style: 8 data bits per frame, no parity, one stop bit). 60So for example the controller drivers won't buffer 61two single byte writes into a single two-byte USB IN packet, 62although gadget drivers may do so when they implement 63protocols where packet boundaries (and "short packets") 64are not significant. 65</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="lifecycle"></a>Driver Life Cycle</h2></div></div></div><p>Gadget drivers make endpoint I/O requests to hardware without 66needing to know many details of the hardware, but driver 67setup/configuration code needs to handle some differences. 68Use the API like this: 69</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Register a driver for the particular device side 70usb controller hardware, 71such as the net2280 on PCI (USB 2.0), 72sa11x0 or pxa25x as found in Linux PDAs, 73and so on. 74At this point the device is logically in the USB ch9 initial state 75("attached"), drawing no power and not usable 76(since it does not yet support enumeration). 77Any host should not see the device, since it's not 78activated the data line pullup used by the host to 79detect a device, even if VBUS power is available. 80</p></li><li class="listitem"><p>Register a gadget driver that implements some higher level 81device function. That will then bind() to a usb_gadget, which 82activates the data line pullup sometime after detecting VBUS. 83</p></li><li class="listitem"><p>The hardware driver can now start enumerating. 84The steps it handles are to accept USB power and set_address requests. 85Other steps are handled by the gadget driver. 86If the gadget driver module is unloaded before the host starts to 87enumerate, steps before step 7 are skipped. 88</p></li><li class="listitem"><p>The gadget driver's setup() call returns usb descriptors, 89based both on what the bus interface hardware provides and on the 90functionality being implemented. 91That can involve alternate settings or configurations, 92unless the hardware prevents such operation. 93For OTG devices, each configuration descriptor includes 94an OTG descriptor. 95</p></li><li class="listitem"><p>The gadget driver handles the last step of enumeration, 96when the USB host issues a set_configuration call. 97It enables all endpoints used in that configuration, 98with all interfaces in their default settings. 99That involves using a list of the hardware's endpoints, enabling each 100endpoint according to its descriptor. 101It may also involve using <code class="function">usb_gadget_vbus_draw</code> 102to let more power be drawn from VBUS, as allowed by that configuration. 103For OTG devices, setting a configuration may also involve reporting 104HNP capabilities through a user interface. 105</p></li><li class="listitem"><p>Do real work and perform data transfers, possibly involving 106changes to interface settings or switching to new configurations, until the 107device is disconnect()ed from the host. 108Queue any number of transfer requests to each endpoint. 109It may be suspended and resumed several times before being disconnected. 110On disconnect, the drivers go back to step 3 (above). 111</p></li><li class="listitem"><p>When the gadget driver module is being unloaded, 112the driver unbind() callback is issued. That lets the controller 113driver be unloaded. 114</p></li></ol></div><p>Drivers will normally be arranged so that just loading the 115gadget driver module (or statically linking it into a Linux kernel) 116allows the peripheral device to be enumerated, but some drivers 117will defer enumeration until some higher level component (like 118a user mode daemon) enables it. 119Note that at this lowest level there are no policies about how 120ep0 configuration logic is implemented, 121except that it should obey USB specifications. 122Such issues are in the domain of gadget drivers, 123including knowing about implementation constraints 124imposed by some USB controllers 125or understanding that composite devices might happen to 126be built by integrating reusable components. 127</p><p>Note that the lifecycle above can be slightly different 128for OTG devices. 129Other than providing an additional OTG descriptor in each 130configuration, only the HNP-related differences are particularly 131visible to driver code. 132They involve reporting requirements during the SET_CONFIGURATION 133request, and the option to invoke HNP during some suspend callbacks. 134Also, SRP changes the semantics of 135<code class="function">usb_gadget_wakeup</code> 136slightly. 137</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="structure.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch9.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Structure of Gadget Drivers </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> USB 2.0 Chapter 9 Types and Constants</td></tr></table></div></body></html> 138