Linux驱动 | USB设备驱动中的URB数据结构

尽管 USB 本身所属设备驱动的结构与其不挂在 USB 总线上时完全相同，但是在访问方式上却发生了很大的变化，例如，对于字符设备而言，尽管仍然是 write()、read()、ioctl()这些函数，但是在这些函数中，与 USB 设备通信时不再是 I/O 内存和 I/O 端口的访问，而贯穿始终的是称为 URB 的 USB 请求块。 

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

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

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

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

spinlock_t lock; /* urb 锁 */

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

int bandwidth; /* INT/ISO 请求的带宽 */

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

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

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

struct list_head urb_list; /* 链表头*/

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

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 被完全传输或发生错误时，被调用 */

struct usb_iso_packet_descriptor iso_frame_desc[0]; /*单个 URB 一次可定义多个等时传输时，描述各个等时传输 */

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

当 transfer_flags 标志中的 URB_NO_TRANSFER_DMA_MAP 被置位时，USB 核心将使用 transfer_dma指向的缓冲区而非 transfer_buffer指向的缓冲区，意味着即将传输 DMA缓冲区。

当 transfer_flags 标志中的 URB_NO_SETUP_DMA_MAP 被置位时，对于有 DMA缓冲区的控制 urb而言，USB核心将使用 setup_dma指向的缓冲区而非 setup_packet指向的缓冲区。

 

URB处理流程

USB 设备中的每个端点都处理一个 urb 队列。

一个 urb 的典型生命周期如下：

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

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

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

（4）提交由 USB 核心指定的 USB 主机控制器驱动。

（5）被 USB 主机控制器处理，进行一次到 USB 设备的传送。

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

（6）当 urb 完成，USB 主机控制器驱动通知 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()分配的 urb 结构体：

void usb_free_urb(struct urb *urb);

 

urb的初始化

1. 对于中断 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应当被调度的间隔。

（int）pipe的创建：使用usb_sndintpipe()或 usb_rcvintpipe()函数

 

2. 对于批量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参数

(bulk) pipe的创建：使用 usb_sndbulkpipe()或者 usb_rcvbulkpipe()函数

 

3. 对于控制urb，使用 usb_fill_contorl_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 参数指向即将被发送到端点的设置数据包。

(ctrl)pipe的创建：使用usb_sndctrlpipe()或者usb_rcvctrlpipe()函数

 

4.对于等时urb，只能手动地初始化urb，而后提交给USB核心

实例（from drivers/usb/media/usbvideo.c）

for (i = 0; i < USBVIDEO_NUMSBUF; i++)

{

int j, k;

struct urb *urb = uvd->sbuf[i].urb;

urb->dev = dev;

urb->context = uvd;

urb->pipe = usb_rcvisocpipe(dev, uvd->video_endp);

urb->interval = 1;

urb->transfer_flags = URB_ISO_ASAP; /*urb 被调度*/

urb->transfer_buffer = uvd->sbuf[i].data;/*传输 buffer*/

urb->complete = usbvideo_IsocIrq; /* 完成函数 */

urb->number_of_packets = FRAMES_PER_DESC; /*urb 中的等时传输数量*/

urb->transfer_buffer_length = uvd->iso_packet_len *FRAMES_PER_DESC;

for (j = k = 0; j < FRAMES_PER_DESC; j++, k += uvd->iso_packet_len)

{

urb->iso_frame_desc[j].offset = k;

urb->iso_frame_desc[j].length = uvd->iso_packet_len;

 }

}

 

urb的提交（提交给usb核心）

int usb_submit_urb(struct urb *urb, int mem_flags);

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

在提交 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核心：提交由 USB 核心指定的 USB 主机控制器驱动

USB 主机控制器：进行一次到 USB 设备的传送

 

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

 

以下情况下，urb完成函数将被调用

（1）urb 被成功发送给设备，并且设备返回正确的确认。如果urb->status 为 0，意味着对于一个输出 urb，数据被成功发送；对于一个输入urb，请求的数据被成功收到。

（2）如果发送数据到设备或从设备接收数据时发生了错误，urb->status 将记录错误值。

（3）urb 被从 USB 核心“去除连接”，这发生在驱动通过 usb_unlink_urb()或usb_kill_urb()函数取消 urb，或 urb虽已提交，而 USB 设备被拔出的情况下。

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

对 usb_unlink_urb() 而 言，如 果 urb 结 构 体中的URB_ASYNC_UNLINK（即异步 unlink）的标志被置位，则对该 urb 的 usb_unlink_urb()调用将立即返回，具体的 unlink 动作将在后台进行。否则，此函数一直等到 urb 被解开链接或结束时才返回。

usb_kill_urb()会彻底终止 urb 的生命周期，它通常在设备的disconnect()函数中被调用。

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

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

简单的批量与控制 URB

（1）usb_bulk_msg()函数

（2）usb_control_msg()函数

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

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

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

 

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()函数掌握足够的信息，以判断和等待该调用的结束。

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