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 结构体的函数为:
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,使用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()函数来创建。
(3)被USB 设备驱动提交给USB 核心。
在完成第(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 设备驱动。
在如下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 核心和主机控制器处理时,被驱动程序取消的情况下才发生。