Linuxusb6.HC/UDC测试

1. 背景介绍

在测试 USB 时&＃xff0c;普通的做法是找一些 U 盘、鼠标、键盘 等外设来做一些测试&＃xff0c;但是这些测试还是偏上层偏功能的。相比较 HC (USB Host Controller) 和 UDC (USB Device Controller) 按照USB协议提供的完整功能来说&＃xff0c;这种测试验证时不充分的。

在 Linux Kernel 中对 HC/UDC 有一套专有的测试方案&＃xff0c;在底层对 control/bulk/int/iso 几种 endpoint 进行针对性的功能和压力测试。

上图的测试方案由几部分组成&＃xff1a;

• 1、Device 侧的 gadget zero 测试设备&＃xff0c;提供了测试通道。
• 2、Host 侧的 usbtest.ko 测试驱动&＃xff0c;封装了 30 个 endpoint 层级的测试用例。
• 3、Host 侧的 testusb 用户程序&＃xff0c;用来调用 usbtest.ko 提供的测试用例。

2. Device (gadget zero)

提供测试需要的Device设备有很多种方式&＃xff0c;例如可用使用专门的测试 Device 里面烧录专有的测试 Firmware。节约成本的方式还是使用 Linux gadget 功能来动态模拟 USB Device 设备。针对 USB 测试&＃xff0c;Linux 专门提供了 gadget zero 设备。

2.1 gadget zero 创建

gadget zero 的核心是创建一个 Composite Device&＃xff0c;其包含了两个 Configuration&＃xff0c;其中一个 Configuration 0 包含 SourceSink Function/Interface&＃xff0c;另一个 Configuration 1 包含 Loopback Function/Interface。某一时刻只能选择使用一个 Configuration&＃xff0c;通常情况下使用 Configuration 0 即 SourceSink的功能。

gadget zero 由两种方式创建&＃xff1a;

• 1、通过 zero_driver 创建&＃xff0c;只要把对应驱动文件 drivers\usb\gadget\legacy\zero.c 编译进内核即可。
• 2、通过 functionfs 动态创建&＃xff0c;这种方式更灵活&＃xff0c;实例命令如下&＃xff1a;

mount -t configfs none /sys/kernel/config
cd /sys/kernel/config/usb_gadgetmkdir g2
cd g2echo "0x04e8" > idVendor
echo "0x2d01" > idProductmkdir configs/c.1
mkdir configs/c.2
mkdir functions/Loopback.0
mkdir functions/SourceSink.0mkdir strings/0x409
mkdir configs/c.1/strings/0x409
mkdir configs/c.2/strings/0x409echo "0x0525" > idVendor
echo "0xa4a0" > idProductecho "0123456789" > strings/0x409/serialnumber
echo "Samsung Inc." > strings/0x409/manufacturer
echo "Bar Gadget" > strings/0x409/productecho "Conf 1" > configs/c.1/strings/0x409/configuration
echo "Conf 2" > configs/c.2/strings/0x409/configuration
echo 120 > configs/c.1/MaxPower// SourceSink&＃xff1a;驱动 set configuration 会选取 第一个 configuration
ln -s functions/Loopback.0 configs/c.2
ln -s functions/SourceSink.0 configs/c.1echo 4100000.udc-controller > UDC


整个过程就是创建了一个 Vendor ID &＃61; 0x0525、Product ID &＃61; 0xa4a0 的 Composite Device&＃xff0c;在 Host 侧可以查看这个设备&＃xff1a;

