USB设备---URB请求块

1．urb 结构体

USB 请求块（USB request block，urb）是USB 设备驱动中用来描述与USB 设备通信所用的基本载体和核心数据结构，非常类似于网络设备驱动中的sk_buff 结构体。

struct urb
 {

/*
 私有的：只能由USB 核心和主机控制器访问的字段 */

struct kref
 kref; /*urb
 引用计数 */

void *hcpriv; /*
 主机控制器私有数据 */

atomic_t
 use_count; /*
 并发传输计数 */

u8
 reject; /*
 传输将失败*/

int unlink; /*
 unlink 错误码 */

 /*
 公共的： 可以被驱动使用的字段 */

 struct list_head
 urb_list; /*
 链表头*/

struct usb_anchor
 *anchor;

 struct usb_device
 *dev; /*
 关联的USB 设备 */

 struct usb_host_endpoint
 *ep;

unsigned int pipe; /*
 管道信息 */

 int status; /*
 URB 的当前状态 */

 unsigned int transfer_flags; /*
 URB_SHORT_NOT_OK | ...*/

 void *transfer_buffer; /*
 发送数据到设备或从设备接收数据的缓冲区 */

 dma_addr_t
 transfer_dma; /*用来以DMA
 方式向设备传输数据的缓冲区 */

 int transfer_buffer_length;/*transfer_buffer
 或transfer_dma 指向缓冲区的大小 */

 

 int actual_length; /*
 URB 结束后，发送或接收数据的实际长度 */

 unsigned char *setup_packet; /*
 指向控制URB 的设置数据包的指针*/

 dma_addr_t
 setup_dma; /*控制URB
 的设置数据包的DMA 缓冲区*/

 int start_frame; /*等时传输中用于设置或返回初始帧*/

 int number_of_packets; /*等时传输中等时缓冲区数量
 */

 int interval; /*
 URB 被轮询到的时间间隔（对中断和等时urb 有效） */

 int error_count; /*
 等时传输错误数量 */

 void *context; /*
 completion 函数上下文 */

 usb_complete_t
 complete; /*
 当URB 被完全传输或发生错误时，被调用 */

 /*单个URB
 一次可定义多个等时传输时，描述各个等时传输 */

 struct usb_iso_packet_descriptor
 iso_frame_desc[0];

};

2．urb 处理流程

USB 设备中的每个端点都处理一个urb 队列，在队列被清空之前，一个urb 的典型生命周期
如下。

（1）被一个USB 设备驱动创建。（创建URB）

创建urb 结构体的函数为：
struct urb *usb_alloc_urb(int iso_packets, int mem_flags);
iso_packets 是这个urb 应当包含的等时数据包的数目，若为0 表示不创建等时数据包。
mem_flags 参数是分配内存的标志，和kmalloc()函数的分配标志参数含义相同。如果分配成功，该函数返回一个urb 结构体指针，否则返回0。
urb 结构体在驱动中不能静态创建，因为这可能破坏USB 核心给urb 使用的引用计数方法。

usb_alloc_urb()的“反函数”为：
void usb_free_urb(struct urb *urb);
该函数用于释放由usb_alloc_urb()分配的urb 结构体。

（2）初始化，被安排给一个特定USB 设备的特定端点。（填充URB）

对于中断urb，使用usb_fill_int_urb()函数来初始化urb，如下所示：
void usb_fill_int_urb(struct urb *urb,

struct usb_device *dev,

unsigned int pipe,

void *transfer_buffer,

int buffer_length,

usb_complete_t complete,

void *context,

int interval);

urb 参数指向要被初始化的urb 的指针；dev 指向这个urb 要被发送到的USB 设备；pipe 是这个urb 要被发送到的USB 设备的特定端点；transfer_buffer 是指向发送数据或接收数据的缓冲区的指针，和urb 一样，它也不能是静态缓冲区，必须使用kmalloc()来分配；buffer_length 是transfer_buffer 指针所指向缓冲区的大小；complete 指针指向当这个 urb 完成时被调用的完成处理函数；context 是完成处理函数的“上下文”；interval 是这个urb 应当被调度的间隔。

上述函数参数中的pipe 使用usb_sndintpipe()或usb_rcvintpipe()创建。

对于批量urb，使用usb_fill_bulk_urb()函数来初始化urb，如下所示：
void usb_fill_bulk_urb(struct urb *urb, struct usb_device *dev,unsigned int pipe, void *transfer_buffer,int buffer_length, usb_complete_t complete,void *context);
除了没有对应于调度间隔的interval 参数以外，该函数的参数和usb_fill_int_urb()函数的参数含义相同。
上述函数参数中的pipe 使用usb_sndbulkpipe()或者usb_rcvbulkpipe()函数来创建。

