Linux gadget USB设备端驱动程序（kernel 2.6.28）

一、几个重要设备端Gadget驱动结构体：

1. struct usb_gadget {//代表一个UDC设备

/* readonly to gadget driver */

const struct usb_gadget_ops *ops; //设备的操作集

struct usb_ep *ep0; //ep0（USB协议中的端点0）, 处理setup()请求

struct list_head ep_list; /* of usb_ep */本设备支持的端点链表

enum usb_device_speed speed; //如：USB_SPEED_LOW、USB_SPEED_FULL等

unsigned is_dualspeed:1; //支持full/high speed

unsigned is_otg:1; //OTG的特性

unsigned is_a_peripheral:1; //当前是A-peripheral，而不是A-host

unsigned b_hnp_enable:1;

unsigned a_hnp_support:1;

unsigned a_alt_hnp_support:1;

const char *name;

struct device dev;

};

2. struct usb_gadget_driver
{//代表一个gadget设备driver，如：file_storage.c中的fsg_driver

//又如：如zero.c中的zero_driver

char *function; //一个字符串，如"Gadget Zero"

enum usb_device_speed speed;

int (*bind)(struct usb_gadget *); //常用语将dev 与driver的绑定，类似于probe，会被底层Gadget自动调用

void (*unbind)(struct usb_gadget *); //与bind作用相反

int (*setup)(struct usb_gadget *, const struct usb_ctrlrequest *); //用于usb设备setup阶段的USB_REQ_GET_DESCRIPTOR等主机端的请求处理，完成USB设置阶段和具体功能相关的交互

void (*disconnect)(struct usb_gadget *);

void (*suspend)(struct usb_gadget *);

void (*resume)(struct usb_gadget *)

/* FIXME support safe rmmod */

struct device_driver driver;

};
3. struct usb_gadget_ops {//代表设备的操作集

int (*get_frame)(struct usb_gadget *);

int (*wakeup)(struct usb_gadget *);

int (*set_selfpowered) (struct usb_gadget *, int is_selfpowered);

nt (*vbus_session) (struct usb_gadget *, int is_active);

int (*vbus_draw) (struct usb_gadget *, unsigned mA);

int (*pullup) (struct usb_gadget *, int is_on);

int (*ioctl)(struct usb_gadget *,

unsigned code, unsigned long param);

};
4. struct usb_ep
{//代表一个端点

void *driver_data //

...

const struct usb_ep_ops *ops; //端点的操作集，如上

struct list_head ep_list; //gadget的所有ep的list

...

};

