4. 设备描述符（Device Descriptor）：结构定义与字段填充规则

设备描述符是 USB 枚举过程中主机获取的第一个描述符，它定义了设备的整体属性，包括协议版本、厂商/产品标识、设备分类以及配置数量。主机通过默认控制端点（端点 0）发送标准请求 GET_DESCRIPTOR（bRequest = 0x06，wValue = 0x0100）来获取该描述符。设备描述符的结构由 USB 规范严格定义，任何字段填充错误都会导致枚举失败。

4.1 结构定义与字节布局

设备描述符的长度固定为 18 字节，所有 USB 设备必须支持。其数据结构在 USB 规范 2.0 第 9.6.1 节中定义，C 语言结构体如下：

typedef struct {
    uint8_t  bLength;            // 描述符长度（固定 0x12 = 18）
    uint8_t  bDescriptorType;    // 描述符类型（0x01 = 设备描述符）
    uint16_t bcdUSB;             // USB 规范版本号（BCD 编码）
    uint8_t  bDeviceClass;       // 类代码
    uint8_t  bDeviceSubClass;    // 子类代码
    uint8_t  bDeviceProtocol;    // 协议代码
    uint8_t  bMaxPacketSize0;    // 端点 0 最大包长度
    uint16_t idVendor;           // 厂商 ID（USB-IF 分配）
    uint16_t idProduct;          // 产品 ID（厂商自定义）
    uint16_t bcdDevice;          // 设备版本号（BCD 编码）
    uint8_t  iManufacturer;      // 厂商字符串描述符索引
    uint8_t  iProduct;           // 产品字符串描述符索引
    uint8_t  iSerialNumber;      // 序列号字符串描述符索引
    uint8_t  bNumConfigurations; // 支持的配置描述符数量
} __attribute__((packed)) usb_device_descriptor_t;

4.2 字段含义与填充规则

下表详细列出每个字段的含义、取值范围及常见填充值：

4.3 设备描述符在枚举流程中的位置

主机在检测到设备连接并完成复位后，立即发送 GET_DESCRIPTOR 请求获取设备描述符。下图展示了设备描述符在枚举第一阶段的关键位置：

4.4 字段填充的常见陷阱与避坑指南

• bLength 错误： 必须为 0x12。如果填入 0x10 或 0x14，主机解析会偏移，导致后续所有字段读取错误。
• bcdUSB 版本不匹配： USB 2.0 设备填 0x0200，USB 1.1 设备填 0x0110。如果高速设备填 0x0110，主机可能以全速模式枚举，降低性能。
• bMaxPacketSize0 与速度不匹配： 高速设备必须为 64 字节（0x40），全速设备可选 8/16/32/64，低速设备固定 8。填入错误值会导致控制传输失败。
• idVendor 未注册： 使用 0x0000 或 0xFFFF 等保留值，主机可能拒绝加载驱动。必须使用 USB-IF 分配的合法 VID。
• 小端序错误： idVendor、idProduct、bcdUSB、bcdDevice 均为小端序。例如 VID=0x0483 在内存中应为 0x83, 0x04，而非 0x04, 0x83。
• 字符串索引冲突： iManufacturer、iProduct、iSerialNumber 必须指向有效的字符串描述符索引，或填 0 表示不存在。如果填 1 但未提供对应的字符串描述符，主机请求字符串时会超时。

4.5 设备描述符的典型填充示例

以下是一个符合 USB 2.0 规范的 HID 设备描述符填充示例：

const uint8_t device_descriptor[18] = {
    0x12,       // bLength: 18 字节
    0x01,       // bDescriptorType: 设备描述符
    0x00, 0x02, // bcdUSB: USB 2.0 (0x0200, 小端序)
    0x00,       // bDeviceClass: 在接口描述符中定义
    0x00,       // bDeviceSubClass: 0
    0x00,       // bDeviceProtocol: 0
    0x40,       // bMaxPacketSize0: 64 字节
    0x83, 0x04, // idVendor: 0x0483 (STMicroelectronics, 小端序)
    0x40, 0x57, // idProduct: 0x5740 (自定义, 小端序)
    0x00, 0x01, // bcdDevice: 1.00 (0x0100, 小端序)
    0x01,       // iManufacturer: 字符串索引 1
    0x02,       // iProduct: 字符串索引 2
    0x03,       // iSerialNumber: 字符串索引 3
    0x01        // bNumConfigurations: 1 个配置
};

4.6 设备描述符与枚举失败的关联分析

当设备描述符填充错误时，主机在枚举过程中会表现出不同的失败模式。下表总结了常见错误与对应的故障现象：

4.7 设备描述符字段间的依赖关系

设备描述符中的某些字段存在逻辑依赖关系，填充时必须保持一致性。下图展示了这些依赖关系：

4.8 调试建议：如何验证设备描述符

1. 使用 USB 分析仪： 抓取枚举阶段的控制传输数据，检查主机收到的 18 字节是否与预期一致。
2. 逻辑分析仪解码： 在 D+/D- 线路上捕获 USB 包，验证 SETUP 令牌、DATA0 数据包和 ACK 握手。
3. 固件打印调试： 在设备端添加调试输出，确认 GET_DESCRIPTOR 请求被正确响应，且返回的数据指针正确。
4. 对比参考实现： 使用已知正常的设备（如 USB 鼠标）抓取其设备描述符，与自己的填充值逐字节对比。