1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 1. Introduction</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="index.html" title="USB Gadget API for Linux"><link rel="next" href="structure.html" title="Chapter 2. Structure of Gadget Drivers"></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 1. Introduction</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="structure.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="intro"></a>Chapter 1. Introduction</h1></div></div></div><p>This document presents a Linux-USB "Gadget" 2kernel mode 3API, for use within peripherals and other USB devices 4that embed Linux. 5It provides an overview of the API structure, 6and shows how that fits into a system development project. 7This is the first such API released on Linux to address 8a number of important problems, including: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Supports USB 2.0, for high speed devices which 9 can stream data at several dozen megabytes per second. 10 </p></li><li class="listitem"><p>Handles devices with dozens of endpoints just as 11 well as ones with just two fixed-function ones. Gadget drivers 12 can be written so they're easy to port to new hardware. 13 </p></li><li class="listitem"><p>Flexible enough to expose more complex USB device 14 capabilities such as multiple configurations, multiple interfaces, 15 composite devices, 16 and alternate interface settings. 17 </p></li><li class="listitem"><p>USB "On-The-Go" (OTG) support, in conjunction 18 with updates to the Linux-USB host side. 19 </p></li><li class="listitem"><p>Sharing data structures and API models with the 20 Linux-USB host side API. This helps the OTG support, and 21 looks forward to more-symmetric frameworks (where the same 22 I/O model is used by both host and device side drivers). 23 </p></li><li class="listitem"><p>Minimalist, so it's easier to support new device 24 controller hardware. I/O processing doesn't imply large 25 demands for memory or CPU resources. 26 </p></li></ul></div><p>Most Linux developers will not be able to use this API, since they 27have USB "host" hardware in a PC, workstation, or server. 28Linux users with embedded systems are more likely to 29have USB peripheral hardware. 30To distinguish drivers running inside such hardware from the 31more familiar Linux "USB device drivers", 32which are host side proxies for the real USB devices, 33a different term is used: 34the drivers inside the peripherals are "USB gadget drivers". 35In USB protocol interactions, the device driver is the master 36(or "client driver") 37and the gadget driver is the slave (or "function driver"). 38</p><p>The gadget API resembles the host side Linux-USB API in that both 39use queues of request objects to package I/O buffers, and those requests 40may be submitted or canceled. 41They share common definitions for the standard USB 42<span class="emphasis"><em>Chapter 9</em></span> messages, structures, and constants. 43Also, both APIs bind and unbind drivers to devices. 44The APIs differ in detail, since the host side's current 45URB framework exposes a number of implementation details 46and assumptions that are inappropriate for a gadget API. 47While the model for control transfers and configuration 48management is necessarily different (one side is a hardware-neutral master, 49the other is a hardware-aware slave), the endpoint I/0 API used here 50should also be usable for an overhead-reduced host side API. 51</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="structure.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">USB Gadget API for Linux </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 2. Structure of Gadget Drivers</td></tr></table></div></body></html> 52