LINUX中USB驱动架构—URB请求块

USB本身所属设备驱动的结构与其挂不挂在USB总线上没什么关系,但是据此在访问方式上却有 很大的变化,例如,对于USB接口的字符设备而言,尽管仍然是write()、read()、ioctl()这些函数,但是在这些函数中,贯穿始终的是称为URB的USB请求块。

一、USB请求块

1.urb结构体

USB请求块(USB Request Block,URB)是USB设备驱动中用来描述与USB设备通信所用的基本载体 和核心数据结构。

复制代码
struct urb {
  ...
  /* public: documented fields in the urb that can be used by drivers */
     struct list_head urb_list; /* list head for use by the urb's
  * current owner */
  ...
      struct usb_host_endpoint *ep; /* (internal) pointer to endpoint */
      unsigned int pipe; /* (in) pipe information */
      unsigned int stream_id; /* (in) stream ID */
      int status; /* (return) non-ISO status */
      unsigned int transfer_flags; /* (in) URB_SHORT_NOT_OK | ...*/
      void *transfer_buffer; /* (in) associated data buffer */
      dma_addr_t transfer_dma; /* (in) dma addr for transfer_buffer */
      struct scatterlist *sg; /* (in) scatter gather buffer list */
      int num_mapped_sgs; /* (internal) mapped sg entries */
      int num_sgs; /* (in) number of entries in the sg list */ 
      u32 transfer_buffer_length;         /* (in) data buffer length */
      u32 actual_length; /* (return) actual transfer length */
      unsigned char *setup_packet; /* (in) setup packet (control only) */
      dma_addr_t setup_dma; /* (in) dma addr for setup_packet */
      int start_frame; /* (modify) start frame (ISO) */
      int number_of_packets; /* (in) number of ISO packets */
      int interval; /* (modify) transfer interval * (INT/ISO) */
      int error_count; /* (return) number of ISO errors */
      void *context; /* (in) context for completion */
      usb_complete_t complete; /* (in) completion routine */
      struct usb_iso_packet_descriptor iso_frame_desc[0]; /* (in) ISO ONLY */
};
2.URB处理流程

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

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

创建URB结构体的函数为:

复制代码
struct urb *usb_alloc_urb(int iso_packets, gfp_t 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()函数来初始化,如下所示:

复制代码
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()函数来初始化,如下所示:

复制代码
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()函数来创建。

等时URB没有像中断、控制和批量URB的初始化函数usb_fill_iso_urb(),我们只能手动对它初始 化,而后才能提交给USB核心。下面给出了初始化等时URB的例子,它来自 drivers/media/usb/uvc/uvc_video.c文件。

复制代码
for (i = 0; i < UVC_URBS; ++i) {
  urb = usb_alloc_urb(npackets, gfp_flags);
  if (urb == NULL) {
  uvc_uninit_video(stream, 1);
  return -ENOMEM;
  }
 
  urb->dev = stream->dev->udev;
  urb->context = stream;
  urb->pipe = usb_rcvisocpipe(stream->dev->udev,
  ep->desc.bEndpointAddress);
#ifndef CONfiG_DMA_NONCOHERENT
 urb->transfer_flags = URB_ISO_ASAP | URB_NO_TRANSFER_DMA_MAP;
 urb->transfer_dma = stream->urb_dma[i];
#else
 urb->transfer_flags = URB_ISO_ASAP;
#endif
  urb->interval = ep->desc.bInterval;
  urb->transfer_buffer = stream->urb_buffer[i];
  urb->complete = uvc_video_complete;
  urb->number_of_packets = npackets;
  urb->transfer_buffer_length = size;

  for (j = 0; j < npackets; ++j) {
  urb->iso_frame_desc[j].offset = j * psize;
  urb->iso_frame_desc[j].length = psize;
 }

  stream->urb[i] = urb;
}
3)被USB设备驱动提交给USB核心

在完成第1)、2)步的创建和初始化URB后,URB便可以提交给USB核心了,可通过 usb_submit_urb()函数来完成

