USB 端点 Max Packet Size 不匹配：wMaxPacketSize、短包、Bulk 传输、固件缓冲 bug
USB 端点 wMaxPacketSize 不匹配、短包、Bulk 传输 STALL、High-Speed 与 Full-Speed 差异、固件缓冲 bug 的排查。
USB 端点的 wMaxPacketSize 看起来只是描述符里一个小字段，但值错了就会破坏 Bulk 传输、Interrupt 报告、High-Speed 工作、固件缓冲、主机驱动假设。传输只在某些大小或速度下失败的时候，用户搜 "USB wMaxPacketSize mismatch"、"USB short packet problem"、"bulk transfer stops at 64 bytes"、"USB endpoint packet size high speed full speed"、"USB descriptor max packet size bug"。
Bus Scope 在这个场景下有用，因为故障只有在描述符和传输包放一起看的时候才显现。描述符可能声称一个 packet size，固件 / 主机代码 / 端点硬件却按另一个跑。
wMaxPacketSize 控制什么
每个端点描述符里都有 wMaxPacketSize。它告诉主机该端点的最大 packet payload。具体取值取决于速度和端点类型。
例子：
- Full-Speed Bulk 端点通常用 64 字节
- High-Speed Bulk 端点通常用 512 字节
- Interrupt 端点按速度和间隔变化
- Isochronous 端点用带宽相关的 packet size
固件如果按 64 字节配端点 buffer，但描述符里写 512 字节，主机就可能发设备根本处理不来的传输。
常见症状
端点 Max Packet Size 的 bug 表现成：
- 小消息 Bulk 成功，大消息失败
- Full-Speed 正常，High-Speed 失败
- 传到正好 64 字节就停了
- 主机永远在等一个短包
- 固件收到意外被切分的数据
- OUT 传输 STALL
- IN 传输返回截断的数据
- 驱动报超时，但其实有流量
- 组合设备一个接口能工作，另一个不行
准确的字节数往往是关键线索。
短包行为
USB Bulk 传输常用短包来标识一次传输的结束——当请求的长度大于实际数据的时候。如果设备返回的长度正好是 Max Packet Size 的整数倍，主机可能会继续等下去，除非协议单独定义长度，或者发一个 Zero Length Packet（ZLP）。
举例：
max packet size: 64
payload length: 128
packets: 64 + 64
end condition: ambiguous unless length is known or ZLP is sent
这就是为什么"USB short packet"和"USB zero length packet"是高频搜索词。一台设备可能通过简单的测试，但 payload 长度正好落在 packet 边界的时候就会卡住。
High-Speed vs Full-Speed 不匹配
有些设备 Full-Speed 正常、High-Speed 挂掉。原因包括：
- High-Speed 描述符写了 512 字节
- 固件 buffer 仍然是 64 字节
- High-Speed 下 DMA 对齐要求变了
- 端点 FIFO 太小
- 主机驱动按 High-Speed 包分片处理
- 两种速度模式下 Device Descriptor 不一样
Bus Scope 应该能帮你对比枚举速度、端点描述符值和实际传输分片。
描述符复制粘贴的错误
固件团队经常在不同接口或模式间复制端点描述符。这会留下隐蔽的 bug：
- Interrupt 端点声明了 Bulk 风格的 size
- OUT 端点的 size 跟 IN 不一致
- Alternate Setting 改了 size 但固件没重新配端点
- Full-Speed 和 High-Speed 的描述符树对不上
- Companion Descriptor 的吞吐对不上
正确的诊断视图要把端点地址、它的描述符和这条端点上的每笔传输绑在一起。
固件 buffer bug
即使描述符对了，固件处理数据的方式可能仍是错的：
- 假设一个 USB 包等于一条应用消息
- 不处理被切分的消息
- 把 ZLP 丢了
- 把短包当错误
- 收完第一个包就把 buffer 覆盖了
- 传输长度等于 Max Packet Size 时处理失败
- 最后一笔短包之后没 flush IN 端点
这些 bug 在厂商自定义设备和 Bootloader 里很常见，因为协议通常都是定制的。
主机驱动的假设
主机代码也可能是错的：
- 请求的 buffer 太小
- 假设一次 read 等于一条设备消息
- 忽略短包作为传输终止
- 不用协议长度框定，靠 timeout 收尾
- 命令发得比固件 buffer 还大
- 忘了 ZLP 行为
两边都是自定义的时候，包 trace 就是契约。
要收集的证据
诊断 Max Packet Size 的时候，收集这些：
- 设备速度
- 端点描述符
- 端点地址和方向
wMaxPacketSize- 主机请求的传输大小
- 实际观测到的包大小
- 短包 / ZLP 是否存在
- STALL、NAK、超时或 Reset 在传输之后
- Full-Speed 和 High-Speed 枚举之间的差异
- 固件日志（如有）
最有力的报告带上精确字节数。这些细节也容易被搜索引擎命中。
排查清单
按这个流程：
- 识别端点描述符
- 记录
wMaxPacketSize - 对比速度模式
- 发送低于、等于、高于 Max Packet Size 的 payload
- 测试正好是 Max Packet Size 整数倍的大小
- 看有没有短包或 ZLP
- 看最后一包之后主机是不是还在等
- 对比 IN 和 OUT 端点行为
- 检查 Alternate Setting 切换
- 保留失败的那段传输序列
最终诊断
USB 端点 Max Packet Size 的 bug 是描述符、传输、固件契约三个层面的问题。有用的证据是：声明的 wMaxPacketSize、实际的分片、短包行为、ZLP 处理、速度模式、端点特定失败。
Bus Scope 让工程师证明 bug 到底出在描述符、固件 buffer 处理、主机驱动假设，还是传输框定。