对于控制 urb，使用usb_fill_control_urb()函数来初始化urb，如下所示：
void usb_fill_control_urb(struct urb *urb, struct usb_device *dev,unsigned int pipe, unsigned char *setup_packet,void *transfer_buffer, int buffer_length,usb_complete_t complete, void *context);
除了增加了新的setup_packet 参数以外，该函数的参数和usb_fill_bulk_urb()函数的参数含义相同。setup_packet 参数指向即将被发送到端点的设置数据包。
上述函数参数中的pipe 使用usb_sndctrlpipe()或usb_rcvictrlpipe()函数来创建。

unsigned int pipe  
一个管道号码，该管道记录了目标设备的端点以及管道的类型。每个管道只有一种类型和一个方向，它与他的目标设备的端点相对应，我们可以通过以下几个函数来获得管道号并设置管道类型：  
unsigned int usb_sndctrlpipe(struct usb_device *dev, unsigned int endpoint)  
     把指定USB设备的指定端点设置为一个控制OUT端点。  
unsigned int usb_rcvctrlpipe(struct usb_device *dev, unsigned int endpoint)  
     把指定USB设备的指定端点设置为一个控制IN端点。  
unsigned int usb_sndbulkpipe(struct usb_device *dev, unsigned int endpoint)  
     把指定USB设备的指定端点设置为一个批量OUT端点。 /* 把数据从批量OUT端口发出 */ 
unsigned int usb_rcvbulkpipe(struct usb_device *dev, unsigned int endpoint)  
     把指定USB设备的指定端点设置为一个批量IN端点。  
unsigned int usb_sndintpipe(struct usb_device *dev, unsigned int endpoint)  
   把指定USB设备的指定端点设置为一个中断OUT端点。  
unsigned int usb_rcvintpipe(struct usb_device *dev, unsigned int endpoint)  
     把指定USB设备的指定端点设置为一个中断IN端点。  
unsigned int usb_sndisocpipe(struct usb_device *dev, unsigned int endpoint)  
     把指定USB设备的指定端点设置为一个等时OUT端点。  
unsigned int usb_rcvisocpipe(struct usb_device *dev, unsigned int endpoint)  
     把指定USB设备的指定端点设置为一个等时IN端点。

（3）被USB 设备驱动提交给USB 核心。(提交URB)

在完成第（1）、（2）步的创建和初始化urb 后，urb 便可以提交给USB 核心，通过usb_submit_urb()函数来完成，如下所示：
int usb_submit_urb(struct urb *urb, int mem_flags);
urb 参数是指向urb 的指针，mem_flags 参数与传递给kmalloc()函数参数的意义相同，它用于告知USB 核心如何在此时分配内存缓冲区。
在提交urb 到USB 核心后，直到完成函数被调用之前，不要访问urb 中的任何成员。

usb_submit_urb()在原子上下文和进程上下文中都可以被调用，mem_flags 变量需根据调用环
境进行相应的设置，如下所示。
GFP_ATOMIC：在中断处理函数、底半部、tasklet、定时器处理函数以及urb 完成函数中，在调用者持有自旋锁或者读写锁时以及当驱动将current→state 修改为非 TASK_RUNNING 时，应使用此标志。
GFP_NOIO：在存储设备的块I/O 和错误处理路径中，应使用此标志；
GFP_KERNEL：如果没有任何理由使用GFP_ATOMIC 和GFP_NOIO，就使用GFP_KERNEL。

如果usb_submit_urb()调用成功，即urb 的控制权被移交给USB 核心，该函数返回0；否则，
返回错误号。

（4）提交由USB 核心指定的USB 主机控制器驱动。
（5）被USB 主机控制器处理，进行一次到USB 设备的传送。

第（4）～（5）步由USB 核心和主机控制器完成，不受USB 设备驱动的控制。

（6）当urb 完成，USB 主机控制器驱动通知USB 设备驱动。

(处理URB)

在如下3 种情况下，urb 将结束，urb 完成函数将被调用。
1、urb 被成功发送给设备，并且设备返回正确的确认。如果urb→status 为0，意味着对于一个输出urb，数据被成功发送；对于一个输入urb，请求的数据被成功收到。
2、如果发送数据到设备或从设备接收数据时发生了错误，urb→status 将记录错误值。
3、urb 被从USB 核心“去除连接”，这发生在驱动通过usb_unlink_urb()或usb_kill_urb()函数取消urb，或urb 虽已提交，而USB 设备被拔出的情况下。

