HID 与 CDC 设备的 USB 描述符调试实战

HID 和 CDC 设备之所以流行，是因为它们让固件团队不用为每个主机写一套自定义驱动就能交付可用的 USB 接口。这种便利的前提是：描述符必须精确。当一个 HID 键盘、传感器、串口桥、组合设备出问题的时候，真正的根因往往在描述符里就能看到——比它在应用层报错早得多。

描述符调试听起来不性感，但它是最快的 USB 支持工单终结方式之一。

HID：Report Descriptor 才是契约

对 HID 设备来说，光有端点信息是不够的。主机还需要 HID Report Descriptor。这个描述符定义了 Report ID、Usage、大小、数量、逻辑范围，以及字节该如何被解析。

常见的 HID 错误包括：

• Report Length 跟实际 Interrupt Payload 对不上
• Report ID 在固件里用了，但没在描述符里一致声明
• Logical Min / Max 跟实际数据表示不一致
• Usage Page 或 Usage 跟主机预期不符
• Endpoint Interval 跟设备实际行为不匹配
• Boot Protocol 假设和 Report Protocol 行为冲突

主机报错可能很模糊。一份能把描述符字节和 Interrupt 传输都摆出来的抓包，会让这种不匹配变得一目了然。

CDC：接口布局才是关键

CDC ACM 设备通常暴露一个 Communication Interface 和一个 Data Interface。主机期望看到一组自洽的描述符和类特定请求。少一个 Functional Descriptor、Interface Association 不对、端点不匹配——都可能让虚拟串口根本不出现。

要看的证据：

• Interface Class / Subclass
• CDC Header / ACM / Union / Call Management Descriptor
• Notification Endpoint
• Bulk IN 和 Bulk OUT Endpoint
• SET_LINE_CODING
• SET_CONTROL_LINE_STATE
• 配置完成后的数据传输

如果串口出来了但数据不走，问题在端点行为或应用协议；如果串口根本出不来，先看描述符和类请求。

组合设备需要更严格的纪律

组合设备可以把 HID、CDC、大容量存储、厂商接口等塞在一起。这很灵活，但也把失败模式成倍放大了。一个接口里的描述符错，可能会牵连整台设备的绑定。

组合设备调试要查：

• Configuration 的 wTotalLength
• Interface 编号
• Interface Association Descriptor
• 端点唯一性
• 类特定描述符的放置位置
• 每个接口的主机请求

不要假设"固件发了对的字节"，除非抓包能证明主机看到了对的结构。

原始字节和类解读缺一不可

原始字节是真相，类解读让它变得可用。一款好的 USB 诊断工具应该两者都展示。工程师在出问题的时候要看到准确的描述符字节，平时又需要解析后的字段，免去每次都数偏移的麻烦。

最佳工作流：

1. 看解析后的描述符树
2. 跳到可疑字段的原始字节
3. 对照主机请求和固件响应
4. 检查配置完成后的端点传输
5. 把会话存下来便于复现或交接

这条工作流让诊断始终贴着证据走。

Bus Scope 在这个场景里做什么

Bus Scope 面向固件团队、硬件实验室、设备厂商，目标是让"USB 流量为什么会失败"这件事有一个可复现的答案。它把 Device Explorer 上下文、包详情、原始字节、描述符、类观察、过滤、.bscope 会话存档放在同一个工作台里。

对 HID 和 CDC 场景，Bus Scope 能帮回答：

• 枚举是否走完了？
• 描述符是不是和预期的类匹配？
• 主机有没有按预期发类请求？
• 端点传输有没有符合 Report 或 Line Coding 的预期？
• 这个问题是固件、主机驱动还是应用协议层？

这就是"驱动失败"和"到底哪条 USB 契约被破坏了"之间的差距。