$ lsusb-s 1:3
Bus 001 Device 003: ID 0525:a4a0 Netchip Technology, Inc. Linux-USB "Gadget Zero"$ lsusb -v -s 1:3Bus 001 Device 003: ID 0525:a4a0 Netchip Technology, Inc. Linux-USB "Gadget Zero"
Couldn&＃39;t open device, some information will be missing
Device Descriptor:bLength 18bDescriptorType 1bcdUSB 2.00bDeviceClass 0 bDeviceSubClass 0 bDeviceProtocol 0 bMaxPacketSize0 64idVendor 0x0525 Netchip Technology, Inc.idProduct 0xa4a0 Linux-USB "Gadget Zero"bcdDevice 5.10iManufacturer 1 iProduct 2 iSerial 3 bNumConfigurations 2Configuration Descriptor:bLength 9bDescriptorType 2wTotalLength 0x0045bNumInterfaces 1bConfigurationValue 1iConfiguration 4 bmAttributes 0x80(Bus Powered)MaxPower 120mAInterface Descriptor:bLength 9bDescriptorType 4bInterfaceNumber 0bAlternateSetting 0bNumEndpoints 2bInterfaceClass 255 Vendor Specific ClassbInterfaceSubClass 0 bInterfaceProtocol 0 iInterface 0 Endpoint Descriptor:bLength 7bDescriptorType 5bEndpointAddress 0x81 EP 1 INbmAttributes 2Transfer Type BulkSynch Type NoneUsage Type DatawMaxPacketSize 0x0200 1x 512 bytesbInterval 0Endpoint Descriptor:bLength 7bDescriptorType 5bEndpointAddress 0x01 EP 1 OUTbmAttributes 2Transfer Type BulkSynch Type NoneUsage Type DatawMaxPacketSize 0x0200 1x 512 bytesbInterval 0Interface Descriptor:bLength 9bDescriptorType 4bInterfaceNumber 0bAlternateSetting 1bNumEndpoints 4bInterfaceClass 255 Vendor Specific ClassbInterfaceSubClass 0 bInterfaceProtocol 0 iInterface 0 Endpoint Descriptor:bLength 7bDescriptorType 5bEndpointAddress 0x81 EP 1 INbmAttributes 2Transfer Type BulkSynch Type NoneUsage Type DatawMaxPacketSize 0x0200 1x 512 bytesbInterval 0Endpoint Descriptor:bLength 7bDescriptorType 5bEndpointAddress 0x01 EP 1 OUTbmAttributes 2Transfer Type BulkSynch Type NoneUsage Type DatawMaxPacketSize 0x0200 1x 512 bytesbInterval 0Endpoint Descriptor:bLength 7bDescriptorType 5bEndpointAddress 0x82 EP 2 INbmAttributes 1Transfer Type IsochronousSynch Type NoneUsage Type DatawMaxPacketSize 0x0400 1x 1024 bytesbInterval 4Endpoint Descriptor:bLength 7bDescriptorType 5bEndpointAddress 0x02 EP 2 OUTbmAttributes 1Transfer Type IsochronousSynch Type NoneUsage Type DatawMaxPacketSize 0x0400 1x 1024 bytesbInterval 4Configuration Descriptor:bLength 9bDescriptorType 2wTotalLength 0x0020bNumInterfaces 1bConfigurationValue 2iConfiguration 5 bmAttributes 0x80(Bus Powered)MaxPower 2mAInterface Descriptor:bLength 9bDescriptorType 4bInterfaceNumber 0bAlternateSetting 0bNumEndpoints 2bInterfaceClass 255 Vendor Specific ClassbInterfaceSubClass 0 bInterfaceProtocol 0 iInterface 6 Endpoint Descriptor:bLength 7bDescriptorType 5bEndpointAddress 0x81 EP 1 INbmAttributes 2Transfer Type BulkSynch Type NoneUsage Type DatawMaxPacketSize 0x0200 1x 512 bytesbInterval 0Endpoint Descriptor:bLength 7bDescriptorType 5bEndpointAddress 0x01 EP 1 OUTbmAttributes 2Transfer Type BulkSynch Type NoneUsage Type DatawMaxPacketSize 0x0200 1x 512 bytesbInterval 0

2.2 SourceSink Function

SourceSink Function 的主要功能是提供了一组 USB 测试 endpoint&＃xff0c;其中:

• Sink。sinks bulk packets OUT to the peripheral。意思是把数据从 Host 引流到 Device&＃xff0c;即 OUT 方向。
• Source。sources them IN to the host。意思是把从 Device 发送数据到 Device&＃xff0c;即 IN 方向。

具体提供了 4 组 测试 endpoint&＃xff1a;

主要流程如下&＃xff1a;

