Wireshark USB 抓包在嵌入式调试中的应用：从 USB 描述符到批量传输的协议分析方法

一、USB 调试的"黑盒困境"：当串口日志不再够用

嵌入式开发中，USB 外设调试长期依赖两种手段：设备端串口打印日志，或主机端的 dmesg 内核日志。这两种方式都有一个共同的盲区——它们看不到总线上真实发生的电气信号和协议交互。当 USB 摄像头在特定的 UVC 控制请求后停止输出数据、当自定义 HID 设备在 Windows 上枚举成功但在 Linux 上失败、当批量传输在高负载下间歇性丢包——仅靠应用层日志几乎无法定位根因。

Wireshark 的 USB 抓包能力（通过 usbmon 内核模块 + Wireshark 或 tcpdump -i usbmonX）填补了这一分析盲区。它能够捕获 USB 总线上的每一个 URB（USB Request Block），包括控制传输的 Setup 阶段、数据阶段和状态阶段。这对于调试自定义 USB 设备的描述符协商、端点配置和传输错误排查至关重要。

二、USB 协议分层与 URB 抓包原理

USB 通信从物理层到应用层经历了多层封装。Wireshark 的 usbmon 抓包位于 USB 核心驱动层，能够捕获完整的事务级交互：

usbmon 的工作原理：usbmon 在 USB 核心层（drivers/usb/mon/）注册回调，每个 URB 在提交（USB_URB_SUBMIT）和完成（USB_URB_COMPLETE）时被记录。它捕获的 URB 结构包含：

• urb->dev->busnum 和 urb->dev->devnum：总线号和设备地址
• urb->pipe：端点方向、类型（Control/Bulk/Interrupt/Isochronous）和端点号
• urb->transfer_buffer 指针（文本模式下仅显示前 32 字节）
• urb->actual_length 和 urb->status：传输结果

抓包命令：

# 加载 usbmon 模块
sudo modprobe usbmon

# 列出所有 USB 总线
ls /sys/kernel/debug/usb/usbmon/

# 使用 tcpdump 抓取 bus 1 的所有 URB
sudo tcpdump -i usbmon1 -w usb_capture.pcapng

# 使用 Wireshark 直接捕获
sudo wireshark -i usbmon1 -k

三、USB 描述符协商与批量传输故障的实战分析

3.1 设备枚举阶段：描述符请求的逐包解析

以调试一颗自定义 USB 摄像头的枚举过程为例。设备插入后，主机依次发起以下控制传输：

/*
 * usb_descriptor_monitor.c — USB 设备描述符校验脚本
 * 通过解析 Wireshark 导出的 JSON 格式 USB 抓包，验证描述符合法性
 * 
 * 编译: gcc -O2 usb_descriptor_monitor.c -ljansson -o usb_descriptor_monitor
 * 使用: tshark -r capture.pcapng -T json > usb.json
 *       ./usb_descriptor_monitor usb.json
 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdint.h>
#include <jansson.h>

/* USB 标准请求类型 (bmRequestType) */
#define USB_DIR_IN          0x80  /* 设备到主机 */
#define USB_TYPE_STANDARD   0x00  /* 标准请求 */
#define USB_RECIP_DEVICE    0x00  /* 接收者为设备 */

/* 标准请求码 (bRequest) */
#define USB_REQ_GET_DESCRIPTOR      0x06
#define USB_DT_DEVICE               0x01
#define USB_DT_CONFIG               0x02
#define USB_DT_STRING               0x03

/* 设备描述符结构 */
typedef struct {
    uint8_t  bLength;
    uint8_t  bDescriptorType;
    uint16_t bcdUSB;
    uint8_t  bDeviceClass;
    uint8_t  bDeviceSubClass;
    uint8_t  bDeviceProtocol;
    uint8_t  bMaxPacketSize0;
    uint16_t idVendor;
    uint16_t idProduct;
    uint16_t bcdDevice;
    uint8_t  iManufacturer;
    uint8_t  iProduct;
    uint8_t  iSerialNumber;
    uint8_t  bNumConfigurations;
} __attribute__((packed)) usb_device_desc_t;

/*
 * 从 hex 字符串解析设备描述符
 * 输入: "1201100200000040..." (Wireshark 中的 usb.data 字段)
 */
static int parse_device_descriptor(const char *hex_str, usb_device_desc_t *desc)
{
    if (!hex_str || !desc) return -1;

    size_t len = strlen(hex_str);
    if (len < 36) { /* 设备描述符 = 18 bytes = 36 hex 字符 */
        fprintf(stderr, "[ERROR] 描述符数据过短: %zu hex chars\n", len);
        return -1;
    }

    unsigned char raw[18];
    /* hex 字符串 → 二进制数组 */
    for (int i = 0; i < 18; i++) {
        unsigned int byte_val;
        if (sscanf(hex_str + i * 2, "%2x", &byte_val) != 1) {
            fprintf(stderr, "[ERROR] hex 解析失败: 位置 %d\n", i * 2);
            return -1;
        }
        raw[i] = (unsigned char)byte_val;
    }

    memcpy(desc, raw, sizeof(usb_device_desc_t));

    /* 字段合法性校验 */
    if (desc->bLength != 18) {
        fprintf(stderr, "[WARN] bLength = %d (期望 18)\n", desc->bLength);
    }
    if (desc->bDescriptorType != USB_DT_DEVICE) {
        fprintf(stderr, "[ERROR] bDescriptorType = 0x%02x (期望 0x01)\n",
                desc->bDescriptorType);
        return -1;
    }

    /* bMaxPacketSize0 必须为 8, 16, 32 或 64 */
    if (desc->bMaxPacketSize0 != 8 && desc->bMaxPacketSize0 != 16 &&
        desc->bMaxPacketSize0 != 32 && desc->bMaxPacketSize0 != 64) {
        fprintf(stderr, "[WARN] bMaxPacketSize0 = %d (非标准值)\n",
                desc->bMaxPacketSize0);
    }

    return 0;
}

