如何使用 WinUSB？

Question

这是我之前问题的后续问题，

背景

我正在使用 STM32 微控制器（裸机/无 OS）设计 USB 外围设备。该设备偶尔会连接到 Windows PC，并在每个方向上传输几 KB 的数据。将有一个自定义 PC 应用程序使用专有协议（即用于 USB 有效负载）控制数据传输。

PC 将始终是主机（启动器）- 它会发送命令，而设备会发出响应，在单个命令或响应中向任一方向发送最多几百字节的数据。我想我会想使用 USB 批量传输模式。

选项 1 - USB CDC

据我了解，一种选择是我可以使用 USB 通信设备 Class (CDC)。在设备方面，我可以将 ST 的示例代码用于 USB CDC，例如来自 STM32Cube。在 PC 端，设备将显示为虚拟 COM 端口 (VCP)。然后在软件中我基本上有一个原始的双向流，我必须在其上定义我的消息格式、命令等。

我的解释正确吗？

选项 2 - WinUSB

我无法完全理解这是什么以及如何使用它。

WinUSB与USB设备classes有什么关系？它似乎可以作为 "generic" USB class 使用，但我找不到任何说明如此的文档。
WinUSB 是否提供任何内置消息定界符？例如WinUsb_WritePipe 是否将缓冲区的内容作为原子单元向下发送到设备？或者我只是得到像 VCP/UART?
如何在设备上实现 WinUSB？有可用的示例代码吗？（最好是 STM32。）

正在选择

在为我的申请选择选项 1 和 2 时有哪些相关考虑因素？

Answer 1

是的，您正确描述了 USC CDC ACM。
WinUSB 的存在是为了支持没有特定设备的设备 class。如果您的设备实现了一种设备 class，例如人机接口设备、大容量存储设备或通信设备 (CDC)，您可以只使用操作系统附带的驱动程序与该设备通信。如果您想要一个不符合其中一个 classes 的更可定制和更灵活的 USB 接口，您可以使用 WinUSB 与您的设备通信。如果需要，您也可以编写自己的驱动程序，但这将需要大量工作，我不推荐这样做。有些人编写了替代 WinUSB 的驱动程序：您可以查找 libusbK、libusb0.sys 和 UsbDK 作为示例。 WinUSB 具有 Windows 附带的优势，因此我不会使用其他驱动程序之一，除非它具有您真正需要的特定功能。
我相信 WinUSB_WritePipe 将数据作为单个 USB 传输发送。 Atransfer在USB规范中有具体的定义。您可以知道传输何时结束，因为您会在传输结束时收到一个短数据包。短数据包是小于端点最大数据包大小的数据包，它可能是零长度的。你应该仔细检查这是否真的是真的；尝试发送一个最大数据包大小的倍数的传输，并确保 Windows 在最后发送一个零长度数据包。顺便说一句，您应该考虑将数据作为控制传输或端点 0 上的一系列控制传输来发送。控制传输具有请求和对请求的响应的内置概念。尽管名称如此，但控制传输可用于传输大量数据；它们通常用于 USB 引导加载程序（参见 DFU class）。使用控制传输而不是非零端点的另一个优点是您不必添加额外的端点描述符并在固件中初始化端点。您的 USB 堆栈应该具有处理自定义控制传输的机制，并且您应该能够通过编写一些回调函数来进行自定义控制传输。
要在设备端实现 WinUSB，您需要编写自己的 USB 描述符，然后使用低级 USB 传输命令从端点读取和写入数据，或处理端点 0 上供应商特定的控制传输.我不熟悉 STM32 USB 库，但你应该能够识别它的核心组件，它实现了控制传输和 IN 和 OUT 端点，而不需要对设备做任何特定的事情 class。这是您需要学习如何使用的组件。
默认情况下，您应该使用 WinUSB 而不是 USB CDC ACM。使用 USB CDC ACM 的唯一原因是，如果您的设备实际上是一个串行端口，或者如果您想让人们在各种编程语言和环境中更轻松地与您的设备交谈。大多数编程语言都支持串行端口，但用户仍然必须在生成特定命令格式的代码之上编写代码，因此它实际上并没有给你那么多。 USB CDC ACM 的一个问题是，如果设备在您打开句柄时断开连接，然后重新连接，则各种 USB CDC ACM 驱动程序通常会进入错误状态。特别是 Windows 10 之前的 usbser.sys 不能很好地处理这个问题，您通常必须拔下并重新插入设备才能使 COM 端口再次可用。 USB CDC ACM 使用批量端点进行数据传输，因此没有延迟保证。使用 WinUSB，您可以选择使用中断端点，这样可以保证始终为每个 USB 帧传输一个数据包。