5. struct usb_ep_ops {//表示端点的操作集

...

int (*queue) (struct usb_ep *ep, struct usb_request *req,

gfp_t gfp_flags); //将一个usb_request提交给endpoint

//是数据传输的关键函数

...

};
6. struct usb_request {//表示一个传输的请求，这与usb host端的urb类似

void *buf;

unsigned length;

dma_addr_t dma;

unsigned no_interrupt:1;

unsigned zero:1;

unsigned short_not_ok:1;

void (*complete)(struct usb_ep *ep, struct usb_request *req); //一个usb请求提交完成后的回调函数

void *context;

struct list_head list;

int status;

unsigned actual;

};
7. struct
usb_ctrlrequest (用在setup函数中）

|-----------------------|

| __u8 bRequestType -|

| __u8 bRequest -|

| __le16 -wValue -|

| __le16 -wIndex -|

| __le16 -wLength -|

|-----------------------|

这个数据结构就是SETUP信包的内容，而缓冲区的内容，就是随后的数据信包的内容。

---------------------------------------------------------------

bRequestType

D7 数据的传输方向：0表示从主机到设备； 1表示从设备到主机；

D6~5 命令的类型： 0表示标准命令； 1表示类命令； 2表示厂商提供的命令； 3保留；

D4~0 接收对象； 0表示设备； 1表示接口； 2表示端点； 3表示其他；

bRequest

命令的序号(其实就是命令)；所有的命令都是以不同编码值的方式传递给设备的，bRequest就表示USB命令的编码值

wValue, wIndex

这两个字段对于不同的命令有不同的含义

wLength

表示在完成命令控制传输的数据阶段，要求传输数据的字节长度。一般不论是输入还是输出都要求给出准确的数字。当命令不需要传输数据时，此字段设为0

二、Gadget层驱动提供的几个常用的函数：

1. usb_gadget_register_driver 注册usb_gadget_driver类型的驱动

2. usb_gadget_unregister_driver 注销usb_gadget_driver类型驱动

3. struct usb_ep * __init usb_ep_autoconfig (

struct usb_gadget *gadget,

struct usb_endpoint_descriptor *desc

) 用于根据端点描述符及控制器端点情况，分配一个合适的端点。

4. static inline struct usb_request *usb_ep_alloc_request(struct usb_ep *ep,

gfp_t gfp_flags) 分配一个usb_request

3. 通过Gadget Core 驱动，向usb_ep发送usb_request, 请求读写

static inline int usb_ep_queue(struct usb_ep *ep,

struct usb_request *req, gfp_t gfp_flags);

三、USB gadget功能驱动

如果内核已经支持了SOC的UDC驱动，很多时候，我们可以只关心这部分代码的编写。那么我们如何编写出一个类似usb 功能驱动呢？
usb 功能驱动应该至少要实现如下功能：
. 实现USB协议中端点0部分和具体功能相关的部分（UDC驱动无法帮我们完成的部分）。如：USB_REQ_GET_DESCRIPTOR、USB_REQ_GET_CONFIGURATION等；

完成了这个功能以后，USB主机端系统就会设别出我们是一个什么样的设备。

. 实现数据交互功能

即如何实现向硬件控制器的端点发出读、写请求来完成数据交互；

. 具体功能的实现如：如何实现一个usb net驱动，或是一个usb storage驱动。

四、实例
Linux内核2.6.28中 drivers/usb/gadget/Zero.c的源码提供了一个编写USB 设备端的驱动框架（利用Gadget层提供的函数，当然底层还需要有UDC层的支持）。
该例子的功能是： USB 设备端提供了一个USB_DIR_IN 用于接收主机数据的端点，同时通过产生一个字符设备与之关联，对其进行读的操作：
字符设备只定义了如下接口
struct file_operations usb_zero_fops = {

.owner = THIS_MODULE,

.read = usb_zero_read,

.open = usb_zero_open,

.release = usb_zero_release,

};

完整的源代码：

/*

* zero.c -- Gadget Zero, for simple USB development

* lht@farsight.com.cn

* All rights reserved.*/

/* #define VERBOSE_DEBUG */

#include <linux/kernel.h>

#include <linux/utsname.h>

#include <linux/device.h>

#include <linux/usb/ch9.h>

#include <linux/usb/gadget.h>

#include "gadget_chips.h"

#include <linux/slab.h>

#include <linux/module.h>

#include <linux/init.h>

#include <linux/usb/input.h>

#include <linux/cdev.h>

#include <asm/uaccess.h>

#include <linux/fs.h>

#include <linux/poll.h>

#include <linux/types.h> /* size_t */

#include <linux/errno.h> /* error codes */

#include <asm/system.h>

#include <asm/io.h>

#include <linux/sched.h>

/*-------------------------------------------------------------------------*/

static const char shortname[] = "zero";

static const char loopback[] = "loop input to output";

static const char longname[] = "Gadget Zero";

static const char source_sink[] = "source and sink data";

#define STRING_MANUFACTURER 25

#define STRING_PRODUCT 42

#define STRING_SERIAL 101

#define STRING_SOURCE_SINK 250

#define STRING_LOOPBACK 251

//#define DRIVER_VENDOR_NUM 0x0525 /* NetChip */

//#define DRIVER_PRODUCT_NUM 0xa4a0 /* Linux-USB "Gadget Zero" */

#define DRIVER_VENDOR_NUM 0x5345 /* NetChip */

#define DRIVER_PRODUCT_NUM 0x1234 /* Linux-USB "Gadget Zero" */

static int usb_zero_major = 251;

/*-------------------------------------------------------------------------*/

static const char *EP_OUT_NAME; /* sink */

/*-------------------------------------------------------------------------*/

/* big enough to hold our biggest descriptor */

#define USB_BUFSIZ 256

struct zero_dev { //zero设备结构

spinlock_t lock;

struct usb_gadget *gadget;

struct usb_request *req; /* for control responses */

struct usb_ep *out_ep;

struct cdev cdev;

unsigned char data[128];

unsigned int data_size;

wait_queue_head_t bulkrq;

};

#define CONFIG_LOOPBACK 2

static struct usb_device_descriptor device_desc = { //设备描述符

.bLength = sizeof device_desc,

.bDescriptorType = USB_DT_DEVICE,

.bcdUSB = __constant_cpu_to_le16(0x0110),

.bDeviceClass = USB_CLASS_VENDOR_SPEC,

.idVendor = __constant_cpu_to_le16(DRIVER_VENDOR_NUM),

.idProduct = __constant_cpu_to_le16(DRIVER_PRODUCT_NUM),

.iManufacturer = STRING_MANUFACTURER,

.iProduct = STRING_PRODUCT,

.iSerialNumber = STRING_SERIAL,

.bNumConfigurations = 1,

};

static struct usb_endpoint_descriptor fs_sink_desc = { //端点描述符

.bLength = USB_DT_ENDPOINT_SIZE,

.bDescriptorType = USB_DT_ENDPOINT,

.bEndpointAddress = USB_DIR_OUT, //对主机端来说，输出

.bmAttributes = USB_ENDPOINT_XFER_BULK,

};

static struct usb_config_descriptor loopback_config = { //配置描述符

.bLength = sizeof loopback_config,

.bDescriptorType = USB_DT_CONFIG,

/* compute wTotalLength on the fly */

.bNumInterfaces = 1,

.bConfigurationValue = CONFIG_LOOPBACK,

.iConfiguration = STRING_LOOPBACK,

.bmAttributes = USB_CONFIG_ATT_ONE | USB_CONFIG_ATT_SELFPOWER,

.bMaxPower = 1, /* self-powered */

};

static const struct usb_interface_descriptor loopback_intf = { //接口描述符

.bLength = sizeof loopback_intf,

.bDescriptorType = USB_DT_INTERFACE,

.bNumEndpoints = 1,

.bInterfaceClass = USB_CLASS_VENDOR_SPEC,

.iInterface = STRING_LOOPBACK,

};

/* static strings, in UTF-8 */

#define STRING_MANUFACTURER 25

#define STRING_PRODUCT 42

#define STRING_SERIAL 101

#define STRING_SOURCE_SINK 250

#define STRING_LOOPBACK 251

static char manufacturer[50];

/* default serial number takes at least two packets */

static char serial[] = "0123456789.0123456789.0123456789";

static struct usb_string strings[] = { //字符串描述符

{ STRING_MANUFACTURER, manufacturer, },

{ STRING_PRODUCT, longname, },

{ STRING_SERIAL, serial, },

{ STRING_LOOPBACK, loopback, },

{ STRING_SOURCE_SINK, source_sink, },

{ } /* end of list */

};

static struct usb_gadget_strings stringtab = {

.language = 0x0409, /* en-us */

.strings = strings,

};

static const struct usb_descriptor_header *fs_loopback_function[] = {

(struct usb_descriptor_header *) &loopback_intf,

(struct usb_descriptor_header *) &fs_sink_desc,

NULL,

};

static int

usb_zero_open (struct inode *inode, struct file *file) //打开设备

{

struct zero_dev *dev =

container_of (inode->i_cdev, struct zero_dev, cdev);

file->private_data = dev;

init_waitqueue_head (&dev->bulkrq);

return 0;

}

static int

usb_zero_release (struct inode *inode, struct file *file) //关闭设备

{

return 0;

}

static void free_ep_req(struct usb_ep *ep, struct usb_request *req)

{

kfree(req->buf);

usb_ep_free_request(ep, req);

}

static struct usb_request *alloc_ep_req(struct usb_ep *ep, unsigned length)//分配请求

{

struct usb_request *req;

req = usb_ep_alloc_request(ep, GFP_ATOMIC);

if (req) {

req->length = length;

req->buf = kmalloc(length, GFP_ATOMIC);

if (!req->buf) {

usb_ep_free_request(ep, req);

req = NULL;

}

}

return req;

}

static void source_sink_complete(struct usb_ep *ep, struct usb_request *req)//请求完成函数

{

struct zero_dev *dev = ep->driver_data;

int status = req->status;

switch (status) {

case 0: /* normal completion */

if (ep == dev->out_ep) {

memcpy(dev->data, req->buf, req-> actual);//返回数据拷贝到req->buf中， //dev->data_size=req->length;

dev->data_size=req->actual; //实际长度为req-> actual；需要确认

req –>short_not_ok为0。参考gadget.h中关于usb_request结构的注释

}

break;

/* this endpoint is normally active while we're configured */

case -ECONNABORTED: /* hardware forced ep reset */

case -ECONNRESET: /* request dequeued */

case -ESHUTDOWN: /* disconnect from host */

printk("%s gone (%d), %d/%d\n", ep->name, status,

req->actual, req->length);

case -EOVERFLOW: /* buffer overrun on read means that

* we didn't provide a big enough

* buffer.

*/

default:

#if 1

printk("%s complete --> %d, %d/%d\n", ep->name,

status, req->actual, req->length);

#endif

case -EREMOTEIO: /* short read */

break;

}

free_ep_req(ep, req);

wake_up_interruptible (&dev->bulkrq); //唤醒读函数

}

static struct usb_request *source_sink_start_ep(struct usb_ep *ep)//构造并发送读请求

{

struct usb_request *req;

int status;

//printk("in %s\n",__FUNCTION__);

req = alloc_ep_req(ep, 128);

if (!req)

return NULL;

memset(req->buf, 0, req->length);

req->complete = source_sink_complete; //请求完成函数

status = usb_ep_queue(ep, req, GFP_ATOMIC); //递交请求

if (status) {

struct zero_dev *dev = ep->driver_data;

printk("start %s --> %d\n", ep->name, status);

free_ep_req(ep, req);

req = NULL;

}

return req;

}

ssize_t

usb_zero_read (struct file * file, const char __user * buf, size_t count,loff_t * f_pos) //读设备

{

struct zero_dev *dev =file->private_data;

struct usb_request *req;

int status;

struct usb_ep *ep;

struct usb_gadget *gadget = dev->gadget;

ssize_t ret = 0;

int result;

ep=dev->out_ep;

source_sink_start_ep(ep);//构造、递交读请求

if (count < 0)

return -EINVAL;

interruptible_sleep_on (&dev->bulkrq);//睡眠，等到请求完成

if (copy_to_user (buf,dev->data,dev->data_size)) //拷贝读取的数据到用户空间

{

ret = -EFAULT;

}

else

{

ret = dev->data_size;

}

return ret;

}

struct file_operations usb_zero_fops = {

.owner = THIS_MODULE,

.read = usb_zero_read,

.open = usb_zero_open,

.release = usb_zero_release,

};

static void

usb_zero_setup_cdev (struct zero_dev *dev, int minor)//注册字符设备驱动

{

int err, devno = MKDEV (usb_zero_major, minor);

cdev_init(&dev->cdev, &usb_zero_fops);

dev->cdev.owner = THIS_MODULE;

err = cdev_add (&dev->cdev, devno, 1);

if (err)

printk ("Error adding usb_rcv\n");

}

static void zero_setup_complete(struct usb_ep *ep, struct usb_request *req)//配置端点0的请求

完成处理

{

if (req->status || req->actual != req->length)

printk("setup complete --> %d, %d/%d\n",

req->status, req->actual, req->length);

}

static void zero_reset_config(struct zero_dev *dev) //复位配置

{

usb_ep_disable(dev->out_ep);

dev->out_ep = NULL;

}

static void zero_disconnect(struct usb_gadget *gadget)//卸载驱动时被调用，做一些注销工作

{

struct zero_dev *dev = get_gadget_data(gadget);

unsigned long flags;

unregister_chrdev_region (MKDEV (usb_zero_major, 0), 1);

cdev_del (&(dev->cdev));

zero_reset_config(dev);

printk("in %s\n",__FUNCTION__);

}

static int config_buf(struct usb_gadget *gadget,

u8 *buf, u8 type, unsigned index)

{

//int is_source_sink;

int len;

const struct usb_descriptor_header **function;

int hs = 0;

function =fs_loopback_function;//根据fs_loopback_function，得到长度，

//此处len=配置（9）+1个接口（9）+1个端点（7）=25

len = usb_gadget_config_buf(&loopback_config,

buf, USB_BUFSIZ, function);

if (len < 0)

return len;

((struct usb_config_descriptor *) buf)->bDescriptorType = type;

return len;

}

static int set_loopback_config(struct zero_dev *dev)

{

int result = 0;

struct usb_ep *ep;

struct usb_gadget *gadget = dev->gadget;

ep=dev->out_ep;

const struct usb_endpoint_descriptor *d;

d = &fs_sink_desc;

result = usb_ep_enable(ep, d); //激活端点

//printk("");

if (result == 0) {

printk("connected\n"); //如果成功，打印“connected”

}

else

printk("can't enable %s, result %d\n", ep->name, result);

return result;

}

static int zero_set_config(struct zero_dev *dev, unsigned number)

{

int result = 0;

struct usb_gadget *gadget = dev->gadget;

result = set_loopback_config(dev);//激活设备

if (result)

zero_reset_config(dev); //复位设备

else {

char *speed;

switch (gadget->speed) {

case USB_SPEED_LOW: speed = "low"; break;

case USB_SPEED_FULL: speed = "full"; break;

case USB_SPEED_HIGH: speed = "high"; break;

default: speed = " "; break;

}

}

return result;

}

/***

zero_setup完成USB设置阶段和具体功能相关的交互部分

***/

static int

zero_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl)

