2. 加载失败常见分类：枚举失败、电源问题、描述符错误

驱动加载失败，说白了就是系统不认你的设备。我调试过的案例里，90% 的问题都逃不出这三个坑：枚举没走完、电源没给够、描述符写得不对。咱们一个一个拆。

2.1 枚举失败

枚举是 USB 设备第一次被主机发现时的那套对话。设备插上去，主机发复位，设备返回描述符，然后分配地址……任何一个环节卡住，驱动就加载不起来。

常见枚举失败现象	典型错误码	可能原因
设备插入后无任何反应	USB-ERROR -110 (ETIMEDOUT)	D+ / D- 上拉电阻缺失或电平异常
收到复位但无后续描述符请求	USB-ERROR -71 (EPROTO)	芯片晶振未起振，时钟不对
设备描述符返回后主机拒绝	USB-ERROR -32 (EPIPE)	bMaxPacketSize0 与实际端点大小不匹配
地址分配成功后立刻断开	USB-ERROR -108 (ESHUTDOWN)	电源瞬间跌落，VBUS 低于 4.4V

我个人习惯，遇到枚举失败先看 dmesg 里有没有 reset failed 或者 handshake timeout。如果有，大概率是硬件层面的问题——上拉电阻没焊好，或者 PCB 走线太长导致信号反射。我在一个量产项目上碰到过：明明参考设计一模一样，就是批量枚举不稳定。最后定位到是 USB 连接器外壳的接地没处理好，静电打进去就把枚举过程冲断了。

2.2 电源问题

电源问题往往伪装成枚举失败。你查了很久协议，结果发现是 VBUS 电压没扛住。

• 瞬间压降：设备插入瞬间浪涌电流很大，如果母座或线缆内阻高，VBUS 会被拉到 4.0V 以下，USB 控制器直接复位。
• 过流保护：主机端的 PTC 或电子开关限流了，设备刚上电就被断开。
• 电容配置不当：OTG 设备作为主机时，VBUS 需要提供 5V / 500mA；如果板子上大电容太少，瞬间供电能力不足。

我曾经调试过一个便携硬盘盒，在 A 口上正常，插到 OTG 手机就不认。抓包发现设备只有第一次复位成功，第二次复位就超时。拆开一看，板子的 VBUS 走线细得像头发丝，线阻 0.3Ω，算下来压降 0.3V，再加上手机 OTG 口本身输出弱，已经降到 4.2V 了。换粗线加电容后问题解决。

2.3 描述符错误

描述符就是 USB 设备的身份证。主机读描述符，决定加载哪个驱动。我见过最离谱的是一个设备把 bDeviceClass 填成了 0xFF（厂商自定义），但实际它是个 HID 键盘——结果 Windows 直接弹“未知设备”。

描述符错误类型	后果	典型案例
bLength 或 bDescriptorType 错误	主机解析错位，后续描述符全部读乱	bLength ≠ 18 的设备描述符导致 stall
bMaxPacketSize0 与实际不符	控制传输的大小不匹配，通信卡死	写了 64 但实际只支持 8，第一次控制读就超时
配置描述符总长计算错误	主机认为描述符不完整，放弃加载	wTotalLength 少算了接口描述符的 9 字节
字符串描述符索引越界或语言 ID 不支持	跳过字符串，设备名显示为空	索引 0x04 指向不存在的位置

你想想看，为什么有些设备在 Linux 上能认，在 Windows 上就不行？原因往往是 Windows 对描述符的校验更严格。比如 bcdUSB 字段，如果你写 0x0200 但实际只实现了 USB 1.1，Windows 可能会在高速握手时强制复位——这就是个典型的“描述符与硬件能力不一致”的坑。

举个代码例子，一个常见的错误：配置描述符总长算错。

// 错误示范：只算了配置描述符自身长度
struct usb_config_descriptor config = {
    .bLength = USB_DT_CONFIG_SIZE,          // 9
    .wTotalLength = USB_DT_CONFIG_SIZE,      // ❌ 这里应该是所有子描述符总和
};
// 实际应该：
.wTotalLength = USB_DT_CONFIG_SIZE + 
                sizeof(struct usb_interface_descriptor) +
                sizeof(struct usb_endpoint_descriptor) * 2;

这种错误在代码 review 时很容易漏掉，因为编译不会报错。我建议在固件里加个断言，运行时检查 wTotalLength 是否等于所有描述符占用的字节数。

三种分类的关系

这三种问题经常交织在一起。比如电源问题导致复位失败，然后表现为枚举超时；枚举超时又进一步让主机认为描述符读取失败。所以调试时别死盯一个方向，得按流程排查。

上面这张图把三种分类以及它们的常见子原因画清楚了。你可以把它贴在调试台前，每次遇到加载失败，先在图上定位问题属于哪个区域，再深入查具体原因。