Linux-USB Gadget : Part 2: USB Gadget API for Linux (From Linux kernel 2.6.25.10)

 

<script type="text/javascript"> document.body.oncopy = function() { if (window.clipboardData) { setTimeout(function() { var text = clipboardData.getData("text"); if (text && text.length>300) { text = text + "/r/n/n本文来自CSDN博客，转载请标明出处：" + location.href; clipboardData.setData("text", text); } }, 100); } } </script> <script class="blogstory">function StorePage(){d=document;t=d.selection?(d.selection.type!='None'?d.selection.createRange().text:''):(d.getSelection?d.getSelection():'');void(keyit=window.open('http://www.365key.com/storeit.aspx?t='+escape(d.title)+'&u='+escape(d.location.href)+'&c='+escape(t),'keyit','scrollbars=no,width=475,height=575,left=75,top=20,status=no,resizable=yes'));keyit.focus();}</script>

Linux-USB Gadget : Part 1: 简介

作者： zjujoe 转载请注明出处

Email ： zjujoe@yahoo.com

BLOG ： http://blog.csdn.net/zjujoe

 

Google 一下，发现网上对 USB Gadget 的介绍资料（中文）比较少，刚好最近也在做这一块，于是产生了学习一下的兴趣，同时作为 home work, 将看到的， 理解的边学边记边译。。。   以下假定您已经精通或者粗通（象我一样） USB 协议 , 比如知道什么叫 usb host , usb device ， 配置（ configuration ），接口 (interface) ，端点（ endpoint ）等，什么叫 alternative setting, enumeraion ( 枚举 ) 。如若不然，请先浏览 usb 协议： http://www.usb.org/developers/docs/ 。以下切入正题。

 

注：英文参考： http://www.linux-usb.org/gadget/

 

简介之简介