/*
 * 验证描述符响应与请求的匹配关系
 * 典型枚举序列：
 *   1. GET_DESCRIPTOR(DEVICE, 0) → 18 bytes 设备描述符
 *   2. SET_ADDRESS(N)           → 0 bytes
 *   3. GET_DESCRIPTOR(CONFIG,0) → 9 bytes 配置描述符 (仅头部)
 *   4. GET_DESCRIPTOR(CONFIG,0) → 完整配置描述符集合
 *   5. GET_DESCRIPTOR(STRING,iManufacturer) → 字符串描述符
 */
static void verify_enumeration_sequence(json_t *root)
{
    /* 枚举阶段的关键检查项 */
    const char *checks[] = {
        "GET_DESCRIPTOR Request DEVICE",
        "SET_ADDRESS Request",
        "GET_DESCRIPTOR Request CONFIGURATION",
    };

    json_t *packets = json_object_get(root, "packets");
    if (!json_is_array(packets)) {
        fprintf(stderr, "[ERROR] JSON 格式异常：缺少 packets 数组\n");
        return;
    }

    size_t pkt_count = json_array_size(packets);
    printf("[INFO] 共解析 %zu 个 URB 事件\n", pkt_count);

    int desc_device_found = 0;
    int set_address_found = 0;

    for (size_t i = 0; i < pkt_count; i++) {
        json_t *pkt = json_array_get(packets, i);
        json_t *layers = json_object_get(pkt, "_source");
        if (!layers) continue;

        json_t *usb_layer = json_object_get(layers, "layers");
        if (!usb_layer) continue;

        /* 检查 USB URB 类型 */
        json_t *usb_urb_type = json_object_get(usb_layer, "usb.urb_type");
        if (!usb_urb_type) continue;

        const char *urb_type = json_string_value(usb_urb_type);
        if (strstr(urb_type, "URB_SUBMIT")) {
            /* 解析请求类型 */
            json_t *bmrt = json_object_get(usb_layer, "usb.bmRequestType");
            json_t *breq = json_object_get(usb_layer, "usb.bRequest");
            if (bmrt && breq) {
                printf("[URB %zu] bmRequestType=%s bRequest=%s\n",
                       i, json_string_value(bmrt), json_string_value(breq));
            }
        }
    }
}

int main(int argc, char **argv)
{
    if (argc < 2) {
        fprintf(stderr, "用法: %s <usb_capture.json>\n", argv[0]);
        return EXIT_FAILURE;
    }

    json_error_t error;
    json_t *root = json_load_file(argv[1], 0, &error);
    if (!root) {
        fprintf(stderr, "[ERROR] JSON 解析失败: %s (行 %d)\n",
                error.text, error.line);
        return EXIT_FAILURE;
    }

    verify_enumeration_sequence(root);

    json_decref(root);
    return EXIT_SUCCESS;
}

3.2 批量传输丢包分析

USB 批量传输的丢包通常表现为 URB 的 status 字段非零。典型异常值包括：

通过 Wireshark 的 usb.transfer_type == 0x03 过滤出所有批量传输 URB，再按 usb.status 分组统计：

# 使用 tshark 统计各状态码的出现频率
tshark -r capture.pcapng \
  -Y "usb.transfer_type == 0x03" \
  -T fields -e usb.status | sort | uniq -c | sort -rn

进一步分析 -EPROTO 发生的时间窗口：如果协议错误集中在某几个连续的 URB，说明可能是设备端 FIFO 溢出或主机控制器驱动问题；如果离散分布，更可能是信号完整性问题（如 PCB 走线阻抗不匹配）。

四、USB 抓包方案的适用边界与限制

数据带宽限制：usbmon 在文本模式下对每个 URB 的数据截断为 32 字节（可通过 usbmon 模块参数调整但会增加内核内存压力）。对于 Isochronous 传输（如 UVC 视频流，单帧可达数百 KB），usbmon 无法完整捕获 payload。这类场景需使用硬件 USB 协议分析仪（如 Total Phase Beagle）。

性能影响：usbmon 在每个 URB 完成时触发回调，在高带宽批量传输（如 USB 3.0 SSD，300MB/s+）中，抓包本身可能引入 5%~15% 的吞吐下降和额外延迟。生产环境性能测试时应关闭抓包。

Linux 平台依赖：usbmon 是 Linux 内核模块，Windows 和 macOS 上需使用 USBPcap（Win）或 Wireshark XHC20（macOS）等替代工具。跨平台调试时需注意不同抓包工具的字段命名差异。

禁用场景：

五、总结

Wireshark + usbmon 组合是嵌入式 USB 调试链路中成本最低、信息密度最高的分析工具。关键运用方式：

1. 枚举阶段调试：通过过滤 usb.bmRequestType 和 usb.bRequest，可完整还原主机对设备的描述符请求序列，快速定位描述符内容不合法、STALL 响应等枚举失败原因。

2. 传输错误统计：通过 usb.status 字段的分组统计和时序分析，可区分驱动取消、协议错误、超时等不同失败模式，进而定位问题在主机驱动侧还是设备固件侧。

3. 描述符校验自动化：将 Wireshark 导出为 JSON 格式后，可编写自动化脚本批量校验描述符合法性，集成到 CI/CD 流程。

4. 工具限制认知：usbmon 受限于 32 字节 payload 截断和 ≈10% 的性能开销，不适用于高速 Isochronous 传输分析和生产环境监控。