USB 设备的电源管理

当 UDE 类扩展收到将设备发送到低功率状态或将其恢复工作状态的请求时，UDE 类扩展将调用客户端驱动程序的回调函数。 支持唤醒的 USB 设备需要这些回调函数。 客户端驱动程序在上一次调用 UdecxUsbDeviceInitSetStateChangeCallbacks 中注册了其实现。

• 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 回调函数中执行这些任务。

1.调用 UdecxUsbSimpleEndpointInitAllocate 以获取指向类扩展分配的初始化参数的指针。

2.调用 UdecxUsbEndpointInitSetEndpointAddress 以在初始化参数中设置端点地址。

3.调用 UdecxUsbEndpointInitSetCallbacks 以注册客户端驱动程序实现的回调函数。

这些函数由客户端驱动程序实现，用于处理端点上的队列和请求。

• EVT_UDECX_USB_ENDPOINT_RE标准版T：重置虚拟 USB 设备的终结点。
• EVT_UDECX_USB_ENDPOINT_START：可选。 开始处理 I/O 请求
• EVT_UDECX_USB_ENDPOINT_PURGE：可选。 停止对端点队列的 I/O 请求进行排队，并取消未处理的请求。

4.调用 UdecxUsbEndpointCreate 以创建端点对象并检索 UDECXUSBENDPOINT 句柄。

5.调用 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 配置和接口设置。 例如，当需要端点对象或必须释放现有端点对象时，类扩展将调用 EVT_UDECX_USB_DEVICE_ENDPOINTS_CONFIGURE。

下面是客户端驱动程序在其回调函数实现中为端点对象创建 UDECXUSBENDPOINT 句柄的顺序的摘要。

1.调用 UdecxUsbEndpointInitSetEndpointAddress 以在初始化参数中设置端点地址。

2.调用 UdecxUsbEndpointInitSetCallbacks 以注册客户端驱动程序实现的回调函数。 与简单的端点类似，驱动程序可以注册以下回调函数：

• EVT_UDECX_USB_ENDPOINT_RESET（必需）。
• EVT_UDECX_USB_ENDPOINT_START
• EVT_UDECX_USB_ENDPOINT_PURGE

3.调用 UdecxUsbEndpointCreate 以创建端点对象并检索 UDECXUSBENDPOINT 句柄。

4.调用 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 处理方法

作为通过虚拟设备上与端点关联的队列 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 回调。