USB Device Qualifier 与 Other Speed Configuration 调试：High-Speed vs Full-Speed 描述符问题

同时支持 Full-Speed 和 High-Speed 运行的 USB 设备，必须描述自己在另一种速度下怎么工作。同一台产品在不同的端口、线材、Hub、主控制器上表现不一样的时候，用户搜 "USB Device Qualifier descriptor"、"Other Speed Configuration descriptor"、"high speed device enumerates as full speed"、"USB descriptor mismatch"、"device works on USB 2.0 but fails on hub"。

Bus Scope 在这个场景下有用，因为诊断要对比描述符请求、实际速度、端点 packet size、Configuration Descriptor 和主机在枚举期间的决定。

Device Qualifier 描述符是什么

Device Qualifier 描述符描述了一台 High-Speed 设备在另一种速度下会怎么工作。如果设备当前是 High-Speed，Qualifier 告诉主机 Full-Speed 行为；如果是 Full-Speed，它可以描述 High-Speed 能力。

重要字段：

• USB 版本
• Device Class
• Subclass
• Protocol
• 端点 0 的 Max Packet Size
• Configuration 数量

如果这个描述符缺失、畸形或前后不一致，枚举在某个主机上可能成功、另一个上失败。

Other Speed Configuration

Other Speed Configuration 描述符描述了相反速度下的 Configuration 细节。端点 packet size、轮询间隔、带宽假设都可能不一样。

常见失败模式：

• Full-Speed Configuration 声明的端点大小只在 High-Speed 下合理
• High-Speed Configuration 漏了某个接口
• Other-Speed 描述符数量和真实 Configuration 对不上
• 主机期望描述符时固件返回 STALL
• 主机收了设备但绑错驱动
• 走某个 Hub 能用，走另一个就不行

这些问题从应用日志里很难看到。

High-Speed 设备被枚举成 Full-Speed

一个高频支持案例就是 "USB High-Speed 设备被检测为 Full-Speed"。原因可能是线材质量、Hub 拓扑、信号完整性、固件 chirp 行为、电气设计、或者描述符问题。

包证据能把各层分开：

• High-Speed 协商有没有发生？
• 主机有没有要 Device Qualifier？
• 设备有没有回合法的描述符字节？
• 端点描述符是不是和选中的速度匹配？
• 主机有没有 Reset 并重试？
• 设备后来有没有以另一种速度重新枚举？

如果 trace 显示设备根本没到 High-Speed，修描述符可能不够。如果 trace 显示 High-Speed 枚举了但 other-speed 描述符非法，固件嫌疑更大。

跨速度的端点 packet size 不匹配

端点描述符在 Full-Speed 和 High-Speed Configuration 下可以不同。一个 Bulk 端点 Full-Speed 下可能是 64 字节，High-Speed 下可能是 512 字节。

失败症状：

• 只有在 High-Speed 端口下传输失败
• 只有通过老 Full-Speed Hub 时失败
• 固件 buffer 大小和一种速度对得上，描述符却声明了另一种
• 主机驱动发的传输比固件预期大
• 设备在意外的边界上回短包

这直接连到 wMaxPacketSize 调试。

组合设备

组合设备让 other-speed 描述符更脆弱。一台设备可能同时暴露 HID、CDC、厂商、大容量存储、固件升级接口。Other-speed 树必须保持一致。

Bug 包括：

• 在某个速度下漏了 Interface Association Descriptor
• 跨速度的 Interface 编号不一致
• 端点地址意外变化
• 一个接口有合法的 other-speed 描述符，另一个没有
• Windows 重新枚举之后绑了别的驱动

自定义固件的产品里，这是典型的复制粘贴失败。

STALL 可能是合法的，也可能可疑

对不支持所请求能力的设备，部分描述符请求合法 STALL 是正常的。但对支持 High-Speed 的设备来说，Device Qualifier 或 Other Speed Configuration 附近反复失败，就值得查。

报告要保留：

• 请求类型
• 描述符类型
• wValue
• wIndex
• wLength
• 返回的数据
• STALL 或超时状态

Bus Scope 应该让这些 Control Transfer 可读，而不是逼工程师手解原始字节。

排查清单

按这个流程：

1. 从物理插入开始抓
2. 记录实际协商的速度
3. 检查 Device Descriptor
4. 检查 Device Qualifier Descriptor
5. 检查 Other Speed Configuration Descriptor
6. 对比端点 packet size 在不同速度下的差异
7. 检查 Interface 编号和端点地址
8. 测直连端口、Hub、USB-C Dock 通路
9. 对比 Windows 和 Linux 的枚举行为
10. 保留描述符请求的失败和重试

最终诊断

USB Device Qualifier 和 Other Speed Configuration 的 bug 是描述符一致性问题。它解释了为什么一台设备在一个速度下能用、在另一个速度下挂，或者在 Hub 和 Dock 后面表现不同。

Bus Scope 帮你抓到精确的枚举证据：描述符请求、other-speed 字节、端点大小、STALL、Reset，以及驱动绑定的后果。