4. 端点配置数据结构：struct usb_host_endpoint 与 struct usb_endpoint_descriptor 解析

在 USB 驱动开发中，端点是主机与设备之间数据传输的逻辑通道。Linux 内核使用 struct usb_host_endpoint 和 struct usb_endpoint_descriptor 两个核心数据结构来描述和管理端点配置。理解这两个结构体的字段含义、层级关系以及它们在 URB 传输中的作用，是调试端点配置错误和 URB 传输失败的基础。

4.1 数据结构层级关系

struct usb_host_endpoint 是内核为每个端点维护的“宿主”结构，它包裹了从设备固件中解析出的标准描述符 struct usb_endpoint_descriptor，并附加了驱动运行时所需的元数据（如 URB 队列、定时器、流 ID 表等）。两者的关系如下图所示：

4.2 struct usb_endpoint_descriptor 字段详解

该结构体定义在 include/uapi/linux/usb/ch9.h 中，是 USB 规范中标准端点描述符的 C 语言映射。每个字段对应 USB 2.0/3.0 规范中端点描述符的字节偏移。

4.3 struct usb_host_endpoint 核心字段

该结构体定义在 include/linux/usb.h 中，是驱动与 USB 核心层交互的主要对象。驱动通过 struct usb_device 的 ep_in[] 和 ep_out[] 数组访问已配置的端点。

4.4 端点地址与方向解码

bEndpointAddress 字段是调试中最常解析的字段。其位布局如下：

• Bit 7：方向位。0 = OUT（主机到设备），1 = IN（设备到主机）。
• Bits 6-4：保留，必须为 0。
• Bits 3-0：端点号，范围 0~15。端点 0 是默认控制端点，不在此描述。

4.5 传输类型与 bmAttributes 解码

bmAttributes 的低 2 位决定端点传输类型，驱动必须使用对应的 URB 类型提交：

4.6 驱动中获取端点描述符的典型代码

以下代码片段展示了在 USB 驱动探测函数中如何遍历接口的端点并读取配置信息：

static int my_driver_probe(struct usb_interface *intf,
                           const struct usb_device_id *id)
{
    struct usb_device *udev = interface_to_usbdev(intf);
    struct usb_host_interface *iface_desc = intf->cur_altsetting;
    struct usb_endpoint_descriptor *ep_desc;
    int i;

    for (i = 0; i < iface_desc->desc.bNumEndpoints; i++) {
        ep_desc = &iface_desc->endpoint[i].desc;

        /* 检查端点方向 */
        if (usb_endpoint_dir_in(ep_desc)) {
            dev_info(&intf->dev, "端点 %02x: IN\n",
                     ep_desc->bEndpointAddress);
        } else {
            dev_info(&intf->dev, "端点 %02x: OUT\n",
                     ep_desc->bEndpointAddress);
        }

        /* 检查传输类型 */
        if (usb_endpoint_xfer_bulk(ep_desc)) {
            dev_info(&intf->dev, "  类型: 批量, 最大包长: %d\n",
                     __le16_to_cpu(ep_desc->wMaxPacketSize));
        } else if (usb_endpoint_xfer_int(ep_desc)) {
            dev_info(&intf->dev, "  类型: 中断, 间隔: %d ms\n",
                     ep_desc->bInterval);
        }

        /* 保存端点用于后续 URB 提交 */
        if (usb_endpoint_dir_in(ep_desc) &&
            usb_endpoint_xfer_bulk(ep_desc)) {
            udev->ep_in[usb_endpoint_num(ep_desc)] =
                &iface_desc->endpoint[i];
        }
    }
    return 0;
}

4.7 常见端点配置错误与调试方法

• 端点号冲突： 同一接口下两个端点使用相同端点号但方向不同是合法的（如批量 IN 和批量 OUT 共用端点号 1），但相同方向相同端点号重复定义会导致内核警告。
• wMaxPacketSize 超出限制： USB 2.0 批量端点最大包长 512 字节，高速中断端点最大 1024 字节，等时端点最大 1024 字节。超出限制时 URB 提交会返回 -ENOMEM。
• bInterval 值异常： 低速/全速中断端点 bInterval 单位为毫秒，高速/超速中断端点单位为 125µs 的倍数。错误设置会导致中断 URB 无法按时完成。
• 描述符长度不匹配： USB 3.0 端点描述符长度为 9 字节（含 bRefresh 和 bSynchAddress），USB 2.0 为 7 字节。驱动应使用 ep_desc->bLength 判断版本。

4.8 小结

struct usb_host_endpoint 和 struct usb_endpoint_descriptor 是 USB 驱动开发中必须掌握的基础数据结构。驱动通过 ep->desc 访问描述符字段，通过 ep->urb_list 管理 URB 队列。调试端点配置错误时，应优先检查 bEndpointAddress 的方向位、bmAttributes 的传输类型以及 wMaxPacketSize 是否与 URB 管道匹配。使用内核提供的辅助宏（如 usb_endpoint_dir_in()、usb_endpoint_xfer_bulk()）可以避免手动位操作错误。