drivers\usb\gadget\function\f_sourcesink.c:sourcesink_bind()&＃xff1a;static int
sourcesink_bind(struct usb_configuration *c, struct usb_function *f)
{/* (1) 从 gadget 中分配 2 个 bulk endpoint *//* allocate bulk endpoints */ss->in_ep &＃61; usb_ep_autoconfig(cdev->gadget, &fs_source_desc);ss->out_ep &＃61; usb_ep_autoconfig(cdev->gadget, &fs_sink_desc);/* (2) 如果支持ISO&＃xff0c;再从 gadget 中分配 2 个 iso endpoint *//* allocate iso endpoints */ss->iso_in_ep &＃61; usb_ep_autoconfig(cdev->gadget, &fs_iso_source_desc);if (!ss->iso_in_ep)goto no_iso;ss->iso_out_ep &＃61; usb_ep_autoconfig(cdev->gadget, &fs_iso_sink_desc);if (!ss->iso_out_ep) {}sourcesink_set_alt() → enable_source_sink() → usb_ep_enable()/source_sink_start_ep()&＃xff1a;
// 启动上述 endpoint→ source_sink_complete():
// urb 的 complete() 函数&＃xff0c;urb 发送/接收完成后&＃xff0c;重新挂载 urb


还支持一些参数调整&＃xff1a;

# ls functions/SourceSink.0/
bulk_buflen iso_qlen isoc_maxburst isoc_mult
bulk_qlen isoc_interval isoc_maxpacket pattern


2.3 Loopback Function

Loopback Function 提供的功能更为简单&＃xff0c;它分配了两个 bulk endpoint&＃xff0c;所做的就是把 out_ep 接收到的数据 转发到 in_ep。

主要流程如下&＃xff1a;

drivers\usb\gadget\function\f_loopback.c:loopback_bind()&＃xff1a;static int loopback_bind(struct usb_configuration *c, struct usb_function *f)
{/* (1) 从 gadget 中分配 2 个 bulk endpoint *//* allocate endpoints */loop->in_ep &＃61; usb_ep_autoconfig(cdev->gadget, &fs_loop_source_desc);loop->out_ep &＃61; usb_ep_autoconfig(cdev->gadget, &fs_loop_sink_desc);
}loopback_set_alt() → enable_loopback() → alloc_requests():static int alloc_requests(struct usb_composite_dev *cdev,struct f_loopback *loop)
{for (i &＃61; 0; i qlen && result &＃61;&＃61; 0; i&＃43;&＃43;) {result &＃61; -ENOMEM;in_req &＃61; usb_ep_alloc_request(loop->in_ep, GFP_ATOMIC);if (!in_req)goto fail;out_req &＃61; lb_alloc_ep_req(loop->out_ep, loop->buflen);if (!out_req)goto fail_in;in_req->complete &＃61; loopback_complete;out_req->complete &＃61; loopback_complete;in_req->buf &＃61; out_req->buf;/* length will be set in complete routine */in_req->context &＃61; out_req;out_req->context &＃61; in_req;/* (2) 先启动 OUT endpoint */result &＃61; usb_ep_queue(loop->out_ep, out_req, GFP_ATOMIC);if (result) {ERROR(cdev, "%s queue req --> %d\n",loop->out_ep->name, result);goto fail_out;}}}static void loopback_complete(struct usb_ep *ep, struct usb_request *req)
{struct f_loopback *loop &＃61; ep->driver_data;struct usb_composite_dev *cdev &＃61; loop->function.config->cdev;int status &＃61; req->status;switch (status) {case 0: /* normal completion? */if (ep &＃61;&＃61; loop->out_ep) {/** We received some data from the host so let&＃39;s* queue it so host can read the from our in ep*/struct usb_request *in_req &＃61; req->context;in_req->zero &＃61; (req->actual length);in_req->length &＃61; req->actual;ep &＃61; loop->in_ep;req &＃61; in_req;} else {/** We have just looped back a bunch of data* to host. Now let&＃39;s wait for some more data.*/req &＃61; req->context;ep &＃61; loop->out_ep;}/* (3) 环回的关键&＃xff1a;OUT endpoint 接收到的数据 转发到 IN endpointIN endpoint 数据发送完成后 req 重新挂载到 OUT endpoint*//* queue the buffer back to host or for next bunch of data */status &＃61; usb_ep_queue(ep, req, GFP_ATOMIC);}


也支持一些参数调整&＃xff1a;

# ls functions/Loopback.0/
bulk_buflen qlen


3. Host (usbtest.ko)

在 Host 侧的 usbtest.ko 它就是一个标准的 usb interface driver。它根据 Vendor ID &＃61; 0x0525、Product ID &＃61; 0xa4a0 适配上一节 Composite Device 中的 SourceSink Interface 或者 Loopback Interface。

static const struct usb_device_id id_table[] &＃61; {/* "Gadget Zero" firmware runs under Linux */{ USB_DEVICE(0x0525, 0xa4a0),.driver_info &＃61; (unsigned long) &gz_info,},}
MODULE_DEVICE_TABLE(usb, id_table);static struct usb_driver usbtest_driver &＃61; {.name &＃61; "usbtest",.id_table &＃61; id_table,.probe &＃61; usbtest_probe,.unlocked_ioctl &＃61; usbtest_ioctl,.disconnect &＃61; usbtest_disconnect,.suspend &＃61; usbtest_suspend,.resume &＃61; usbtest_resume,
};


3.1 testcase

其在 SourceSink Interface 提供的 4 个测试 endpoint、或者 Loopback Interface 提供的 2 个测试 endpoint &＃43; Composite Device 本身的 ep0 control endpoint 基础之上&＃xff0c;提供了30个 testcase&＃xff1a;

drivers\usb\misc\usbtest.c: usbtest_do_ioctl()


3.2 ioctl

usbtest.ko 以 ioctl 的形式向用户态提供对 testcase 的调用&＃xff1a;

usbdev_file_operations → usbdev_ioctl() → usbdev_do_ioctl() → proc_ioctl_default() → proc_ioctl()&＃xff1a;static int proc_ioctl(struct usb_dev_state *ps, struct usbdevfs_ioctl *ctl)
{/* (1) 找到对应的 usb interface device */else if (!(intf &＃61; usb_ifnum_to_if(ps->dev, ctl->ifno)))retval &＃61; -EINVAL;/* talk directly to the interface&＃39;s driver */default:if (intf->dev.driver)/* (2) 找到 usb interface device 对应的 driver */driver &＃61; to_usb_driver(intf->dev.driver);if (driver &＃61;&＃61; NULL || driver->unlocked_ioctl &＃61;&＃61; NULL) {retval &＃61; -ENOTTY;} else {/* (3) 调用 driver 的 ioctl 函数 */retval &＃61; driver->unlocked_ioctl(intf, ctl->ioctl_code, buf);if (retval &＃61;&＃61; -ENOIOCTLCMD)retval &＃61; -ENOTTY;}}↓usbtest_ioctl() → usbtest_do_ioctl()


4. App (testusb)

因为通过 ioctl 可以调用 usbtest.ko 的 testcase&＃xff0c;所以只要一个用户态的程序通过打开 /proc/bus/usb/devices/xxxx 对应 gadget zero 的 usb interface device 的文件节点&＃xff0c;就可以很方便的调用测试了。

在 USB Testing on Linux 有一个现成的工程&＃xff0c;提供了 testusb.c 和 test.sh&＃xff0c;但是因为适配的内核比较老&＃xff0c;所以需要对 testusb.c 进行一些修改&＃xff1a;

- if ((c &＃61; open ("/proc/bus/usb/devices", O_RDONLY)) <0) {
&＃43; if ((c &＃61; open ("/sys/kernel/debug/usb/devices", O_RDONLY)) <0) {fputs ("usbfs files are missing\n", stderr);return -1;}/* collect and list the test devices */
- if (ftw ("/proc/bus/usb", find_testdev, 3) !&＃61; 0) {
&＃43; if (ftw ("/dev/bus/usb", find_testdev, 3) !&＃61; 0) {fputs ("ftw failed; is usbfs missing?\n", stderr);return -1;}


简单编译&＃xff1a;

gcc -Wall -g -lpthread -o testusb testusb.c


就可以启动测试了&＃xff1a;

$ sudo ./testusb -a
unknown speed /dev/bus/usb/001/002
/dev/bus/usb/001/002 test 0, 0.000011 secs
/dev/bus/usb/001/002 test 1, 1.625031 secs
/dev/bus/usb/001/002 test 2 --> 110 (Connection timed out)
/dev/bus/usb/001/002 test 3, 1.639717 secs
/dev/bus/usb/001/002 test 4 --> 110 (Connection timed out)
/dev/bus/usb/001/002 test 5, 1.915198 secs
/dev/bus/usb/001/002 test 6 --> 110 (Connection timed out)
/dev/bus/usb/001/002 test 7, 1.928419 secs
/dev/bus/usb/001/002 test 8 --> 110 (Connection timed out)
/dev/bus/usb/001/002 test 9, 13.835084 secssudo ./testusb -asudo ./testusb -a -t1 -c1 -s512 -g32 -v32sudo ./testusb -a -t29 -c1 -s512 -g32 -v32// test 10 需要特别注意&＃xff0c;容易挂死 host
sudo ./testusb -a -t10 -c1 -s512 -g5 -v32
// test 28 需要特别注意&＃xff0c;容易挂死 host
sudo ./testusb -a -t28 -c1 -s512 -g32 -v32


参考资料

1.USB Testing on Linux
2.Linux USB测试
3.linux usb_gadget&＃xff1a;设备控制器驱动测试
4.Linux-USB Gadget : Part 5: 测试 PXA UDC 驱动
5.Linux-USB Gadget : Part 4: 最简单的 gadget驱动&＃xff1a;g_zero
6.Linux USB tests using Gadget Zero driver
7.USB/Linux USB Layers/Configfs Composite Gadget/Usage eq. to g zero.ko
8.usb/gadget: the start of the configfs interface