driver-api/usb/gadget.rst

2 USB Gadget API for Linux
11 This document presents a Linux-USB "Gadget" kernel mode API, for use
21    just two fixed-function ones. Gadget drivers can be written so
46 are "USB gadget drivers". In USB protocol interactions, the device
47 driver is the master (or "client driver") and the gadget driver is the
50 The gadget API resembles the host side Linux-USB API in that both use
56 details and assumptions that are inappropriate for a gadget API. While
62 Structure of Gadget Drivers
67 additional layers in user space code. The ``gadget`` API is used by the
76     ``<linux/usb/gadget.h>`` API abstracts the peripheral controller
79     callbacks that interact with gadget drivers. Since normal USB
82     gadget drivers, but only one of them can be used at a time.
88 *Gadget Driver*
92     in embedded environments where space is at a premium, the gadget
94     supported by one particular controller. Gadget drivers may be
98     automatically for many bulk-oriented drivers.) Gadget driver
119     Most gadget drivers have an upper boundary that connects to some
121     data which the gadget driver produces and/or consumes through
128        Model gadget driver)
155 which is visible to gadget and device driver developers only indirectly.
161 Over time, reusable utilities are evolving to help make some gadget
171 NFS are. Such gadget-side interface drivers should eventually be
174 Kernel Mode Gadget API
177 Gadget drivers declare themselves through a struct
181 the gadget, and submitting one or more struct usb_request buffers to
193     example source code (such as that for "Gadget Zero"), to fully
199     no analogue on earlier kernels; so those parts of the gadget API are
231 IN packet, although gadget drivers may do so when they implement
238 Gadget drivers make endpoint I/O requests to hardware without needing to
250 2. Register a gadget driver that implements some higher level device
256    handled by the gadget driver. If the gadget driver module is unloaded
259 4. The gadget driver's ``setup()`` call returns usb descriptors, based both
265 5. The gadget driver handles the last step of enumeration, when the USB
282 7. When the gadget driver module is being unloaded, the driver unbind()
285 Drivers will normally be arranged so that just loading the gadget driver
291 USB specifications. Such issues are in the domain of gadget drivers,
306 Gadget drivers rely on common USB structures and constants defined in
314 These are declared in ``<linux/usb/gadget.h>``, and are used by gadget
317 .. kernel-doc:: include/linux/usb/gadget.h
323 The core API is sufficient for writing a USB Gadget Driver, but some
327 .. kernel-doc:: drivers/usb/gadget/usbstring.c
330 .. kernel-doc:: drivers/usb/gadget/config.c
352 .. kernel-doc:: drivers/usb/gadget/composite.c
358 At this writing, a few of the current gadget drivers have been converted
371 Other hardware working in the ``gadget`` framework includes: Intel's PXA
385 extent interrupt transfers. That lets you develop some parts of a gadget
396 Gadget Drivers
399 In addition to *Gadget Zero* (used primarily for testing and development
400 with drivers for usb controller hardware), other gadget drivers exist.
402 There's an ``ethernet`` gadget driver, which implements one of the most
407 network where the gadget's CPU is one host, which could easily be
421 There is also support for user mode gadget drivers, using ``gadgetfs``.
444 Support for other kinds of gadget is expected to be developed and
459 ``gadget`` framework. To do that, the system software relies on small
468 -  Gadget drivers test the ``is_otg`` flag, and use it to determine
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