The <linux/usb_gadget.h> API makes it easy for peripherals and other devices (such as PDAs) embedding Linux to act in the USB "device" (slave) role. Most Linux users will not be able to use this API, since they have PC-style USB "Host Controller" hardware in a PC, workstation, or server. Smart gadgets like PDAs, printers, cash registers, and network routers will often have this type of "Device Controller" USB link.

This is the first such "USB Gadget" API on Linux to support high speed (USB 2.0) devices and arbitrary numbers of endpoints, sharing core models and data structures with the "host side" USB API. It's designed for flexibility: the API handles simple devices, composite ones, multiple configurations, class (or vendor) specific functionality, and more. It a good base for integrating and re-using this type of driver code.

Getting the Code

The API works on both 2.4 and 2.6 Linux kernels. Get the very latest code using BitKeeper:

     bk://linux.bkbits.net/linux-2.5
     bk://linux.bkbits.net/linux-2.4

     bk://usb-gadget.bkbits.net/gadget-2.6
     bk://usb-gadget.bkbits.net/gadget-2.4

Those first trees are the "official" Linux kernel trees, and they include a basic set of drivers. They're available through kernel.org as (compressed) tarballs, or as patches. The other trees are more experimental, and may have additional gadget drivers, enhancements, or fixes. (There may be other public trees with controller or gadget drivers too.) The "gadget" API is available in 2.6 kernels, as well as 2.4.23 and later.

Parts of the API

The API standardizes a boundary between two software layers, but the software stack usually has several higher layers. From the bottom up, those layers are:

• Controller Drivers implement the gadget API, and are the only layers that talk directly to hardware. Different controller hardware will need different drivers. These provide a software "gadget" device, visible in sysfs.
• Gadget Drivers use that gadget API, and can be written to be hardware-neutral. Certain hardware facts need to affect the implementation of configuration management parts of ep0 logic. Those parameters are usually handled with conditional compilation. For example, some controllers have more endpoints than others, many don't support high speed or isochronous transfers, and sometimes endpoints have fixed configurations.
• Upper Layers, such as the network, file system, or block I/O subsystems. These generate and consume the data that the gadget driver transfers to the host through the controller driver. There will often be several such layers, perhaps including user mode components.

The Linux 2.6 kernel tree includes kerneldoc for this API, including a structural overview as well as API reference.

Drivers

Drivers for several different usb device chips are available. Not all are listed on this page. One driver of particular interest supports the NetChip net2280. The net2280 hardware supports high speed (40+ MByte/sec) and full speed (1.5 MByte/sec) USB traffic through PCI, so it's easy for Linux developers to start with. A controller driver is also available for the full speed USB device controller (UDC) in Intel's PXA 2xx series of XScale ARM-5TE processors, used in products including Linux PDAs. The full speed UDC from several SuperH processors is supported, as is the full speed UDC from the Toshiba TC86c001 (Goku-S).

At this writing there are several public "gadget drivers", implementing USB functions.

• Gadget Zero ... is essential for driver testing. It provides two configurations: one for bulk traffic source/sink, and another for bulk traffic loopback. On the device side it helps verify that the driver stack pass USB-IF and other tests (needed for at least USB branding). On the host side it helps test the USB stack, such as the Linux-USB HCDs and usbcore. If built as a module, start it by modprobe g_zero; no other initialization is needed.
• CDC Ethernet ... the Communications Device Class (CDC) "Ethernet Model" protocols are the standard way for USB devices to expose Ethernet style functionality. The USB hardware will enumerate to the host as a standard CDC Ethernet device. (Like many cable modems.) Set it up like any other two-host Ethernet link; often, connecting it to a bridged host will be the easiest way to run things.

  bash# : this also loads the usb controller driver bash# modprobe g_ether bash# bash# : connect the device. bash# : then use dhcp, zcip or static configuration: bash# ifconfig usb0 10.0.0.105 bash# ip addr show usb0 2: usb0: <BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast qlen 100 link/ether 5a:dd:dc:eb:6d:f1 brd ff:ff:ff:ff:ff:ff inet 10.0.0.105/8 brd 10.255.255.255 scope global usb0 bash#

  This driver also supports a minimalist protocol usable on device hardware that doesn't support interface altsettings. (Two examples are the PXA2xx and SuperH UDCs.) This driver interoperates out-of-the-box with any recent Linux kernel. Modifications for RNDIS support are also in development, which will do the same for recent releases of Microsoft Windows. (RNDIS is Microsoft's analogue of CDC Ethernet, with complex frame encapsulation and its own internal RPC protocol.)
• GadgetFS ... since not every developer wants to program in the kernel, or rely specifically on the Linux kernel APIs, a user mode API is available. An example user mode driver is usb.c. (It also needs usbstring.c and usbstring.h.) Notice how the device is initialized by writing its configuration and device descriptors to a file (such as /dev/gadget/$CHIP), and how the endpoints are initialized in similar ways (writing descriptors to /dev/gadget/$ENDPOINT). After initializing them, just read or write to the files to transfer data; or to handle events including control requests to retrieve string descriptors, configure alternate settings, and implement class or vendor requests. On Linux 2.6 AIO (Async I/O) support is available, helping user mode drivers avoid i/o latencies and letting them stream data as quickly as in-kernel drivers can stream it.
• File-backed Storage ... implements the USB Mass Storage class (as CB, CBI, or BBB), appearing to the host as a SCSI disk drive. This uses a file or block device as a backing store for the drive, like the "loop" driver.

  bash# dd bs=1M count=64 if=/dev/zero of=/root/data/backing_file bash# mkfs ... bash# modprobe g_file_storage file=/root/data/backing_file bash#

• Serial ... this exposes a tty style serial line interface, usable with Minicom and similar tools. Most Linux hosts can talk to this using the generic usb-serial driver.

  bash# mknod /dev/ttygs0 c 127 0 bash# modprobe g_serial bash# cat /dev/ttygs0 # or whatever bash#

Other controller and gadget drivers are in development, but are unreleased or not published here.

Contributing

Yes, please! Bug fixes, gadget drivers (especially "class" drivers), and USB device controller drivers will all be of interest. Discussions, patches, and similar work should be on the linux-usb-devel mailing list for now.

Thanks!

This work has been supported by patches, feedback, bug reports, hardware, and other contributions from many groups and individuals. Of particular note are NetChip Technology Inc, Agilent Technologies, Intel Corporation, Pengutronix, MontaVista Software, handhelds.org, Alan Stern, Al Borchers, Julian Back, and everyone who's contributed a patch or other feedback through the Linux-USB community.