{

struct zero_dev *dev = get_gadget_data(gadget);

struct usb_request *req = dev->req;

int value = -EOPNOTSUPP;

u16 w_index = le16_to_cpu(ctrl->wIndex);

u16 w_value = le16_to_cpu(ctrl->wValue);

u16 w_length = le16_to_cpu(ctrl->wLength);

/* usually this stores reply data in the pre-allocated ep0 buffer,

* but config change events will reconfigure hardware.

*/

req->zero = 0;

switch (ctrl->bRequest) {

case USB_REQ_GET_DESCRIPTOR: //获取描述符

if (ctrl->bRequestType != USB_DIR_IN)

goto unknown;

switch (w_value >> 8) {

case USB_DT_DEVICE: //获取设备描述符

value = min(w_length, (u16) sizeof device_desc);

memcpy(req->buf, &device_desc, value);

break;

case USB_DT_CONFIG: //获取配置，注意：会根据fs_loopback_function读取到接口、端点描述符，注意通过config_buf完成读取数据及数量的统计。

value = config_buf(gadget, req->buf,

w_value >> 8,

w_value & 0xff);

if (value >= 0)

value = min(w_length, (u16) value);

break;

case USB_DT_STRING:

value = usb_gadget_get_string(&stringtab,

w_value & 0xff, req->buf);

if (value >= 0)

value = min(w_length, (u16) value);

break;

}

break;

case USB_REQ_SET_CONFIGURATION:

if (ctrl->bRequestType != 0)

goto unknown;

spin_lock(&dev->lock);

value = zero_set_config(dev, w_value);//激活相应的端点

spin_unlock(&dev->lock);

break;

default:

unknown:

printk(

"unknown control req%02x.%02x v%04x i%04x l%d\n",

ctrl->bRequestType, ctrl->bRequest,

w_value, w_index, w_length);

}

/* respond with data transfer before status phase */

if (value >= 0) {

req->length = value;

req->zero = value < w_length;

value = usb_ep_queue(gadget->ep0, req, GFP_ATOMIC);//通过端点0完成setup

if (value < 0) {

printk("ep_queue --> %d\n", value);

req->status = 0;

zero_setup_complete(gadget->ep0, req);

}

}

/* device either stalls (value < 0) or reports success */

return value;

}