复制代码
int usb_submit_urb(struct urb *urb, gfp_t 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完成回调函数将被调用(完成回调是通过usb_fill_xxx_urb的参数传入的)。

在完成回调中,我们通常要进行urb->status的判断。 ·URB被成功发送给设备,并且设备返回正确的确认。如果urb->status为0,意味着对于一个输出 URB,数据被成功发送;对于一个输入URB,请求的数据被成功收到。 ·

如果发送数据到设备或从设备接收数据时发生了错误,urb->status将记录错误值。 ·URB被从USB核心"去除连接" ,这发生在驱动通过usb_unlink_urb()或usb_kill_urb()函数取消或 URB虽已提交而USB设备被拔出的情况下。

usb_unlink_urb()和usb_kill_urb()这两个函数用于取消已提交的URB,其参数为要被取消的URB 指针。usb_unlink_urb()是异步的,搞定后对应的完成回调会被调用;而usb_kill_urb()会彻底终止 URB的生命周期并等待这一行为,它通常在设备的disconnect()函数中被调用。

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

给出了一个URB的完整处理流程,虚线框的 usb_unlink_urb()和usb_kill_urb()并不一定会发生,它们只是在URB正在被USB核心和主机控制器处理时又被驱动程序取消的情况下才发生。

3.简单的批量与控制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()函数

dev指向控制消息发往的USB设备,pipe是控制消息要发往的USB设备的端点,request是这个控制消息 的USB请求值,requesttype是这个控制消息的USB请求类型,value是这个控制消息的USB消息值,index是这个控制消息的USB消息索引值,data指向要发送或接收的数据缓冲区,size是data参数所指向的缓冲区的大小,timeout是发送超时,以毫秒为单位,0意味着永远等待。

参数request、requesttype、value和index与USB规范中定义的USB控制消息直接对应。 如果函数调用成功,该函数返回发送到设备或从设备接收到的字节数;否则,返回一个负的错误值。

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

===========================================

USB程序的字符设备文件操作结构体

复制代码
static const struct file_operations skel_fops = { 
  .owner = THIS_MODULE,
  .read = skel_read,
  .write = skel_write,
  .open = skel_open,
  .release = skel_release,
  .flush = skel_flush,
  .llseek = noop_llseek,
};

在skel_write()函数中进行的关于URB的操作与前面的描述完全对应,即进行了URB的分配 (调用usb_alloc_urb())、初始化 (调用usb_fill_bulk_urb())和提交(调用usb_submit_urb())的 操作

复制代码
static ssize_t skel_write(struct file *file, const char *user_buffer,
  size_t count, loff_t *ppos)
{
   struct usb_skel *dev;
   int retval = 0;
   struct urb *urb = NULL;
   char *buf = NULL;
   size_t writesize = min(count, (size_t)MAX_TRANSFER);
 
   dev = file->private_data;
   ...
   spin_lock_irq(&dev->err_lock);
   retval = dev->errors;
   ...
   spin_unlock_irq(&dev->err_lock);
   ...

   /* create a urb, and a buffer for it, and copy the data to the urb */
   urb = usb_alloc_urb(0, GFP_KERNEL);
   ...
   buf = usb_alloc_coherent(dev->udev, writesize, GFP_KERNEL,&urb->transfer_dma);
   ...

 if (copy_from_user(buf, user_buffer, writesize)) {
   retval = -EFAULT;28 goto error;
 }

   /* this lock makes sure we don't submit URBs to gone devices */
   mutex_lock(&dev->io_mutex);
   ...

   /* initialize the urb properly */
   usb_fill_bulk_urb(urb, dev->udev,
   usb_sndbulkpipe(dev->udev, dev->bulk_out_endpointAddr),
   buf, writesize, skel_write_bulk_callback, dev);
   urb->transfer_flags |= URB_NO_TRANSFER_DMA_MAP;
   usb_anchor_urb(urb, &dev->submitted);

   /* send the data out the bulk port */
   retval = usb_submit_urb(urb, GFP_KERNEL);
   mutex_unlock(&dev->io_mutex);
   ...
   usb_free_urb(urb); 
   return writesize;
   ...
}

在写函数中发起的URB结束后,填入的完成函数skel_write_bulk_callback()将被调用,它会 进行urb->status的判断

复制代码
static void skel_write_bulk_callback(struct urb *urb)
{
  struct usb_skel *dev;
 
  dev = urb->context;
 
  /* sync/async unlink faults aren't errors */
  if (urb->status) {
  if (!(urb->status == -ENOENT ||
  urb->status == -ECONNRESET ||
  urb->status == -ESHUTDOWN))
  dev_err(&dev->interface->dev,
  "%s - nonzero write bulk status received: %d\n",__func__, urb->status);
  spin_lock(&dev->err_lock);
  dev->errors = urb->status;
  spin_unlock(&dev->err_lock);
 }

 /* free up our allocated buffer */
  usb_free_coherent(urb->dev, urb->transfer_buffer_length,
  urb->transfer_buffer, urb->transfer_dma);
  up(&dev->limit_sem);
}
相关推荐
知星小度S4 小时前
系统核心解析:深入操作系统内部机制——进程管理与控制指南(一)【进程/PCB】
linux·运维·服务器·进程
Empty_7778 小时前
SELinux安全上下文
linux·服务器·安全
bug攻城狮9 小时前
解决Ubuntu中apt-get -y安装时弹出交互提示的问题
linux·运维·ubuntu
xiachong279 小时前
ubuntu18.04安装PCL1.14
linux·ubuntu
夜阑珊夭夭10 小时前
linux自定义网卡名字
linux·运维
czhc114007566310 小时前
Linux912 shell:$# $1 $?;RHEL 8 AppStream BaseOS
linux
佛天华10 小时前
centos 时间校准
linux·运维·centos
小柯J桑_11 小时前
Linux:线程封装
linux·运维·c++
先锋队长11 小时前
linux系统搭建nacos集群,并通过nginx实现负载均衡
linux·nginx·负载均衡