Linux-USB Gadget(小玩意) API Framework(框架)

Linux-USB Gadget(小玩意) API Framework(框架)

Last Modified: 8 June 2005

The <linux/usb_gadget.h> API makes it easy for peripherals(周边设备) and other devices(装置) embedding(栽种) GNU/Linux system software to act in the USB "device" (slave) role. The drivers implementing(实施) and using that API combine to make a useful driver framework for Linux systems that implement USB peripherals. Many Linux systems will not be able to use it, since they only have PC-style USB Host (master) hardware(计算机硬件) in a PC, workstation(工作站), or server. But when you're putting together embedded Linux systems, a USB peripheral(外围的) controller option is routine(程序); it's often integrated(综合的) into processors(处理器). Smart gadgets like PDAs, printers, cell phones, cash registers, and network routers often rely(依靠) on this type of "Device Controller" USB link as one of their basicconnectivity(连通性) options. Sometimes it will be the only option; there are Linux devices that rely on USB even for their power supplies.

This is the first such "USB Gadget" framework on GNU/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(复合的) (multi-function) ones, multiple configurations(配置), class (or vendor(卖主)) specific(特殊的) functionality(功能), and more. It a good base for integrating and re-using this type of driver code. Tests are available too, which can speed hardware bringup substantially(大量的).

Many developers have asked about easy ways to start working with this API. If you're comfortable working with embedded Linux platforms, many ARM systems already have Linux support for their integrated USB controllers. Otherwise, a Net2280 PCI card lets you work on a standard PC, developing ordebugging(调试以排除故障) gadget drivers on computers you may already own.

Getting the Code

The API and several supporting drivers are included in current 2.4 and 2.6 Linux kernels(核心), available through kernel.org as tarballs, or from vendors supportingcustomized(自定义) Linux distributions(分布). The BitKeeper trees are no longer current, but the "mm" patchsets or various other GIT trees may well have more current code than the current mainstream(主流) kernel.

There may be other public trees with controller or gadget drivers too. The handhelds.org website includes pointers to a number of these; a USB network link can be extremely useful. Kernel trees that support specific System-on-Chip platforms often include a driver for that platform's USB Peripheral Controller.

The "gadget" framework is available in 2.6 kernels, as well as 2.4.23 and later. (2.4.27 is the first 2.4 kernel to bundle(束) RNDIS support, and some other frameworkimprovements(改进).) At this writing, other than architecture- or board-specific setup(设置), and the <linux/usb_*.h> header files, all the gadget(小玩意) code is in the drivers/usb/gadget directory. It's easy to backport current 2.4 gadget code (e.g. 2.4.31) onto older 2.4 kernels(核心). Most new development is based on 2.6 kernels; differences relevant(有关的) to 2.4 based development are minor(未成年的), mostly limited to kernel configuration(配置) and the 2.6 kernel's "generic(类的)DMA" and "driver model" infrastructure(基础设施). Some 2.4 vendor(卖主) kernels already include some of that code, making 2.6 backports even easier.

Parts of the Framework(框架)

The API standardizes(标准化) a platform-neutral boundary(边界) between two software layers, but the software stack(堆叠) usually has several higher layers. The framework includes that API, some support software, and several drivers on each side of that API boundary, integrating(完整) well with other Linux subsystems(子系统). From the bottom up, those layers are:

• Peripheral(外围的) Controller Drivers implement the gadget API, and are the only layers that talk directly to hardware(计算机硬件). Different controller hardware will need different drivers, which may also need board-specific customization(定制). These provide a software "gadget" device(装置), visible(可见物) in sysfs. You can think of that device as being the virtual(虚拟的) hardware to which the higher level drivers are written. Other operating systems use other names for this component