static void zero_unbind(struct usb_gadget *gadget) //解除绑定

{

struct zero_dev *dev = get_gadget_data(gadget);

printk("unbind\n");

unregister_chrdev_region (MKDEV (usb_zero_major, 0), 1);

cdev_del (&(dev->cdev));

/* we've already been disconnected ... no i/o is active */

if (dev->req) {

dev->req->length = USB_BUFSIZ;

free_ep_req(gadget->ep0, dev->req);

}

kfree(dev);

set_gadget_data(gadget, NULL);

}

static int __init zero_bind(struct usb_gadget *gadget) //绑定过程

{

struct zero_dev *dev;

struct usb_ep *ep;

int gcnum;

usb_ep_autoconfig_reset(gadget);

ep = usb_ep_autoconfig(gadget, &fs_sink_desc);//根据端点描述符及控制器端点情况，分配一个合适的端点。

if (!ep)

goto enomem;

EP_OUT_NAME = ep->name; //记录名称

gcnum = usb_gadget_controller_number(gadget);//获得控制器代号

if (gcnum >= 0)

device_desc.bcdDevice = cpu_to_le16(0x0200 + gcnum);//赋值设备描述符

else {

pr_warning("%s: controller '%s' not recognized\n",

shortname, gadget->name);

device_desc.bcdDevice = __constant_cpu_to_le16(0x9999);

}

dev = kzalloc(sizeof(*dev), GFP_KERNEL); //分配设备结构体

if (!dev)

return -ENOMEM;

spin_lock_init(&dev->lock);

dev->gadget = gadget;

set_gadget_data(gadget, dev);

dev->req = usb_ep_alloc_request(gadget->ep0, GFP_KERNEL);//分配一个请求

if (!dev->req)

goto enomem;

dev->req->buf = kmalloc(USB_BUFSIZ, GFP_KERNEL);

if (!dev->req->buf)

goto enomem;

dev->req->complete = zero_setup_complete;

dev->out_ep=ep; //记录端点（就是接收host端数据的端点）

printk("name=%s\n",dev->out_ep->name); //打印出这个端点的名称

ep->driver_data=dev;

device_desc.bMaxPacketSize0 = gadget->ep0->maxpacket;

usb_gadget_set_selfpowered(gadget);

gadget->ep0->driver_data = dev;

snprintf(manufacturer, sizeof manufacturer, "%s %s with %s",

init_utsname()->sysname, init_utsname()->release,

gadget->name);

/**************************字符设备注册*******************/

dev_t usb_zero_dev = MKDEV (usb_zero_major, 0);

int result = register_chrdev_region (usb_zero_dev, 1, "usb_zero");

if (result < 0)

{

printk (KERN_NOTICE "Unable to get usb_transfer region, error %d\n",result);

return 0;

}

usb_zero_setup_cdev (dev, 0);

return 0;

enomem:

zero_unbind(gadget);

return -ENOMEM;

}

/*-------------------------------------------------------------------------*/

static struct usb_gadget_driver zero_driver = { //gadget驱动的核心数据结构

#ifdef CONFIG_USB_GADGET_DUALSPEED

.speed = USB_SPEED_HIGH,

#else

.speed = USB_SPEED_FULL,

#endif

.function = (char *) longname,

.bind = zero_bind,

.unbind = __exit_p(zero_unbind),

.setup = zero_setup,

.disconnect = zero_disconnect,

//.suspend = zero_suspend, //不考虑电源管理的功能

//.resume = zero_resume,

.driver = {

.name = (char *) shortname,

.owner = THIS_MODULE,

},

};

MODULE_AUTHOR("David Brownell");

MODULE_LICENSE("GPL");

static int __init init(void)

{

return usb_gadget_register_driver(&zero_driver); //注册驱动，调用bind绑定到控制器

}

module_init(init);

static void __exit cleanup(void)

{

usb_gadget_unregister_driver(&zero_driver); //注销驱动，通常会调用到unbind解除绑定， //在s3c2410_udc.c中调用的是disconnect方法

}

module_exit(cleanup);