一、什么情况下需要使用libusb
根据对大量实际应用的分析，以下场景是libusb在Windows上的典型使用场景：
1. 自定义USB设备通信
当开发者设计了自己的USB设备（基于MCU、FPGA或ASIC），且该设备不属于标准USB设备类（如HID、Mass Storage、CDC等）时，需要一种通用的方式来与设备通信。libusb提供了这样的能力。
典型例子：通过libusb实现PC与FPGA开发板之间的USB通信。开发者可以使用libusb库开发上位机程序，与FPGA的USB接口进行数据收发测试。
2. 替代厂商私有驱动
许多硬件厂商提供的Windows驱动存在兼容性问题、性能问题或仅支持特定Windows版本。libusb提供了一种标准化的替代方案。
例如，sfd_tool提供了使用libusb驱动的版本，替代了展讯的SPRD原生驱动。这使用户可以在更广泛的Windows版本上使用该工具。
3. 跨平台应用开发
对于需要在Windows、Linux和macOS上运行的应用程序，使用libusb意味着只需维护一套USB通信代码。Fobos SDR项目就是典型代表，其代码在三个平台上都可以编译运行。
4. USB设备调试与逆向工程
IO Ninja的USB Endpoint插件展示了libusb在USB调试和逆向工程中的价值。开发者可以通过该插件直接发送和接收原始USB数据包，分析设备协议。
5. 教学与原型开发
在学术研究和产品原型开发阶段，libusb提供了一种快速验证USB通信方案的手段，无需投入大量时间开发内核驱动。
6. 虚拟化与容器场景
usbipd-win等项目展示了libusb在虚拟化场景中的价值——使得Hyper-V虚拟机和WSL 2可以访问宿主机上的USB设备。
二、libusb vs 内核驱动：何时选择libusb
在Windows上开发USB通信应用时，开发者面临一个基本选择：使用libusb（用户态）还是开发内核驱动（KMDF/WDM）。
| 开发门槛 | 高（需DDK/WDK知识） | 低（标准C接口） |
| 调试难度 | 困难（可能导致系统崩溃） | 容易（用户态调试） |
| 签名要求 | 必须微软认证 | 不需要（但WinUSB需签名） |
| 开发周期 | 通常2-4周 | 1-3天 |
| 性能 | 高（直接内核访问） | 中等（通过用户态API） |
| 稳定性风险 | 高（蓝屏风险） | 低（用户态崩溃可恢复） |
选择建议：
- 选择libusb：大多数数据采集、控制类应用，对延迟和吞吐量要求不极端，需要快速开发
- 选择内核驱动：需要极低延迟（<1ms）或极高吞吐量（>500MB/s）的场景，或需要实现特定内核级功能
三、Windows上libusb驱动安装的完整流程
在Windows上使用基于libusb的软件，通常需要以下步骤：
步骤1：识别设备
首先需要确定目标USB设备的Vendor ID（VID）和Product ID（PID）。可以使用USBView、设备管理器等工具查看设备信息。
步骤2：下载Zadig
从Zadig官方网站（https://zadig.akeo.ie/）下载最新版本的Zadig可执行文件。
步骤3：以管理员身份运行Zadig
右键点击Zadig可执行文件，选择“以管理员身份运行”。
步骤4：选择目标设备
在Options菜单中启用“List All Devices”选项，然后从下拉列表中选择目标USB设备。务必确认选择了正确的设备，以免覆盖其他设备的驱动程序。
步骤5：选择驱动类型
Zadig提供多个驱动选项：
- WinUSB：微软官方驱动，Windows 8+内置，推荐首选
- libusb-win32：传统libusb兼容驱动
- libusbK：较新的替代方案，基于KMDF框架
- USB Serial (CDC)：串口设备驱动
通常选择WinUSB即可满足大多数libusb应用的需求。
步骤6：安装驱动
点击“Replace Driver”按钮，Zadig将开始安装所选驱动。安装过程中可能会弹出Windows安全警告，确认并允许安装继续。
步骤7：验证安装
安装完成后，Zadig会显示成功消息。此时设备应该已经可以使用libusb进行通信了。
四、手动编写INF文件指南（无Zadig环境）
当企业内网禁止下载未知EXE（如Zadig）时，可以手动部署libusb驱动。核心是编写自定义INF文件。
WinUSB的INF模板如下：
[Version]
Signature = "$Windows NT$"
Class = USBDevice
ClassGuid = {88BAE032-5A81-49f0-BC3D-A4FF138216D6}
Provider = %ManufacturerName%
DriverVer=09/04/2024,1.0.0.0
[Manufacturer]
%ManufacturerName% = Standard,NTamd64
[Standard.NTamd64]
%DeviceName% = USB_Install, USB\\VID_1234&PID_5678
[USB_Install]
Include = winusb.inf
Needs = WINUSB.NT
[USB_Install.Services]
Include = winusb.inf
Needs = WINUSB.NT.Services
[USB_Install.HW]
AddReg = Dev_AddReg
[Dev_AddReg]
HKR,,DeviceInterfaceGUIDs,0x10000,"{your-GUID-here}"
此INF利用Windows内置的winusb.inf进行链式安装（通过Include/Needs语法）。编写完成后，通过DevCon.exe或PnPUtil.exe命令行安装：pnputil -i -a mydriver.inf。
特别注意：64位Windows要求INF文件必须经过数字签名（至少是测试签名或企业EV签名），否则会被PnP管理器拒绝加载。如果设备支持WCID，Zadig可以利用这个机制让系统认为该设备“天生”就适合用WinUSB驱动。
五、深入解决“驱动已安装但libusb_open失败”问题
在实际工程中，经常遇到驱动看似安装成功但应用程序无法打开设备的情况。以下是完整的排错决策树：
1. 权限问题。Windows安全模型可能拦截应用程序对USB设备的访问。解决方案：在app.manifest中设置requireAdministrator，或调用libusb_set_auto_detach_kernel_driver解除内核占用。
2. 设备接口GUID不一致。Zadig安装时分配的GUID是随机的（如{A5DCBF10-6530-11D2-901F-00C04FB951ED}）。如果代码中使用了libusb_open_device_with_vid_pid，则不依赖GUID；但如果混用了SetupDi系列原生函数，则需要确保GUID匹配。
3. USB选择性挂起（Selective Suspend） 。Windows电源管理会关闭闲置USB端口，导致libusb_claim_interface返回LIBUSB_ERROR_NO_DEVICE。解决方法：在设备管理器的USB设备属性中，取消勾选“允许计算机关闭此设备以节约电源”。
4. 驱动冲突。某些情况下，系统自带的驱动可能与libusb驱动冲突。例如，iOS有线投屏方案中，libusb驱动会与Apple官方驱动冲突，需要先卸载Apple Mobile Device Support。
5. USB控制器兼容性。某些USB 3.0控制器的驱动程序可能与libusb不兼容，将设备插入USB 2.0端口可以解决此问题。
六、性能调优参数详解
对于高速场景（如SDR或高分辨率摄像头），默认配置往往丢包。需重点调整以下参数：
超时时间（Timeout） ：批量传输超时应设为0（无限等待）或极大值（5000ms），避免操作系统调度抖动造成虚假超时。
缓冲区对齐（Buffer Alignment） ：在Windows x64上，通过libusb_alloc_transfer申请的缓冲区默认非缓存对齐（Non-Cached Alignment）。若直接传递栈变量可能导致PAGE_FAULT_IN_NONPAGED_AREA蓝屏。必须使用malloc或libusb_dev_mem_alloc申请堆内存。
传输缓冲区大小：适当增大传输缓冲区可以减少系统调用次数，提升吞吐量。
异步传输：对于高吞吐量场景，使用异步API而非同步API可以显著提升性能，充分利用Windows的IOCP（完成端口）机制。
