编写 UDE 客户端驱动程序
本文介绍 USB 设备仿真 (UDE) 类扩展的行为，以及客户机驱动程序必须为仿真主机控制器及其连接的设备执行的任务。 它提供有关类驱动程序和类扩展如何通过一组例程和回调函数与每个函数进行通信的信息。 它还介绍了客户端驱动程序应实现的功能。
总结
- 类扩展和客户端驱动程序使用的 UDE 对象和句柄。
- 创建具有查询控制器功能并重置控制器功能的模拟主机控制器。
- 创建虚拟 USB 设备，将其设置为通过端点进行电源管理和数据传输。
重要的 API
- Emulated USB host controller driver programming reference（模拟 USB 主控制器驱动程序编程参考）
开始之前
- 安装开发计算机的最新 Windows 驱动程序工具包 (WDK)。 该工具包具有用于编写 UDE 客户端驱动程序所需的头文件和库，具体而言，需要：
- 存根库 (Udecxstub.lib)。 该库转换客户端驱动程序发出的调用，并将其传递给 UdeCx。
- 头文件 Udecx.h。
- 在目标计算机上安装 Windows 10。
- 自行熟悉聊天 UDE。 请参阅体系结构：USB 设备仿真 (UDE)。
- 熟悉 Windows Driver Foundation (WDF)。 建议阅读：由 Penny Orwick 和 Guy Smith 编写的 Windows Driver Foundation 开发驱动程序。
UDE对象和句柄
UDE 类扩展和客户端驱动程序使用表示模拟主机控制器和虚拟设备的特定 WDF 对象，包括用于在设备和主机之间传输数据的端点和 URB。 客户端驱动程序请求创建对象，并且对象的生存期由类扩展管理。
模拟主机控制器对象 (WDFDEVICE)
表示模拟的主机控制器，是 UDE 类扩展和客户端驱动程序之间的主句柄。
UDE 设备对象 (UDECXUSBDEVICE)
表示连接到模拟主机控制器上的端口的虚拟 USB 设备。
UDE 端点对象 (UDECXUSBENDPOINT)
表示 USB 设备的顺序数据管道。 用于接收端点发送或接收数据的软件请求。
初始化模拟主机控制器
下面是客户端驱动程序检索模拟主机控制器的 WDFDEVICE 句柄的顺序的摘要。 我们建议驱动程序在其 EvtDriverDeviceAdd 回调函数中执行这些任务。
通过传递对框架传递 WDFDEVICE_INIT 的引用来调用 UdecxInitializeWdfDeviceInit。
使用设置信息初始化 WDFDEVICE_INIT 结构，以便此设备与其他 USB 主机控制器类似。 例如，分配 FDO 名称和符号链接，将设备接口注册到 Microsoft 提供的 GUID_DEVINTERFACE_USB_HOST_CONTROLLER GUID 作为设备接口 GUID，以便应用程序可以打开设备的句柄。
调用 WdfDeviceCreate 以创建框架设备对象。
调用 UdecxWdfDeviceAddUsbDeviceEmulation 并注册客户端驱动程序的回调函数。
下面是与主机控制器对象关联的回调函数，这些函数由 UDE 类扩展调用。 这些函数必须由客户端驱动程序实现。
EVT_UDECX_WDF_DEVICE_QUERY_USB_CAPABILITY
确定客户端驱动程序必须向类扩展报告的主控制器支持的功能。
-
可选。 重置主机控制器和/或连接的设备。
EVT_WDF_DRIVER_DEVICE_ADD Controller_WdfEvtDeviceAdd; #define BASE_DEVICE_NAME L"\\Device\\USBFDO-" #define BASE_SYMBOLIC_LINK_NAME L"\\DosDevices\\HCD" #define DeviceNameSize sizeof(BASE_DEVICE_NAME)+MAX_SUFFIX_SIZE #define SymLinkNameSize sizeof(BASE_SYMBOLIC_LINK_NAME)+MAX_SUFFIX_SIZE NTSTATUS Controller_WdfEvtDeviceAdd( _In_ WDFDRIVER Driver, _Inout_ PWDFDEVICE_INIT WdfDeviceInit ) { NTSTATUS status; WDFDEVICE wdfDevice; WDF_PNPPOWER_EVENT_CALLBACKS wdfPnpPowerCallbacks; WDF_OBJECT_ATTRIBUTES wdfDeviceAttributes; WDF_OBJECT_ATTRIBUTES wdfRequestAttributes; UDECX_WDF_DEVICE_CONFIG controllerConfig; WDF_FILEOBJECT_CONFIG fileConfig; PWDFDEVICE_CONTEXT pControllerContext; WDF_IO_QUEUE_CONFIG defaultQueueConfig; WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS idleSettings; UNICODE_STRING refString; ULONG instanceNumber; BOOLEAN isCreated; DECLARE_UNICODE_STRING_SIZE(uniDeviceName, DeviceNameSize); DECLARE_UNICODE_STRING_SIZE(uniSymLinkName, SymLinkNameSize); UNREFERENCED_PARAMETER(Driver); ... WdfDeviceInitSetPnpPowerEventCallbacks(WdfDeviceInit, &wdfPnpPowerCallbacks); WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&wdfRequestAttributes, REQUEST_CONTEXT); WdfDeviceInitSetRequestAttributes(WdfDeviceInit, &wdfRequestAttributes); // To distinguish I/O sent to GUID_DEVINTERFACE_USB_HOST_CONTROLLER, we will enable // enable interface reference strings by calling WdfDeviceInitSetFileObjectConfig // with FileObjectClass WdfFileObjectWdfXxx. WDF_FILEOBJECT_CONFIG_INIT(&fileConfig, WDF_NO_EVENT_CALLBACK, WDF_NO_EVENT_CALLBACK, WDF_NO_EVENT_CALLBACK // No cleanup callback function ); ... WdfDeviceInitSetFileObjectConfig(WdfDeviceInit, &fileConfig, WDF_NO_OBJECT_ATTRIBUTES); ... // Do additional setup required for USB controllers. status = UdecxInitializeWdfDeviceInit(WdfDeviceInit); ... WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&wdfDeviceAttributes, WDFDEVICE_CONTEXT); wdfDeviceAttributes.EvtCleanupCallback = _ControllerWdfEvtCleanupCallback; // Call WdfDeviceCreate with a few extra compatibility steps to ensure this device looks // exactly like other USB host controllers. isCreated = FALSE; for (instanceNumber = 0; instanceNumber < ULONG_MAX; instanceNumber++) { status = RtlUnicodeStringPrintf(&uniDeviceName, L"%ws%d", BASE_DEVICE_NAME, instanceNumber); ... status = WdfDeviceInitAssignName(*WdfDeviceInit, &uniDeviceName); ... status = WdfDeviceCreate(WdfDeviceInit, WdfDeviceAttributes, WdfDevice); if (status == STATUS_OBJECT_NAME_COLLISION) { // This is expected to happen at least once when another USB host controller // already exists on the system. ... } else if (!NT_SUCCESS(status)) { ... } else { isCreated = TRUE; break; } } if (!isCreated) { ... } // Create the symbolic link (also for compatibility). status = RtlUnicodeStringPrintf(&uniSymLinkName, L"%ws%d", BASE_SYMBOLIC_LINK_NAME, instanceNumber); ... status = WdfDeviceCreateSymbolicLink(*WdfDevice, &uniSymLinkName); ... // Create the device interface. RtlInitUnicodeString(&refString, USB_HOST_DEVINTERFACE_REF_STRING); status = WdfDeviceCreateDeviceInterface(wdfDevice, (LPGUID)&GUID_DEVINTERFACE_USB_HOST_CONTROLLER, &refString); ... UDECX_WDF_DEVICE_CONFIG_INIT(&controllerConfig, Controller_EvtUdecxWdfDeviceQueryUsbCapability); status = UdecxWdfDeviceAddUsbDeviceEmulation(wdfDevice, &controllerConfig); // Create default queue. It only supports USB controller IOCTLs. (USB I/O will come through // in separate USB device queues.) // Shown later in this topic. WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(&defaultQueueConfig, WdfIoQueueDispatchSequential); defaultQueueConfig.EvtIoDeviceControl = ControllerEvtIoDeviceControl; defaultQueueConfig.PowerManaged = WdfFalse; status = WdfIoQueueCreate(wdfDevice, &defaultQueueConfig, WDF_NO_OBJECT_ATTRIBUTES, &pControllerContext->DefaultQueue); ... // Initialize virtual USB device software objects. // Shown later in this topic. status = Usb_Initialize(wdfDevice); ... exit: return status; } ```1.
处理发送到主机控制器的用户模式 IOCTL 请求
初始化期间，UDE 客户端驱动程序公开 GUID_DEVINTERFACE_USB_HOST_CONTROLLER 设备接口 GUID。 这使驱动程序能够接收来自使用该 GUID 打开设备句柄的应用程序的 IOCTL 请求。 有关 IOCTL 控制代码的列表，请参阅具有设备接口 GUID 的 USB IOCTL ：GUID_DEVINTERFACE_USB_HOST_CONTROLLER。
为了处理这些请求，客户端驱动程序注册 EvtIoDeviceControl 事件回调。 在实现中，驱动程序可以选择将请求转发到 UDE 类扩展进行处理，而不是处理请求。 若要转发请求，驱动程序必须调用 UdecxWdfDeviceTryHandleUserIoctl。 如果收到的 IOCTL 控制代码对应于标准请求，例如检索设备描述符，则类扩展将处理并成功完成请求。 在这种情况下，UdecxWdfDeviceTryHandleUserIoctl 以 TRUE 作为返回值完成。 否则，调用返回 FALSE，驱动程序必须确定如何完成请求。 在最简单的实现中，驱动程序可以通过调用 WdfRequestComplete 以完成请求，并给出相应的失败代码。
EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL Controller_EvtIoDeviceControl;
VOID
Controller_EvtIoDeviceControl(
_In_
WDFQUEUE Queue,
_In_
WDFREQUEST Request,
_In_
size_t OutputBufferLength,
_In_
size_t InputBufferLength,
_In_
ULONG IoControlCode
)
{
BOOLEAN handled;
NTSTATUS status;
UNREFERENCED_PARAMETER(OutputBufferLength);
UNREFERENCED_PARAMETER(InputBufferLength);
handled = UdecxWdfDeviceTryHandleUserIoctl(WdfIoQueueGetDevice(Queue),
Request);
if (handled) {
goto exit;
}
// Unexpected control code.
// Fail the request.
status = STATUS_INVALID_DEVICE_REQUEST;
WdfRequestComplete(Request, status);
exit:
return;
}
报告主机控制器的功能
在上层驱动程序可以使用 USB 主机控制器的功能之前，驱动程序必须确定控制器是否支持这些功能。 驱动程序通过调用 WdfUsbTargetDeviceQueryUsbCapability 和 USBD_QueryUsbCapability 进行此类查询。 这些调用将转接到 USB 设备仿真 (UDE) 类扩展。 获取请求后，类扩展将调用客户端驱动程序的 EVT_UDECX_WDF_DEVICE_QUERY_USB_CAPABILITY 实现。 此调用仅在 EvtDriverDeviceAdd 完成之后进行，通常在 EvtDevicePrepareHardware 中，而不是在 EvtDeviceReleaseHardware 之后进行。 这是需要回调函数。
在实现中，客户端驱动程序必须报告它是否支持请求的功能。 UDE 不支持某些功能，例如静态流。
NTSTATUS
Controller_EvtControllerQueryUsbCapability(
WDFDEVICE UdeWdfDevice,
PGUID CapabilityType,
ULONG OutputBufferLength,
PVOID OutputBuffer,
PULONG ResultLength
)
{
NTSTATUS status;
UNREFERENCED_PARAMETER(UdeWdfDevice);
UNREFERENCED_PARAMETER(OutputBufferLength);
UNREFERENCED_PARAMETER(OutputBuffer);
*ResultLength = 0;
if (RtlCompareMemory(CapabilityType,
&GUID_USB_CAPABILITY_CHAINED_MDLS,
sizeof(GUID)) == sizeof(GUID)) {
//
// TODO: Is GUID_USB_CAPABILITY_CHAINED_MDLS supported?
// If supported, status = STATUS_SUCCESS
// Otherwise, status = STATUS_NOT_SUPPORTED
}
else {
status = STATUS_NOT_IMPLEMENTED;
}
return status;
}
创建虚拟 USB 服务
虚拟 USB 设备的行为类似于 USB 设备。 它支持具有多个接口的配置，每个接口都支持备用设置。 每个设置可以有一个用于数据传输的端点。 所有描述符（设备、配置、接口、端点）都由 UDE 客户端驱动程序设置，以便设备可以报告与真实 USB 设备非常类似的信息。
注意
UDE 客户端驱动程序不支持外部集线器
下面是客户端驱动程序为 UDE 设备对象创建 UDECXUSBDEVICE 句柄的顺序的摘要。 驱动程序在检索模拟主机控制器的 WDFDEVICE 句柄后必须执行这些步骤。 我们建议驱动程序在其 EvtDriverDeviceAdd 回调函数中执行这些任务。
调用 UdecxUsbDeviceInitAllocate 以获取指向创建设备所需的初始化参数的指针。 此结构由 UDE 类扩展分配。
通过设置 UDECX_USB_DEVICE_STATE_CHANGE_CALLBACKS 的成员并调用 UdecxUsbDeviceInitSetStateChangeCallbacks 来注册事件回调函数。 下面是与 UDE 设备对象关联的回调函数，这些函数由 UDE 类扩展调用。
这些函数由客户端驱动程序实现以创建或配置端点。
调用 UdecxUsbDeviceInitSetSpeed 以设置 USB 设备速度以及设备类型、USB 2.0 或 SuperSpeed 设备。
调用 UdecxUsbDeviceInitSetEndpointsType 以指定设备支持的端点类型：简单或动态。 如果客户端驱动程序选择创建简单端点，驱动程序必须在插入设备之前创建所有端点对象。 设备必须只有一个配置，每个接口只能有一个接口设置。 对于动态端点，驱动程序可以在设备收到 EVT_UDECX_USB_DEVICE_ENDPOINTS_CONFIGURE 事件回调后随时创建端点。 请参阅创建动态端点。
调用上述任一方法，将必要的描述符添加到设备。
UdecxUsbDeviceInitAddStringDescriptorRaw
如果 UDE 类扩展使用上述方法之一收到客户端驱动程序在初始化期间提供的标准描述符的请求，则类扩展会自动完成请求。 类扩展不会将该请求转发到客户端驱动程序。 此设计减少了驱动程序需要处理控制请求的请求数。 此外，它还不需要驱动程序实现描述符逻辑，这些逻辑需要对设置数据包进行广泛的分析，并正确处理 wLength 和 TransferBufferLength。 此列表包括标准请求。 客户端驱动程序不需要为这些请求检查（仅当调用上述方法以添加描述符时）：
USB_REQUEST_GET_DESCRIPTOR
USB_REQUEST_SET_CONFIGURATION
USB_REQUEST_SET_INTERFACE
USB_REQUEST_SET_ADDRESS
USB_REQUEST_SET_FEATURE
USB_FEATURE_FUNCTION_SUSPEND
USB_FEATURE_REMOTE_WAKEUP
USB_REQUEST_CLEAR_FEATURE
USB_FEATURE_ENDPOINT_STALL
USB_REQUEST_SET_SEL
USB_REQUEST_ISOCH_DELAY
但是，对于接口、特定于类或供应商定义的描述符的请求，UDE 类扩展会将它们转发到客户端驱动程序。 驱动程序必须处理这些 GET_DESCRIPTOR 请求。
调用 UdecxUsbDeviceCreate 以创建 UDE 设备对象并检索 UDECXUSBDEVICE 句柄。
通过调用 UdecxUsbEndpointCreate 创建静态端点。 请参阅创建简单端点。
调用 UdecxUsbDevicePlugIn 以指示设备已附加的 UDE 类扩展，并且可以在端点上接收 I/O 请求。 此调用后，类扩展还可以在端点和 USB 设备上调用回调函数。 请注意如果需要在运行时删除 USB 设备，客户端驱动程序可以调用 UdecxUsbDevicePlugOutAndDelete。 如果驱动程序想要使用设备，则必须通过调用 UdecxUsbDeviceCreate 来创建它。
在此示例中，描述符声明假定为全局变量，此处以 HID 设备为例进行声明：
const UCHAR g_UsbDeviceDescriptor[] = {
// Device Descriptor
0x12, // Descriptor Size
0x01, // Device Descriptor Type
0x00, 0x03, // USB 3.0
0x00, // Device class
0x00, // Device sub-class
0x00, // Device protocol
0x09, // Maxpacket size for EP0 : 2^9
0x5E, 0x04, // Vendor ID
0x39, 0x00, // Product ID
0x00, // LSB of firmware version
0x03, // MSB of firmware version
0x01, // Manufacture string index
0x03, // Product string index
0x00, // Serial number string index
0x01 // Number of configurations
};
下面是客户端驱动程序通过注册回调函数、设置设备速度、指示端点类型以及最后设置某些设备描述符来指定初始化参数的示例。
NTSTATUS
Usb_Initialize(
_In_
WDFDEVICE WdfDevice
)
{
NTSTATUS status;
PUSB_CONTEXT usbContext; //Client driver declared context for the host controller object
PUDECX_USBDEVICE_CONTEXT deviceContext; //Client driver declared context for the UDE device object
UDECX_USB_DEVICE_STATE_CHANGE_CALLBACKS callbacks;
WDF_OBJECT_ATTRIBUTES attributes;
UDECX_USB_DEVICE_PLUG_IN_OPTIONS pluginOptions;
usbContext = WdfDeviceGetUsbContext(WdfDevice);
usbContext->UdecxUsbDeviceInit = UdecxUsbDeviceInitAllocate(WdfDevice);
if (usbContext->UdecxUsbDeviceInit == NULL) {
...
goto exit;
}
// State changed callbacks
UDECX_USB_DEVICE_CALLBACKS_INIT(&callbacks);
#ifndef SIMPLEENDPOINTS
callbacks.EvtUsbDeviceDefaultEndpointAdd = UsbDevice_EvtUsbDeviceDefaultEndpointAdd;
callbacks.EvtUsbDeviceEndpointAdd = UsbDevice_EvtUsbDeviceEndpointAdd;
callbacks.EvtUsbDeviceEndpointsConfigure = UsbDevice_EvtUsbDeviceEndpointsConfigure;
#endif
callbacks.EvtUsbDeviceLinkPowerEntry = UsbDevice_EvtUsbDeviceLinkPowerEntry;
callbacks.EvtUsbDeviceLinkPowerExit = UsbDevice_EvtUsbDeviceLinkPowerExit;
callbacks.EvtUsbDeviceSetFunctionSuspendAndWake = UsbDevice_EvtUsbDeviceSetFunctionSuspendAndWake;
UdecxUsbDeviceInitSetStateChangeCallbacks(usbContext->UdecxUsbDeviceInit, &callbacks);
// Set required attributes.
UdecxUsbDeviceInitSetSpeed(usbContext->UdecxUsbDeviceInit, UdecxUsbLowSpeed);
#ifdef SIMPLEENDPOINTS
UdecxUsbDeviceInitSetEndpointsType(usbContext->UdecxUsbDeviceInit, UdecxEndpointTypeSimple);
#else
UdecxUsbDeviceInitSetEndpointsType(usbContext->UdecxUsbDeviceInit, UdecxEndpointTypeDynamic);
#endif
// Add device descriptor
//
status = UdecxUsbDeviceInitAddDescriptor(usbContext->UdecxUsbDeviceInit,
(PUCHAR)g_UsbDeviceDescriptor,
sizeof(g_UsbDeviceDescriptor));
if (!NT_SUCCESS(status)) {
goto exit;
}
#ifdef USB30
// Add BOS descriptor for a SuperSpeed device
status = UdecxUsbDeviceInitAddDescriptor(pUsbContext->UdecxUsbDeviceInit,
(PUCHAR)g_UsbBOSDescriptor,
sizeof(g_UsbBOSDescriptor));
if (!NT_SUCCESS(status)) {
goto exit;
}
#endif
// String descriptors
status = UdecxUsbDeviceInitAddDescriptorWithIndex(usbContext->UdecxUsbDeviceInit,
(PUCHAR)g_LanguageDescriptor,
sizeof(g_LanguageDescriptor),
0);
if (!NT_SUCCESS(status)) {
goto exit;
}
status = UdecxUsbDeviceInitAddStringDescriptor(usbContext->UdecxUsbDeviceInit,
&g_ManufacturerStringEnUs,
g_ManufacturerIndex,
US_ENGLISH);
if (!NT_SUCCESS(status)) {
goto exit;
}
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, UDECX_USBDEVICE_CONTEXT);
status = UdecxUsbDeviceCreate(&usbContext->UdecxUsbDeviceInit,
&attributes,
&usbContext->UdecxUsbDevice);
if (!NT_SUCCESS(status)) {
goto exit;
}
#ifdef SIMPLEENDPOINTS
// Create the default control endpoint
// Shown later in this topic.
status = UsbCreateControlEndpoint(WdfDevice);
if (!NT_SUCCESS(status)) {
goto exit;
}
#endif
UDECX_USB_DEVICE_PLUG_IN_OPTIONS_INIT(&pluginOptions);
#ifdef USB30
pluginOptions.Usb30PortNumber = 2;
#else
pluginOptions.Usb20PortNumber = 1;
#endif
status = UdecxUsbDevicePlugIn(usbContext->UdecxUsbDevice, &pluginOptions);
exit:
if (!NT_SUCCESS(status)) {
UdecxUsbDeviceInitFree(usbContext->UdecxUsbDeviceInit);
usbContext->UdecxUsbDeviceInit = NULL;
}
return status;
}
USB 设备的电源管理
当 UDE 类扩展收到将设备发送到低功率状态或将其恢复工作状态的请求时，UDE 类扩展将调用客户端驱动程序的回调函数。 支持唤醒的 USB 设备需要这些回调函数。 客户端驱动程序在上一次调用 UdecxUsbDeviceInitSetStateChangeCallbacks 中注册了其实现。
有关详细信息，请参阅 USB 设备电源管理状态。
EVT_UDECX_USB_DEVICE_D0_ENTRY：客户端驱动程序将设备从 Dx 状态转换为 D0 状态。
EVT_UDECX_USB_DEVICE_D0_EXIT：客户端驱动程序将设备从 D0 状态转换为 Dx 状态。
EVT_UDECX_USB_DEVICE_SET_FUNCTION_SUSPEND_AND_WAKE：客户端驱动程序更改虚拟 USB 3.0 设备的指定接口的功能状态。
USB 3.0 设备允许各个功能进入较低的电源状态。 每个函数还能够发送唤醒信号。 UDE 类扩展通过调用 EVT_UDECX_USB_DEVICE_SET_FUNCTION_SUSPEND_AND_WAKE 通知客户端驱动程序。 此事件指示函数电源状态更改，并通知客户端驱动程序该函数是否可以从新状态唤醒。 在函数中，类扩展传递正在唤醒的函数的接口号。
客户端驱动程序可以模拟虚拟 USB 设备从低链路电源状态、功能挂起或同时启动其唤醒的虚拟 USB 设备的操作。 对于 USB 2.0 设备，如果驱动程序在最近的 EVT_UDECX_USB_DEVICE_D0_EXIT 中启用了唤醒，驱动程序必须调用 UdecxUsbDeviceSignalWake。 对于 USB 3.0 设备，驱动程序必须调用 UdecxUsbDeviceSignalFunctionWake，因为 USB 3.0 唤醒功能是按函数唤醒的。 如果整个设备处于低功率状态或进入此类状态，则 UdecxUsbDeviceSignalFunctionWake 唤醒设备。
创建简单端点
客户端驱动程序创建 UDE 端点对象来处理与 USB 设备的数据传输。 驱动程序在创建 UDE 设备后以及在将设备报告为插入之前创建简单的端点。
下面是客户端驱动程序为 UDE 端点对象创建 UDECXUSBENDPOINT 句柄的顺序的摘要。 驱动程序在检索虚拟 USB 设备的 UDECXUSBDEVICE 句柄后，必须执行这些步骤。 我们建议驱动程序在其 EvtDriverDeviceAdd 回调函数中执行这些任务。
调用 UdecxUsbSimpleEndpointInitAllocate 以获取指向类扩展分配的初始化参数的指针。
调用 UdecxUsbEndpointInitSetEndpointAddress 以在初始化参数中设置端点地址。
调用 UdecxUsbEndpointInitSetCallbacks 以注册客户端驱动程序实现的回调函数。
这些函数由客户端驱动程序实现，用于处理端点上的队列和请求。
EVT_UDECX_USB_ENDPOINT_RE标准版T：重置虚拟 USB 设备的终结点。
EVT_UDECX_USB_ENDPOINT_START：可选。 开始处理 I/O 请求
EVT_UDECX_USB_ENDPOINT_PURGE：可选。 停止对端点队列的 I/O 请求进行排队，并取消未处理的请求。
调用 UdecxUsbEndpointCreate 以创建端点对象并检索 UDECXUSBENDPOINT 句柄。
调用 UdecxUsbEndpointSetWdfIoQueue 以将框架队列对象与端点相关联。 如果适用，它可以通过设置适当的属性将端点对象设置为队列的 WDF 父对象。
每个端点对象都有一个框架队列对象，用于处理传输请求。 对于类扩展接收的每个传输请求，它会将框架请求对象排入队列。 队列的状态（已启动、清除）由 UDE 类扩展管理，客户端驱动程序不得更改该状态。 每个请求对象都包含一个 USB 请求块 (URB)，其中包含传输的详细信息。
在此示例中，客户端驱动程序创建默认控制端点。
EVT_WDF_IO_QUEUE_IO_INTERNAL_DEVICE_CONTROL IoEvtControlUrb;
EVT_UDECX_USB_ENDPOINT_RESET UsbEndpointReset;
EVT_UDECX_USB_ENDPOINT_PURGE UsEndpointEvtPurge;
EVT_UDECX_USB_ENDPOINT_START UsbEndpointEvtStart;
NTSTATUS
UsbCreateControlEndpoint(
_In_
WDFDEVICE WdfDevice
)
{
NTSTATUS status;
PUSB_CONTEXT pUsbContext;
WDF_IO_QUEUE_CONFIG queueConfig;
WDFQUEUE controlQueue;
UDECX_USB_ENDPOINT_CALLBACKS callbacks;
PUDECXUSBENDPOINT_INIT endpointInit;
pUsbContext = WdfDeviceGetUsbContext(WdfDevice);
endpointInit = NULL;
WDF_IO_QUEUE_CONFIG_INIT(&queueConfig, WdfIoQueueDispatchSequential);
queueConfig.EvtIoInternalDeviceControl = IoEvtControlUrb;
status = WdfIoQueueCreate (Device,
&queueConfig,
WDF_NO_OBJECT_ATTRIBUTES,
&controlQueue);
if (!NT_SUCCESS(status)) {
goto exit;
}
endpointInit = UdecxUsbSimpleEndpointInitAllocate(pUsbContext->UdecxUsbDevice);
if (endpointInit == NULL) {
status = STATUS_INSUFFICIENT_RESOURCES;
goto exit;
}
UdecxUsbEndpointInitSetEndpointAddress(endpointInit, USB_DEFAULT_ENDPOINT_ADDRESS);
UDECX_USB_ENDPOINT_CALLBACKS_INIT(&callbacks, UsbEndpointReset);
UdecxUsbEndpointInitSetCallbacks(endpointInit, &callbacks);
callbacks.EvtUsbEndpointStart = UsbEndpointEvtStart;
callbacks.EvtUsbEndpointPurge = UsEndpointEvtPurge;
status = UdecxUsbEndpointCreate(&endpointInit,
WDF_NO_OBJECT_ATTRIBUTES,
&pUsbContext->UdecxUsbControlEndpoint);
if (!NT_SUCCESS(status)) {
goto exit;
}
UdecxUsbEndpointSetWdfIoQueue(pUsbContext->UdecxUsbControlEndpoint,
controlQueue);
exit:
if (endpointInit != NULL) {
NT_ASSERT(!NT_SUCCESS(status));
UdecxUsbEndpointInitFree(endpointInit);
endpointInit = NULL;
}
return status;
}
创建动态端点
客户端驱动程序可以根据 UDE 类扩展的请求（代表中心驱动程序和客户端驱动程序）创建动态端点。 类扩展通过调用以下任一回调函数发出请求：
*EVT_UDECX_USB_DEVICE_DEFAULT_ENDPOINT_ADD 客户端驱动程序创建默认控制端点（端点 0）
*EVT_UDECX_USB_DEVICE_ENDPOINT_ADD 客户端驱动程序创建动态端点。
*EVT_UDECX_USB_DEVICE_ENDPOINTS_CONFIGURE 客户端驱动程序通过选择备用设置、禁用当前端点或添加动态端点来更改配置。
客户端驱动程序在调用 UdecxUsbDeviceInitSetStateChangeCallbacks 期间注册了上述回调。 请参阅“创建虚拟 USB 设备”。 此机制允许客户端驱动程序动态更改设备上的 USB 配置和接口设置。 例如，当需要端点对象或必须释放现有端点对象时，类扩展将调用 EVT_UDECX_USB_DEVICE_ENDPOINTS_CONFIGURE。
下面是客户端驱动程序在其回调函数实现中为端点对象创建 UDECXUSBENDPOINT 句柄的顺序的摘要。
调用 UdecxUsbEndpointInitSetEndpointAddress 以在初始化参数中设置端点地址。
调用 UdecxUsbEndpointInitSetCallbacks 以注册客户端驱动程序实现的回调函数。 与简单的端点类似，驱动程序可以注册以下回调函数：
调用 UdecxUsbEndpointCreate 以创建端点对象并检索 UDECXUSBENDPOINT 句柄。
调用 UdecxUsbEndpointSetWdfIoQueue 以将框架队列对象与端点相关联。
在此示例实现中，客户端驱动程序创建动态默认控制端点。
NTSTATUS
UsbDevice_EvtUsbDeviceDefaultEndpointAdd(
_In_
UDECXUSBDEVICE UdecxUsbDevice,
_In_
PUDECXUSBENDPOINT_INIT UdecxUsbEndpointInit
)
{
NTSTATUS status;
PUDECX_USBDEVICE_CONTEXT deviceContext;
WDFQUEUE controlQueue;
WDF_IO_QUEUE_CONFIG queueConfig;
UDECX_USB_ENDPOINT_CALLBACKS callbacks;
deviceContext = UdecxDeviceGetContext(UdecxUsbDevice);
WDF_IO_QUEUE_CONFIG_INIT(&queueConfig, WdfIoQueueDispatchSequential);
queueConfig.EvtIoInternalDeviceControl = IoEvtControlUrb;
status = WdfIoQueueCreate (deviceContext->WdfDevice,
&queueConfig,
WDF_NO_OBJECT_ATTRIBUTES,
&controlQueue);
if (!NT_SUCCESS(status)) {
goto exit;
}
UdecxUsbEndpointInitSetEndpointAddress(UdecxUsbEndpointInit, USB_DEFAULT_DEVICE_ADDRESS);
UDECX_USB_ENDPOINT_CALLBACKS_INIT(&callbacks, UsbEndpointReset);
UdecxUsbEndpointInitSetCallbacks(UdecxUsbEndpointInit, &callbacks);
status = UdecxUsbEndpointCreate(UdecxUsbEndpointInit,
WDF_NO_OBJECT_ATTRIBUTES,
&deviceContext->UdecxUsbControlEndpoint);
if (!NT_SUCCESS(status)) {
goto exit;
}
UdecxUsbEndpointSetWdfIoQueue(deviceContext->UdecxUsbControlEndpoint,
controlQueue);
exit:
return status;
}
通过重置端点执行错误恢复
有时，由于各种原因（例如端点中的停滞条件），数据传输可能会失败。 如果传输失败，端点在清除错误条件之前无法处理请求。 当 UDE 类扩展遇到数据传输失败时，它将调用客户端驱动程序的 EVT_UDECX_USB_ENDPOINT_RESET 回调函数，该函数是之前对 UdecxUsbEndpointInitSetCallbacks 的调用中注册的驱动程序。 在实现中，驱动程序可以选择清除管道的 HALT 状态，并采取其他必要步骤来清除错误条件。
该调用是异步的。 在客户端完成重置操作后，驱动程序必须通过调用 WdfRequestComplete 以完成请求，并给出相应的失败代码。 该调用会通知 UDE 客户端扩展完成状态重置操作。
请注意如果错误恢复需要复杂的解决方案，客户端驱动程序可以选择重置主机控制器。 此逻辑可以在驱动程序在其 UdecxWdfDeviceAddUsbDeviceEmulation 调用中注册的 EVT_UDECX_WDF_DEVICE_RESET 回调函数中实现。 如果适用，驱动程序可以重置主机控制器和所有下游设备。 如果客户端驱动程序不需要重置控制器，而是重置所有下游设备，驱动程序必须在注册期间在配置参数中指定 UdeWdfDeviceResetActionResetEachUsbDevice。 在这种情况下，类扩展会为每个连接的设备调用 EVT_UDECX_WDF_DEVICE_RESET。
实现队列状态管理
与 UDE 端点对象关联的框架队列对象的状态由 UDE 类扩展管理。 但是，如果客户端驱动程序将来自端点队列的请求转发到其他内部队列，则客户端必须实现逻辑来处理端点的 I/O 流中的更改。 这些回调函数注册到 UdecxUsbEndpointInitSetCallbacks。
端点清除操作
每个端点有一个队列的 UDE 客户端驱动程序可以实现 EVT_UDECX_USB_ENDPOINT_PURGE，如以下示例所示：
在 EVT_UDECX_USB_ENDPOINT_PURGE 实现中，客户端驱动程序需要确保从端点队列转发的所有 I/O 都已完成，并且新转发的 I/O 也失败，直到调用客户端驱动程序的 EVT_UDECX_USB_ENDPOINT_START。 通过调用 UdecxUsbEndpointPurgeComplete 来满足这些要求，这可确保所有转发的 I/O 都已完成，并且将来的转发 I/O 失败。
端点启动操作
在 EVT_UDECX_USB_ENDPOINT_START 实现中，客户端驱动程序需要开始处理端点队列的 I/O，以及接收端点转发 I/O 的任何队列。 创建端点后，在返回此回调函数之前，它不会收到任何 I/O。 此回调在完成 EVT_UDECX_USB_ENDPOINT_PURGE 后将端点返回到处理 I/O 的状态。
处理数据传输请求 (URB)
若要处理发送到客户端设备端点的 USB I/O 请求，在将队列与终结点关联时，截获与 UdecxUsbEndpointInitSetCallbacks 一起使用的队列对象上的 EVT_WDF_IO_QUEUE_IO_INTERNAL_DEVICE_CONTROL 回调。 在该回调中，处理 IOCTL_INTERNAL_USB_SUBMIT_URB IoControlCode 的 I/O（请参阅 URB 处理方法下的示例代码）。
URB 处理方法
作为通过虚拟设备上与端点关联的队列 IOCTL_INTERNAL_USB_SUBMIT_URB 处理 URI 的一部分，UDE 客户端驱动程序可以使用以下方法获取指向 I/O 请求传输缓冲区的指针：
这些函数由客户端驱动程序实现，用于处理端点上的队列和请求。
UdecxUrbRetrieveControlSetupPacket 从指定的框架请求对象检索 USB 控件设置数据包。
UdecxUrbRetrieveBuffer 从发送到端点队列的指定框架请求对象中检索 URB 的传输缓冲区。
UdecxUrbSetBytesCompleted 设置为框架请求对象中包含的 URB 传输的字节数。
UdecxUrbComplete 使用特定于 USB 的完成状态代码完成 URB 请求。
UdecxUrbCompleteWithNtStatus 使用 NTSTATUS 代码完成 URB 请求。
下面是 USB OUT 传输 URB 的典型 I/O 处理流。
static VOID
IoEvtSampleOutUrb(
_In_ WDFQUEUE Queue,
_In_ WDFREQUEST Request,
_In_ size_t OutputBufferLength,
_In_ size_t InputBufferLength,
_In_ ULONG IoControlCode
)
{
PENDPOINTQUEUE_CONTEXT pEpQContext;
NTSTATUS status = STATUS_SUCCESS;
PUCHAR transferBuffer;
ULONG transferBufferLength = 0;
UNREFERENCED_PARAMETER(OutputBufferLength);
UNREFERENCED_PARAMETER(InputBufferLength);
// one possible way to get context info
pEpQContext = GetEndpointQueueContext(Queue);
if (IoControlCode != IOCTL_INTERNAL_USB_SUBMIT_URB)
{
LogError(TRACE_DEVICE, "WdfRequest %p Incorrect IOCTL %x, %!STATUS!",
Request, IoControlCode, status);
status = STATUS_INVALID_PARAMETER;
goto exit;
}
status = UdecxUrbRetrieveBuffer(Request, &transferBuffer, &transferBufferLength);
if (!NT_SUCCESS(status))
{
LogError(TRACE_DEVICE, "WdfRequest %p unable to retrieve buffer %!STATUS!",
Request, status);
goto exit;
}
if (transferBufferLength >= 1)
{
//consume one byte of output data
pEpQContext->global_storage = transferBuffer[0];
}
exit:
// writes never pended, always completed
UdecxUrbSetBytesCompleted(Request, transferBufferLength);
UdecxUrbCompleteWithNtStatus(Request, status);
return;
}
客户端驱动程序可以使用 DPC 在单独的设备上完成 I/O 请求。 请遵循以下最佳实践：
- 为了确保与现有 USB 驱动程序的兼容性，UDE 客户端必须在 DISPATCH_LEVEL 调用 WdfRequestComplete。
- 如果 URB 已添加到端点队列中，并且驱动程序开始在调用驱动程序的线程或 DPC 上同步处理它，则不能同步完成请求。 为此，需要单独的 DPC，驱动程序通过调用 WdfDpcEnqueue 将其排队。
- 当 UDE 类扩展调用 EvtIoCanceledOnQueue 或 EvtRequestCancel 时，客户端驱动程序必须在独立于调用方线程或 DPC 的单独 DPC 上完成收到的 URB。 为此，驱动程序必须为其 URB 队列提供 EvtIoCanceledOnQueue 回调。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