libusb在macOS系统上的ZLP传输问题分析与修复

问题背景

在USB协议中，零长度包(Zero Length Packet, ZLP)是一个重要的控制机制，用于指示数据传输的结束。当使用libusb库进行异步USB传输时，可以通过设置LIBUSB_TRANSFER_ADD_ZERO_PACKET标志来请求在适当的时候自动发送ZLP。

然而，在macOS系统(Darwin)上，开发者发现这个功能存在异常行为。具体表现为：对于USB 3.0设备，当maxPacketSize为1024字节时，libusb会在数据包大小为5120字节(1024×5)的倍数时发送ZLP，而不是预期的1024字节倍数。这导致接收端设备无法正确识别传输结束，从而造成批量传输挂起的问题。

技术分析

经过深入调查，发现问题根源在于macOS系统中获取USB管道属性的方式。libusb在darwin_usb.c文件中使用了GetPipePropertiesV3函数来获取管道属性，但这个函数返回的wMaxPacketSize值已经包含了burst传输和multiplier的乘积因子。

在USB 3.0规范中：

• 基础最大包大小(wMaxPacketSize)是端点描述符中定义的值
• bMaxBurst表示设备支持的最大突发传输次数
• bMult是等时传输的乘数因子

GetPipePropertiesV3返回的是"完整"的最大包大小，已经包含了(bMaxBurst+1)的乘积因子。而libusb错误地将这个已经乘积后的值直接用作基础包大小，导致ZLP计算逻辑出现偏差。

解决方案

开发者提出了三种可能的修复方案：

1. 推荐方案：在获取管道属性后，再调用GetEndpointPropertiesV3函数。这个函数明确说明会返回端点描述符中的基础wMaxPacketSize值，不包含任何乘积因子。

2. 修正计算：继续使用GetPipePropertiesV3，但需要手动除以(bMaxBurst+1)和可能的(bMult+1)因子来还原基础包大小。这种方法需要对USB协议有深入理解，特别是处理等时传输时更复杂。

3. 使用描述符值：直接从端点描述符中获取maxPacketSize值。这种方法简单但可能不够灵活。

最终实现采用了第一种方案，因为它最直接可靠，且符合USB规范的定义。通过获取端点的基础属性值，确保ZLP计算基于正确的包大小。

技术影响

这个修复对于依赖ZLP机制进行传输控制的USB设备尤为重要，特别是那些需要精确控制数据传输边界的应用场景。修复后，libusb在macOS系统上能够正确地在数据包大小达到maxPacketSize倍数时发送ZLP，确保数据传输的完整性。

开发者建议

对于需要在macOS系统上使用libusb进行USB开发的工程师，建议：

1. 更新到包含此修复的libusb版本
2. 在开发过程中充分测试ZLP相关功能
3. 了解不同操作系统下USB实现的差异
4. 对于关键数据传输，考虑实现额外的传输结束确认机制

这个问题的解决展示了开源社区协作的优势，通过开发者的报告和分析，最终找到了问题的根源并提供了可靠的解决方案。