当urb 生命结束时（处理完成或被解除链接），通过urb 结构体的status 成员可以获知其原因，
如0 表示传输成功，-ENOENT 表示被usb_kill_urb()杀死，-ECONNRESET 表示被usb_unlink_urb()
杀死，-EPROTO 表示传输中发生了bitstuff 错误或者硬件未能及时收到响应数据包，-ENODEV
表示USB 设备已被移除，-EXDEV 表示等时传输仅完成了一部分等。

对以上urb 的处理步骤进行一个总结，图20.5 给出了一个urb 的整个处理流程，虚线框的usb_unlink_urb()和usb_kill_urb()并非一定会发生，它只是在urb 正在被USB 核心和主机控制器处理时，被驱动程序取消的情况下才发生。

（7）. urb的取消

如果想取消之前提交的urb，可以用usb_unlink_urb来实现:

int usb_unlink_urb(struct urb *urb);

3．简单的批量与控制URB

用前面的方式提交urb或取消urb时，程序不会阻塞，属于异步方式。除了异步方式外，usb还可用同步方式来提交和取消urb。同样由于isochronous中发送数据包个数不确定性，驱动只实现了control,interrupt和bulk三种方式的同步方式操作urb接口。

有时USB驱动程序只是从USB设备上接收或向USB设备发送一些简单的数据，这时候，没有必要将urb创建、初始化、提交、完成处理的整个流程走一遍，而可以使用两个更简单的函数，如下所示。

（1）usb_bulk_msg()

usb_bulk_msg()函数创建一个USB批量urb 并将它发送到特定设备，这个函数是同步的，它一直等待urb完成后才返回。usb_bulk_msg()函数的原型为：

int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
                 void *data, int len, int *actual_length,
                 int timeout);

usb_dev参数为批量消息要发送的USB 设备的指针，pipe为批量消息要发送到的USB设备的端点，data参数为指向要发送或接收的数据缓冲区的指针，len参数为data参数所指向的缓冲区的长度，actual_length用于返回实际发送或接收的字节数，timeout是发送超时，以jiffies为单位，0意味着永远等待。

如果函数调用成功，返回0；否则，返回1个负的错误值。

（2）usb_control_msg()函数

usb_control_msg()函数与usb_bulk_msg()函数类似，不过它提供驱动发送和结束USB控制信息而非批量信息的能力，该函数的原型为：

int usb_control_msg(struct usb_device *dev, unsigned int pipe, __u8 request, 
                    __u8 requesttype, __u16 value, __u16 index, void *data, __u16 size, int timeout);

dev指向控制消息发往的USB设备，pipe是控制消息要发往的USB设备的端点，request是这个控制消息的USB请求值，requesttype是这个控制消息的USB请求类型，value是这个控制消息的USB消息值，index是这个控制消息的USB消息索引值，data指向要发送或接收的数据缓冲区，size是data参数所指向的缓冲区的大小，timeout是发送超时，以jiffies为单位，0意味着永远等待。
参数request、requesttype、value和index与USB规范中定义的USB控制消息直接对应。

如果函数调用成功，该函数返回发送到设备或从设备接收到的字节数；否则，返回一个负的错误值。

对usb_bulk_msg()和usb_control_msg()函数的使用要特别慎重，由于它们是同步的，因此不能在中断上下文和持有自旋锁的情况下使用。而且，该函数也不能被任何其他函数取消，因此，务必要使得驱动程序的disconnect()函数掌握足够的信息，以判断和等待该调用的结束。

（3）usb_interrupt_msg() 函数

int usb_interrupt_msg(struct usb_device *usb_dev, unsigned int pipe, void *data, int len, int *actual_length, int timeout)

上面三个接口函数都已经将之前提到过的申请urb,填充urb和提交urb过程封装在一起，在使用时只要指定对应该数据，数据长度及超时时间就可以。在使用上面三个接口提交urb时，程序阻塞，直到超时或urb提交成功并通过回调函数返回结果并唤醒等待队列。

在同步方式下对应的urb取消函数接口为：

void usb_kill_urb(struct urb *urb)

usb_kill_urb提交取消urb申请后，会一直等待urb取消完成才会退出，里面的等待也是通过等待队列实现的。

参考：

https://www.cnblogs.com/chd-zhangbo/p/5261045.html

http://book.51cto.com/art/200803/66930.htm

http://blog.sina.com.cn/s/blog_a336aee70102x5hk.html