Linux-USB Gadget 驱动框架（以下简称 Gadget ）实现了 USB 协议定义的设备端的软件功能。相对于 Linux USB 主机端（ Host ） 驱动而言， Gadget 驱动出现较晚，它出现在 2.4.23 以后， ( 作者的第一次 announce: http://lwn.net/Articles/27352/ 或 http://kerneltrap.org/node/621 ) ， 如果需要在老的 2.4 内核上支持 Gadget ， 可以移植 2.4.31 代码，工作量较小。另外， 2.6 内核标准版本里的可能比最新版本要老一些。 “ mm” 补丁中的版本会比较新。

 

Gadget 框架提出了一套标准 API, 在底层， USB 设备控制器 (USB Device Controller, UDC) 驱动则实现这一套 API, 不同的 UDC （通常是 SOC 的一部分） 需要不同的驱动， 甚至基于同样的 UDC 的不同板子也需要进行代码修改。这一层我们可以称之为平台相关层。

 

基于 API, Gadget 驱动实现了一套硬件无关的功能，这基本上可以对应到 USB 协议里 的各种 USB Class ， 也有比如 USB Gadget Generic Serial 驱动，没有对应的 Class 。当然， Gadget 驱动还是受限于底层提供的功能的。比如 某些 Class 需要 USB Isochronous   端点，这时我们就不能支持该 Class 。

 

普通的 Gadget 驱动只实现一个功能（比如， u 盘， usb 网卡）。复合设备可以支持多个功能，后面将仔细研究一下复合设备的实现。像智能手机 , PDA 这样的设备，硬件支持较丰富的端点、 DMA Buffer, 给软件提了支持复合功能的基础。

 

有两点值得注意，第一是 usb gaget 驱动框架不象 usb 主机端有 usb core 的概念， usb 主机可能支持成百类型的外设，把通用功能抽象出来很有意义。 Usb device 端则通常没有这个需求，一些通用功能抽象在一些 Helper 函数里就可以了。第二是 usb 2.0 里提出了 OTG 的概念，可以在同一接口上支持 host 以及 device 功能。 OTG 是一个比较复杂的规范，以后有时间再研究。

 

控制器驱动

       常见的 usb device 有 U 盘， usb 鼠标、键盘， usb 蓝牙模块， usb 读卡器，等等。这些设备比较简单，通常不会运行 Linux 。运行 Linux Gadget 的通常是一些集成 CPU 以及很多外设接口的 SOC (System-on-Chip), 其中 CPU 通常为 32 bit 的 CPU, 并且 udc 也是该 SOC 的一部分 ( 顺带还有 DMA 通道， FIFO) 。

       Linux 标准内核里支持各主流 SOC 的 udc 驱动， make menuconfig 一下可以看到具体列表，其中值得一提的是 dummy_hcd , 它是一个软件模拟的 udc, 在开发新的 gadget 驱动时很有帮助。

       控制器驱动处理很少的 USB 控制请求（主要由硬件负责的部分）。其它所有的控制请求，比如返回描述符，设置当前配置，由 Gadget Driver 完成。控制器驱动一个主要责任就是负责管理各个端点的 I/O 队列，在 Gadget Driver 的 buffer 和硬件 buffer 之间传输数据 ( 通常是通过 DMA) 。

       我们前面提过，上层 Gadget 驱动能够实现什么功能要依赖底层提供的硬件条件。比如一个复合设备需要至少 5 个端点，这些硬件特性通过一组 gadget_is_*() 函数实现。

 

Gadget 驱动

基于底层提供的资源， Gadget 驱动可以运行在各种硬件平台上。重要的驱动有：

Ø         Gadget Zero, 类似于 dummy hcd, 该驱动用于测试 udc 驱动。它会帮助您通过 USB-IF 测试。

Ø         Ethernet over USB ， 该驱动模拟以太网网口，它支持多种运行方式：

²        CDC Ethernet: usb 规范规定的 Communications Device Class “Ethernet Model” protocol 。

²        CDC Subset ： 对硬件要求最低的一种方式，主要是 Linux 主机支持该方式。

²        RNDIS ： 微软公司对 CDC Ethernet 的变种实现。

Ø         File-backed Storage Gadget 最常见的 U 盘功能实现。

Ø         Serial Gadget 实现，包括 :

²        Generic Serial 实现（只需要 Bulk-in/Bulk-out 端点 +ep0 ）

²        CDC ACM 规范实现。

Ø         Gadget Filesystem, 将 Gadget API 接口暴露给应用层，以便在应用层实现 user mode driver 。

Ø         MIDI: 暴露 ALSA 接口，提供 recording 以及 playback 功能。

 

下午用最新内核试了一下 make pdfdocs 没有成功（google 一下也没有搞定），make htmldocs 成功了。于是为了方便，将原本分散的各章节合并成一个。 本想边看边理解、翻译，想想 API 其实是很直白的东西，翻译意义不大，于是直接放到这里。在看 gadget 驱动时，该 API 文档和 USB 协议 (CH9) 是最好的参考。

USB Gadget API for Linux

Chapter 1 Introduction

This document presents a Linux-USB "Gadget" kernel mode API, for use within peripherals and other USB devices that embed Linux. It provides an overview of the API structure, and shows how that fits into a system development project. This is the first such API released on Linux to address a number of important problems, including:

·         Supports USB 2.0, for high speed devices which can stream data at several dozen megabytes per second.

·         Handles devices with dozens of endpoints just as well as ones with just two fixed-function ones. Gadget drivers can be written so they're easy to port to new hardware.

·         Flexible enough to expose more complex USB device capabilities such as multiple configurations, multiple interfaces, composite devices, and alternate interface settings.

·         USB "On-The-Go" (OTG) support, in conjunction with updates to the Linux-USB host side.

·         Sharing data structures and API models with the Linux-USB host side API. This helps the OTG support, and looks forward to more-symmetric frameworks (where the same I/O model is used by both host and device side drivers).

·         Minimalist, so it's easier to support new device controller hardware. I/O processing doesn't imply large demands for memory or CPU resources.

Most Linux developers will not be able to use this API, since they have USB "host" hardware in a PC, workstation, or server. Linux users with embedded systems are more likely to have USB peripheral hardware. To distinguish drivers running inside such hardware from the more familiar Linux "USB device drivers", which are host side proxies for the real USB devices, a different term is used: the drivers inside the peripherals are "USB gadget drivers". In USB protocol interactions, the device driver is the master (or "client driver") and the gadget driver is the slave (or "function driver").

The gadget API resembles the host side Linux-USB API in that both use queues of request objects to package I/O buffers, and those requests may be submitted or canceled. They share common definitions for the standard USB Chapter 9 messages, structures, and constants. Also, both APIs bind and unbind drivers to devices. The APIs differ in detail, since the host side's current URB framework exposes a number of implementation details and assumptions that are inappropriate for a gadget API. While the model for control transfers and configuration management is necessarily different (one side is a hardware-neutral master, the other is a hardware-aware slave), the endpoint I/0 API used here should also be usable for an overhead-reduced host side API.

Chapter 2 Structure of Gadget Drivers

A system running inside a USB peripheral normally has at least three layers inside the kernel to handle USB protocol processing, and may have additional layers in user space code. The "gadget" API is used by the middle layer to interact with the lowest level (which directly handles hardware).

In Linux, from the bottom up, these layers are:

USB Controller Driver

This is the lowest software level. It is the only layer that talks to hardware, through registers, fifos, dma, irqs, and the like. The <linux/usb_gadget.h> API abstracts the peripheral controller endpoint hardware. That hardware is exposed through endpoint objects, which accept streams of IN/OUT buffers, and through callbacks that interact with gadget drivers. Since normal USB devices only have one upstream port, they only have one of these drivers. The controller driver can support any number of different gadget drivers, but only one of them can be used at a time.

Examples of such controller hardware include the PCI-based NetChip 2280 USB 2.0 high speed controller, the SA-11x0 or PXA-25x UDC (found within many PDAs), and a variety of other products.

Gadget Driver

The lower boundary of this driver implements hardware-neutral USB functions, using calls to the controller driver. Because such hardware varies widely in capabilities and restrictions, and is used in embedded environments where space is at a premium, the gadget driver is often configured at compile time to work with endpoints supported by one particular controller. Gadget drivers may be portable to several different controllers, using conditional compilation. (Recent kernels substantially simplify the work involved in supporting new hardware, by autoconfiguring endpoints automatically for many bulk-oriented drivers.) Gadget driver responsibilities include:

·   handling setup requests (ep0 protocol responses) possibly including class-specific functionality

·   returning configuration and string descriptors

·   (re)setting configurations and interface altsettings, including enabling and configuring endpoints

·   handling life cycle events, such as managing bindings to hardware, USB suspend/resume, remote wakeup, and disconnection from the USB host.

·   managing IN and OUT transfers on all currently enabled endpoints

Such drivers may be modules of proprietary code, although that approach is discouraged in the Linux community.

Upper Level