Answer 2

WinUSB 由两部分组成：

WinUsb.sys 是一个 kernel-mode 驱动程序，可以作为过滤器或功能驱动程序安装，位于 USB 设备的 kernel-mode 设备堆栈中的协议驱动程序之上。
WinUsb.dll 是一个 user-mode DLL，公开了 WinUSB API。当它作为设备的功能驱动程序安装时，应用程序可以使用此 API 与 WinUsb.sys 通信。 WinUSB API—由 WinUSB.dll 公开。 WinUSB 以 co-installer 包 WinUSBCoInstaller.dll 的形式包含在 Windows 驱动程序套件 (WDK) 中，位于 WinDDK\BuildNumber\Redist\Winusb.

要在应用程序中使用 WinUSB API：

包括WinUsb.h
将 WinUsb.lib 添加到链接到您的应用程序的库列表中。
Usb100.h 包含一些有用的宏的声明。
使用设备接口GUID获取设备路径。正确的 GUID 是您在用于安装 WinUsb.sys.
通过将您在 INF 中定义的设备接口 GUID 传递给 SetupDiGetClassDevs 来获取设备信息集的句柄。函数returns一个HDEVINFO句柄。
调用SetupDiEnumDeviceInterfaces来枚举系统的设备接口，获取你的设备接口信息。
调用 SetupDiGetDeviceInterfaceDetail 获取设备接口的详细数据。
调用GetDevicePath函数获取设备路径
将设备路径传递给CreateFile以获得设备的文件句柄。使用 ReadFile 和 WriteFile 与设备 通信。
将文件句柄传递给WinUsb_Initialize以初始化WinUSB并获得WinUSB句柄。当您调用 WinUSB API 函数时，您使用设备的 WinUSB 句柄来识别设备，而不是设备的文件句柄。

对于更高级的解决方案 - 使用函数：

WinUsb_QueryDeviceInformation获取设备的速度。
WinUsb_QueryInterfaceSettings获取对应的接口描述符。 WinUSB句柄对应第一个接口
WinUsb_QueryPipe 获取有关每个端点的信息。
WinUsb_WritePipe 将缓冲区写入设备 - 默认行为：zero-length 写入向下转发到堆栈。如果传输长度大于最大传输长度，WinUSB 将请求分成最大传输长度的更小请求并依次提交。
更多功能和信息：http://download.microsoft.com/download/9/c/5/9c5b2167-8017-4bae-9fde-d599bac8184a/winusb_howto.docx

出于调试目的您可能需要： winusbtrace_tool https://blogs.msdn.microsoft.com/usbcoreblog/2010/02/05/how-to-generate-and-view-a-winusb-debug-trace-log/; 带 USBPcap 插件的 Wireshark https://www.wireshark.org。

其他示例： http://searchingforbit.blogspot.com/2012/04/winusb-communication-with-stm32-part-1.html。示例模板附带 Visual Studio.

您还需要具备编写 .inf 文件的知识。

另一种与 USB 通信的简单方法 - libusb-win32 https://sourceforge.net/projects/libusb-win32/

我的简单示例控制台应用程序向设备发送小的（keep-alive）数据块：

#include "stdafx.h"
#include <SetupAPI.h>
#include <Hidsdi.h> 
#include <devguid.h> 
#include <winusb.h>
#include <usb.h>
#pragma comment(lib, "hid.lib")
#pragma comment(lib, "setupapi.lib")
#pragma comment(lib, "winusb.lib")
#include <iUString.h> 


iString<char> DevicePath;
bool                    WinusbHandle_Open=false;
bool                    DeviceHandle_Open = false;
WINUSB_INTERFACE_HANDLE WinusbHandle;
HANDLE                  DeviceHandle;
UCHAR usb_out_buffer[64];
DEFINE_GUID(GUID_DEVCLASS_WINUSB, 0x88bae032L, 0x5a81, 0x49f0, 0xbc, 0x3d, 0xa4, 0xff, 0x13, 0x82, 0x16, 0xd6);
DEFINE_GUID(GUID_DEVCLASS_STL, 0xf177724dL, 0x74d3, 0x430e, 0x86, 0xb5, 0xf0, 0x36, 0x89, 0x10, 0xeb, 0x23);
GUID winusb_guid;
GUID stl_guid;

bool connectusb();
void  disconnectusb();




