1========================
2USB Gadget API for Linux
3========================
4
5:Author: David Brownell
6:Date:   20 August 2004
7
8Introduction
9============
10
11This document presents a Linux-USB "Gadget" kernel mode API, for use
12within peripherals and other USB devices that embed Linux. It provides
13an overview of the API structure, and shows how that fits into a system
14development project. This is the first such API released on Linux to
15address a number of important problems, including:
16
17-  Supports USB 2.0, for high speed devices which can stream data at
18   several dozen megabytes per second.
19
20-  Handles devices with dozens of endpoints just as well as ones with
21   just two fixed-function ones. Gadget drivers can be written so
22   they're easy to port to new hardware.
23
24-  Flexible enough to expose more complex USB device capabilities such
25   as multiple configurations, multiple interfaces, composite devices,
26   and alternate interface settings.
27
28-  USB "On-The-Go" (OTG) support, in conjunction with updates to the
29   Linux-USB host side.
30
31-  Sharing data structures and API models with the Linux-USB host side
32   API. This helps the OTG support, and looks forward to more-symmetric
33   frameworks (where the same I/O model is used by both host and device
34   side drivers).
35
36-  Minimalist, so it's easier to support new device controller hardware.
37   I/O processing doesn't imply large demands for memory or CPU
38   resources.
39
40Most Linux developers will not be able to use this API, since they have
41USB ``host`` hardware in a PC, workstation, or server. Linux users with
42embedded systems are more likely to have USB peripheral hardware. To
43distinguish drivers running inside such hardware from the more familiar
44Linux "USB device drivers", which are host side proxies for the real USB
45devices, a different term is used: the drivers inside the peripherals
46are "USB gadget drivers". In USB protocol interactions, the device
47driver is the master (or "client driver") and the gadget driver is the
48slave (or "function driver").
49
50The gadget API resembles the host side Linux-USB API in that both use
51queues of request objects to package I/O buffers, and those requests may
52be submitted or canceled. They share common definitions for the standard
53USB *Chapter 9* messages, structures, and constants. Also, both APIs
54bind and unbind drivers to devices. The APIs differ in detail, since the
55host side's current URB framework exposes a number of implementation
56details and assumptions that are inappropriate for a gadget API. While
57the model for control transfers and configuration management is
58necessarily different (one side is a hardware-neutral master, the other
59is a hardware-aware slave), the endpoint I/0 API used here should also
60be usable for an overhead-reduced host side API.
61
62Structure of Gadget Drivers
63===========================
64
65A system running inside a USB peripheral normally has at least three
66layers inside the kernel to handle USB protocol processing, and may have
67additional layers in user space code. The ``gadget`` API is used by the
68middle layer to interact with the lowest level (which directly handles
69hardware).
70
71In Linux, from the bottom up, these layers are:
72
73*USB Controller Driver*
74    This is the lowest software level. It is the only layer that talks
75    to hardware, through registers, fifos, dma, irqs, and the like. The
76    ``<linux/usb/gadget.h>`` API abstracts the peripheral controller
77    endpoint hardware. That hardware is exposed through endpoint
78    objects, which accept streams of IN/OUT buffers, and through
79    callbacks that interact with gadget drivers. Since normal USB
80    devices only have one upstream port, they only have one of these
81    drivers. The controller driver can support any number of different
82    gadget drivers, but only one of them can be used at a time.
83
84    Examples of such controller hardware include the PCI-based NetChip
85    2280 USB 2.0 high speed controller, the SA-11x0 or PXA-25x UDC
86    (found within many PDAs), and a variety of other products.
87
88*Gadget Driver*
89    The lower boundary of this driver implements hardware-neutral USB
90    functions, using calls to the controller driver. Because such
91    hardware varies widely in capabilities and restrictions, and is used
92    in embedded environments where space is at a premium, the gadget
93    driver is often configured at compile time to work with endpoints
94    supported by one particular controller. Gadget drivers may be
95    portable to several different controllers, using conditional
96    compilation. (Recent kernels substantially simplify the work
97    involved in supporting new hardware, by *autoconfiguring* endpoints
98    automatically for many bulk-oriented drivers.) Gadget driver
99    responsibilities include:
100
101    -  handling setup requests (ep0 protocol responses) possibly
102       including class-specific functionality
103
104    -  returning configuration and string descriptors
105
106    -  (re)setting configurations and interface altsettings, including
107       enabling and configuring endpoints
108
109    -  handling life cycle events, such as managing bindings to
110       hardware, USB suspend/resume, remote wakeup, and disconnection
111       from the USB host.
112
113    -  managing IN and OUT transfers on all currently enabled endpoints
114
115    Such drivers may be modules of proprietary code, although that
116    approach is discouraged in the Linux community.
117
118*Upper Level*
119    Most gadget drivers have an upper boundary that connects to some
120    Linux driver or framework in Linux. Through that boundary flows the
121    data which the gadget driver produces and/or consumes through
122    protocol transfers over USB. Examples include:
123
124    -  user mode code, using generic (gadgetfs) or application specific
125       files in ``/dev``
126
127    -  networking subsystem (for network gadgets, like the CDC Ethernet
128       Model gadget driver)
129
130    -  data capture drivers, perhaps video4Linux or a scanner driver; or
131       test and measurement hardware.
132
133    -  input subsystem (for HID gadgets)
134
135    -  sound subsystem (for audio gadgets)
136
137    -  file system (for PTP gadgets)
138
139    -  block i/o subsystem (for usb-storage gadgets)
140
141    -  ... and more
142
143*Additional Layers*
144    Other layers may exist. These could include kernel layers, such as
145    network protocol stacks, as well as user mode applications building
146    on standard POSIX system call APIs such as ``open()``, ``close()``,
147    ``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may
148    be an option. Such user mode code will not necessarily be subject to
149    the GNU General Public License (GPL).
150
151OTG-capable systems will also need to include a standard Linux-USB host
152side stack, with ``usbcore``, one or more *Host Controller Drivers*
153(HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
154List", and so forth. There will also be an *OTG Controller Driver*,
155which is visible to gadget and device driver developers only indirectly.
156That helps the host and device side USB controllers implement the two
157new OTG protocols (HNP and SRP). Roles switch (host to peripheral, or
158vice versa) using HNP during USB suspend processing, and SRP can be
159viewed as a more battery-friendly kind of device wakeup protocol.
160
161Over time, reusable utilities are evolving to help make some gadget
162driver tasks simpler. For example, building configuration descriptors
163from vectors of descriptors for the configurations interfaces and
164endpoints is now automated, and many drivers now use autoconfiguration
165to choose hardware endpoints and initialize their descriptors. A
166potential example of particular interest is code implementing standard
167USB-IF protocols for HID, networking, storage, or audio classes. Some
168developers are interested in KDB or KGDB hooks, to let target hardware
169be remotely debugged. Most such USB protocol code doesn't need to be
170hardware-specific, any more than network protocols like X11, HTTP, or
171NFS are. Such gadget-side interface drivers should eventually be
172combined, to implement composite devices.
173
174Kernel Mode Gadget API
175======================
176
177Gadget drivers declare themselves through a struct
178:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
179for a struct :c:type:`usb_gadget`. The response to a set_configuration usually
180involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by
181the gadget, and submitting one or more struct :c:type:`usb_request` buffers to
182transfer data. Understand those four data types, and their operations,
183and you will understand how this API works.
184
185.. Note::
186
187    Other than the "Chapter 9" data types, most of the significant data
188    types and functions are described here.
189
190    However, some relevant information is likely omitted from what you
191    are reading. One example of such information is endpoint
192    autoconfiguration. You'll have to read the header file, and use
193    example source code (such as that for "Gadget Zero"), to fully
194    understand the API.
195
196    The part of the API implementing some basic driver capabilities is
197    specific to the version of the Linux kernel that's in use. The 2.6
198    and upper kernel versions include a *driver model* framework that has
199    no analogue on earlier kernels; so those parts of the gadget API are
200    not fully portable. (They are implemented on 2.4 kernels, but in a
201    different way.) The driver model state is another part of this API that is
202    ignored by the kerneldoc tools.
203
204The core API does not expose every possible hardware feature, only the
205most widely available ones. There are significant hardware features,
206such as device-to-device DMA (without temporary storage in a memory
207buffer) that would be added using hardware-specific APIs.
208
209This API allows drivers to use conditional compilation to handle
210endpoint capabilities of different hardware, but doesn't require that.
211Hardware tends to have arbitrary restrictions, relating to transfer
212types, addressing, packet sizes, buffering, and availability. As a rule,
213such differences only matter for "endpoint zero" logic that handles
214device configuration and management. The API supports limited run-time
215detection of capabilities, through naming conventions for endpoints.
216Many drivers will be able to at least partially autoconfigure
217themselves. In particular, driver init sections will often have endpoint
218autoconfiguration logic that scans the hardware's list of endpoints to
219find ones matching the driver requirements (relying on those
220conventions), to eliminate some of the most common reasons for
221conditional compilation.
222
223Like the Linux-USB host side API, this API exposes the "chunky" nature
224of USB messages: I/O requests are in terms of one or more "packets", and
225packet boundaries are visible to drivers. Compared to RS-232 serial
226protocols, USB resembles synchronous protocols like HDLC (N bytes per
227frame, multipoint addressing, host as the primary station and devices as
228secondary stations) more than asynchronous ones (tty style: 8 data bits
229per frame, no parity, one stop bit). So for example the controller
230drivers won't buffer two single byte writes into a single two-byte USB
231IN packet, although gadget drivers may do so when they implement
232protocols where packet boundaries (and "short packets") are not
233significant.
234
235Driver Life Cycle
236-----------------
237
238Gadget drivers make endpoint I/O requests to hardware without needing to
239know many details of the hardware, but driver setup/configuration code
240needs to handle some differences. Use the API like this:
241
2421. Register a driver for the particular device side usb controller
243   hardware, such as the net2280 on PCI (USB 2.0), sa11x0 or pxa25x as
244   found in Linux PDAs, and so on. At this point the device is logically
245   in the USB ch9 initial state (``attached``), drawing no power and not
246   usable (since it does not yet support enumeration). Any host should
247   not see the device, since it's not activated the data line pullup
248   used by the host to detect a device, even if VBUS power is available.
249
2502. Register a gadget driver that implements some higher level device
251   function. That will then bind() to a :c:type:`usb_gadget`, which activates
252   the data line pullup sometime after detecting VBUS.
253
2543. The hardware driver can now start enumerating. The steps it handles
255   are to accept USB ``power`` and ``set_address`` requests. Other steps are
256   handled by the gadget driver. If the gadget driver module is unloaded
257   before the host starts to enumerate, steps before step 7 are skipped.
258
2594. The gadget driver's ``setup()`` call returns usb descriptors, based both
260   on what the bus interface hardware provides and on the functionality
261   being implemented. That can involve alternate settings or
262   configurations, unless the hardware prevents such operation. For OTG
263   devices, each configuration descriptor includes an OTG descriptor.
264
2655. The gadget driver handles the last step of enumeration, when the USB
266   host issues a ``set_configuration`` call. It enables all endpoints used
267   in that configuration, with all interfaces in their default settings.
268   That involves using a list of the hardware's endpoints, enabling each
269   endpoint according to its descriptor. It may also involve using
270   ``usb_gadget_vbus_draw`` to let more power be drawn from VBUS, as
271   allowed by that configuration. For OTG devices, setting a
272   configuration may also involve reporting HNP capabilities through a
273   user interface.
274
2756. Do real work and perform data transfers, possibly involving changes
276   to interface settings or switching to new configurations, until the
277   device is disconnect()ed from the host. Queue any number of transfer
278   requests to each endpoint. It may be suspended and resumed several
279   times before being disconnected. On disconnect, the drivers go back
280   to step 3 (above).
281
2827. When the gadget driver module is being unloaded, the driver unbind()
283   callback is issued. That lets the controller driver be unloaded.
284
285Drivers will normally be arranged so that just loading the gadget driver
286module (or statically linking it into a Linux kernel) allows the
287peripheral device to be enumerated, but some drivers will defer
288enumeration until some higher level component (like a user mode daemon)
289enables it. Note that at this lowest level there are no policies about
290how ep0 configuration logic is implemented, except that it should obey
291USB specifications. Such issues are in the domain of gadget drivers,
292including knowing about implementation constraints imposed by some USB
293controllers or understanding that composite devices might happen to be
294built by integrating reusable components.
295
296Note that the lifecycle above can be slightly different for OTG devices.
297Other than providing an additional OTG descriptor in each configuration,
298only the HNP-related differences are particularly visible to driver
299code. They involve reporting requirements during the ``SET_CONFIGURATION``
300request, and the option to invoke HNP during some suspend callbacks.
301Also, SRP changes the semantics of ``usb_gadget_wakeup`` slightly.
302
303USB 2.0 Chapter 9 Types and Constants
304-------------------------------------
305
306Gadget drivers rely on common USB structures and constants defined in
307the :ref:`linux/usb/ch9.h <usb_chapter9>` header file, which is standard in
308Linux 2.6+ kernels. These are the same types and constants used by host side
309drivers (and usbcore).
310
311Core Objects and Methods
312------------------------
313
314These are declared in ``<linux/usb/gadget.h>``, and are used by gadget
315drivers to interact with USB peripheral controller drivers.
316
317.. kernel-doc:: include/linux/usb/gadget.h
318   :internal:
319
320Optional Utilities
321------------------
322
323The core API is sufficient for writing a USB Gadget Driver, but some
324optional utilities are provided to simplify common tasks. These
325utilities include endpoint autoconfiguration.
326
327.. kernel-doc:: drivers/usb/gadget/usbstring.c
328   :export:
329
330.. kernel-doc:: drivers/usb/gadget/config.c
331   :export:
332
333Composite Device Framework
334--------------------------
335
336The core API is sufficient for writing drivers for composite USB devices
337(with more than one function in a given configuration), and also
338multi-configuration devices (also more than one function, but not
339necessarily sharing a given configuration). There is however an optional
340framework which makes it easier to reuse and combine functions.
341
342Devices using this framework provide a struct :c:type:`usb_composite_driver`,
343which in turn provides one or more struct :c:type:`usb_configuration`
344instances. Each such configuration includes at least one struct
345:c:type:`usb_function`, which packages a user visible role such as "network
346link" or "mass storage device". Management functions may also exist,
347such as "Device Firmware Upgrade".
348
349.. kernel-doc:: include/linux/usb/composite.h
350   :internal:
351
352.. kernel-doc:: drivers/usb/gadget/composite.c
353   :export:
354
355Composite Device Functions
356--------------------------
357
358At this writing, a few of the current gadget drivers have been converted
359to this framework. Near-term plans include converting all of them,
360except for ``gadgetfs``.
361
362Peripheral Controller Drivers
363=============================
364
365The first hardware supporting this API was the NetChip 2280 controller,
366which supports USB 2.0 high speed and is based on PCI. This is the
367``net2280`` driver module. The driver supports Linux kernel versions 2.4
368and 2.6; contact NetChip Technologies for development boards and product
369information.
370
371Other hardware working in the ``gadget`` framework includes: Intel's PXA
37225x and IXP42x series processors (``pxa2xx_udc``), Toshiba TC86c001
373"Goku-S" (``goku_udc``), Renesas SH7705/7727 (``sh_udc``), MediaQ 11xx
374(``mq11xx_udc``), Hynix HMS30C7202 (``h7202_udc``), National 9303/4
375(``n9604_udc``), Texas Instruments OMAP (``omap_udc``), Sharp LH7A40x
376(``lh7a40x_udc``), and more. Most of those are full speed controllers.
377
378At this writing, there are people at work on drivers in this framework
379for several other USB device controllers, with plans to make many of
380them be widely available.
381
382A partial USB simulator, the ``dummy_hcd`` driver, is available. It can
383act like a net2280, a pxa25x, or an sa11x0 in terms of available
384endpoints and device speeds; and it simulates control, bulk, and to some
385extent interrupt transfers. That lets you develop some parts of a gadget
386driver on a normal PC, without any special hardware, and perhaps with
387the assistance of tools such as GDB running with User Mode Linux. At
388least one person has expressed interest in adapting that approach,
389hooking it up to a simulator for a microcontroller. Such simulators can
390help debug subsystems where the runtime hardware is unfriendly to
391software development, or is not yet available.
392
393Support for other controllers is expected to be developed and
394contributed over time, as this driver framework evolves.
395
396Gadget Drivers
397==============
398
399In addition to *Gadget Zero* (used primarily for testing and development
400with drivers for usb controller hardware), other gadget drivers exist.
401
402There's an ``ethernet`` gadget driver, which implements one of the most
403useful *Communications Device Class* (CDC) models. One of the standards
404for cable modem interoperability even specifies the use of this ethernet
405model as one of two mandatory options. Gadgets using this code look to a
406USB host as if they're an Ethernet adapter. It provides access to a
407network where the gadget's CPU is one host, which could easily be
408bridging, routing, or firewalling access to other networks. Since some
409hardware can't fully implement the CDC Ethernet requirements, this
410driver also implements a "good parts only" subset of CDC Ethernet. (That
411subset doesn't advertise itself as CDC Ethernet, to avoid creating
412problems.)
413
414Support for Microsoft's ``RNDIS`` protocol has been contributed by
415Pengutronix and Auerswald GmbH. This is like CDC Ethernet, but it runs
416on more slightly USB hardware (but less than the CDC subset). However,
417its main claim to fame is being able to connect directly to recent
418versions of Windows, using drivers that Microsoft bundles and supports,
419making it much simpler to network with Windows.
420
421There is also support for user mode gadget drivers, using ``gadgetfs``.
422This provides a *User Mode API* that presents each endpoint as a single
423file descriptor. I/O is done using normal ``read()`` and ``read()`` calls.
424Familiar tools like GDB and pthreads can be used to develop and debug
425user mode drivers, so that once a robust controller driver is available
426many applications for it won't require new kernel mode software. Linux
4272.6 *Async I/O (AIO)* support is available, so that user mode software
428can stream data with only slightly more overhead than a kernel driver.
429
430There's a USB Mass Storage class driver, which provides a different
431solution for interoperability with systems such as MS-Windows and MacOS.
432That *Mass Storage* driver uses a file or block device as backing store
433for a drive, like the ``loop`` driver. The USB host uses the BBB, CB, or
434CBI versions of the mass storage class specification, using transparent
435SCSI commands to access the data from the backing store.
436
437There's a "serial line" driver, useful for TTY style operation over USB.
438The latest version of that driver supports CDC ACM style operation, like
439a USB modem, and so on most hardware it can interoperate easily with
440MS-Windows. One interesting use of that driver is in boot firmware (like
441a BIOS), which can sometimes use that model with very small systems
442without real serial lines.
443
444Support for other kinds of gadget is expected to be developed and
445contributed over time, as this driver framework evolves.
446
447USB On-The-GO (OTG)
448===================
449
450USB OTG support on Linux 2.6 was initially developed by Texas
451Instruments for `OMAP <http://www.omap.com>`__ 16xx and 17xx series
452processors. Other OTG systems should work in similar ways, but the
453hardware level details could be very different.
454
455Systems need specialized hardware support to implement OTG, notably
456including a special *Mini-AB* jack and associated transceiver to support
457*Dual-Role* operation: they can act either as a host, using the standard
458Linux-USB host side driver stack, or as a peripheral, using this
459``gadget`` framework. To do that, the system software relies on small
460additions to those programming interfaces, and on a new internal
461component (here called an "OTG Controller") affecting which driver stack
462connects to the OTG port. In each role, the system can re-use the
463existing pool of hardware-neutral drivers, layered on top of the
464controller driver interfaces (:c:type:`usb_bus` or :c:type:`usb_gadget`).
465Such drivers need at most minor changes, and most of the calls added to
466support OTG can also benefit non-OTG products.
467
468-  Gadget drivers test the ``is_otg`` flag, and use it to determine
469   whether or not to include an OTG descriptor in each of their
470   configurations.
471
472-  Gadget drivers may need changes to support the two new OTG protocols,
473   exposed in new gadget attributes such as ``b_hnp_enable`` flag. HNP
474   support should be reported through a user interface (two LEDs could
475   suffice), and is triggered in some cases when the host suspends the
476   peripheral. SRP support can be user-initiated just like remote
477   wakeup, probably by pressing the same button.
478
479-  On the host side, USB device drivers need to be taught to trigger HNP
480   at appropriate moments, using ``usb_suspend_device()``. That also
481   conserves battery power, which is useful even for non-OTG
482   configurations.
483
484-  Also on the host side, a driver must support the OTG "Targeted
485   Peripheral List". That's just a whitelist, used to reject peripherals
486   not supported with a given Linux OTG host. *This whitelist is
487   product-specific; each product must modify* ``otg_whitelist.h`` *to
488   match its interoperability specification.*
489
490   Non-OTG Linux hosts, like PCs and workstations, normally have some
491   solution for adding drivers, so that peripherals that aren't
492   recognized can eventually be supported. That approach is unreasonable
493   for consumer products that may never have their firmware upgraded,
494   and where it's usually unrealistic to expect traditional
495   PC/workstation/server kinds of support model to work. For example,
496   it's often impractical to change device firmware once the product has
497   been distributed, so driver bugs can't normally be fixed if they're
498   found after shipment.
499
500Additional changes are needed below those hardware-neutral :c:type:`usb_bus`
501and :c:type:`usb_gadget` driver interfaces; those aren't discussed here in any
502detail. Those affect the hardware-specific code for each USB Host or
503Peripheral controller, and how the HCD initializes (since OTG can be
504active only on a single port). They also involve what may be called an
505*OTG Controller Driver*, managing the OTG transceiver and the OTG state
506machine logic as well as much of the root hub behavior for the OTG port.
507The OTG controller driver needs to activate and deactivate USB
508controllers depending on the relevant device role. Some related changes
509were needed inside usbcore, so that it can identify OTG-capable devices
510and respond appropriately to HNP or SRP protocols.
511