int main()
{
    DWORD n;
    DWORD   numEvents;
    HANDLE rHnd;    

WinusbHandle_Open = false;
DeviceHandle_Open = false;
winusb_guid = GUID_DEVCLASS_WINUSB;
stl_guid = GUID_DEVCLASS_STL;
usb_out_buffer[0] = 0;
usb_out_buffer[1] = 1;
usb_out_buffer[2] = 2;
usb_out_buffer[3] = 3;

ULONG bytesWritten;
ULONG timeout;
timeout = 100;
rHnd = GetStdHandle(STD_INPUT_HANDLE);

WinUsb_SetPipePolicy(WinusbHandle, 0x01, PIPE_TRANSFER_TIMEOUT, sizeof(ULONG), &timeout);

timeout = TRUE;
WinUsb_SetPipePolicy(WinusbHandle, 0x01, AUTO_CLEAR_STALL, sizeof(ULONG), &timeout);


timeout = TRUE;
WinUsb_SetPipePolicy(WinusbHandle, 0x01, RAW_IO, sizeof(ULONG), &timeout);//Bypasses queuing and error handling to boost performance for multiple read requests.


while (true)
{
if ((!WinusbHandle_Open) || (!WinusbHandle_Open)) { if (!connectusb())Sleep(2000); }
if ((!WinusbHandle_Open) || (!WinusbHandle_Open))continue;

bytesWritten = 0;
if (!WinUsb_WritePipe(WinusbHandle, 0x01, &usb_out_buffer[0], 2, &bytesWritten, NULL))
{
    n = GetLastError();
disconnectusb();
}
Sleep(2000);
}
disconnectusb();
return 0;
}




bool connectusb()
{
    BOOL                             bResult = FALSE;
    HDEVINFO                         deviceInfo;
    SP_DEVICE_INTERFACE_DATA         interfaceData;
    PSP_DEVICE_INTERFACE_DETAIL_DATA detailData = NULL;
    DWORD n;
    SP_DEVINFO_DATA devinfo;
    BYTE devdetailbuffer[4096];
    bool found;

    deviceInfo = SetupDiGetClassDevs(&stl_guid, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
    if (deviceInfo == INVALID_HANDLE_VALUE) { return false; }

    found = false;
    for (n = 0;; n++)
    {

        interfaceData.cbSize = sizeof(SP_DEVICE_INTERFACE_DATA);

        if (!SetupDiEnumDeviceInterfaces(deviceInfo, NULL, &stl_guid, n, &interfaceData))
        {
            n = GetLastError();
            break;
        }




        detailData = (PSP_DEVICE_INTERFACE_DETAIL_DATA)devdetailbuffer;
        detailData->cbSize = sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA);
        devinfo.cbSize = sizeof(devinfo);
        if (!SetupDiGetDeviceInterfaceDetail(deviceInfo, &interfaceData, detailData, sizeof(devdetailbuffer), NULL, &devinfo)) { printf("SetupDiGetDeviceInterfaceDetail: %u\n", GetLastError()); break; }
        if (IsEqualGUID(devinfo.ClassGuid, winusb_guid))
        {
            if ((-1 != iStrPos(detailData->DevicePath, "VID_0483")) || (-1 != iStrPos(detailData->DevicePath, "vid_0483")))
            {
                if ((-1 != iStrPos(detailData->DevicePath, "PID_576B")) || (-1 != iStrPos(detailData->DevicePath, "pid_576b")))
                {

                    DevicePath = detailData->DevicePath;
                    found = true;
                    break;
                }
            }
        }
    }



SetupDiDestroyDeviceInfoList(deviceInfo);
if (!found)return false;


DeviceHandle = CreateFile(DevicePath.Buffer() ,
    GENERIC_WRITE | GENERIC_READ,
    FILE_SHARE_WRITE | FILE_SHARE_READ,
    NULL,
    OPEN_EXISTING,
    FILE_ATTRIBUTE_NORMAL | FILE_FLAG_OVERLAPPED,
    NULL);

if (INVALID_HANDLE_VALUE == DeviceHandle) {
    n = GetLastError();
}

if (INVALID_HANDLE_VALUE == DeviceHandle) return false;
DeviceHandle_Open = true;



if (!WinUsb_Initialize(DeviceHandle, &WinusbHandle))
 {
     n = GetLastError();
     CloseHandle(DeviceHandle); DeviceHandle_Open = false;
     return false;
 }



WinusbHandle_Open = true;
return true;
}

void  disconnectusb()
{
    if (WinusbHandle_Open) { WinUsb_Free(WinusbHandle); WinusbHandle_Open = false; }
    if (DeviceHandle_Open) { CloseHandle(DeviceHandle); DeviceHandle_Open = false; }
}