4、EvtIoRead派遣函数：读取请求处理流程、缓冲区管理、完成例程注册

在KMDF框架中，EvtIoRead是处理IRP_MJ_READ请求的核心派遣回调。驱动程序通过注册该回调，接收来自应用程序或内核其他组件的读取请求。本章深入剖析读取请求的完整处理流程、三种缓冲区管理模型的选择与实现，以及完成例程的注册机制与执行上下文。

4.1 读取请求处理流程

当应用程序调用ReadFile或内核组件发送IRP_MJ_READ时，KMDF框架自动调用驱动注册的EvtIoRead回调。整个处理流程可分为四个阶段：请求接收、参数验证、数据传输、请求完成。

4.2 缓冲区管理模型

KMDF提供三种缓冲区管理模型，驱动在创建队列时通过WDF_IO_QUEUE_CONFIG结构体的PowerManaged和DefaultQueue等字段配合WdfDeviceInitSetIoType指定。选择正确的模型直接影响性能与兼容性。

4.3 缓冲区获取与数据访问

在EvtIoRead中，驱动通过KMDF提供的API获取缓冲区指针或内存对象。不同I/O模型对应的API不同：

• 缓冲I/O： 使用 WdfRequestRetrieveOutputBuffer 获取系统分配的中间缓冲区。
• 直接I/O： 使用 WdfRequestRetrieveOutputMemory 获取WDFMEMORY对象，再通过 WdfMemoryGetBuffer 获取虚拟地址。
• 两者皆可： 直接访问 WdfRequestWdmGetIrp 返回的IRP中的 UserBuffer 或 SystemBuffer。

// 示例：在EvtIoRead中使用缓冲I/O获取输出缓冲区
VOID
EvtIoRead(
    _In_ WDFQUEUE Queue,
    _In_ WDFREQUEST Request,
    _In_ size_t Length
    )
{
    NTSTATUS status;
    PVOID buffer;
    size_t bufferLength;

    // 获取输出缓冲区（缓冲I/O模型）
    status = WdfRequestRetrieveOutputBuffer(
        Request,
        Length,           // 请求的最小字节数
        &buffer,
        &bufferLength
        );

    if (!NT_SUCCESS(status)) {
        WdfRequestComplete(Request, status);
        return;
    }

    // 执行硬件读取操作，将数据填入buffer
    // ...

    // 完成请求，返回实际读取的字节数
    WdfRequestCompleteWithInformation(
        Request,
        STATUS_SUCCESS,
        bufferLength
        );
}

4.4 完成例程注册

完成例程（CompletionRoutine）是KMDF驱动中处理异步I/O操作完成通知的关键机制。当驱动将请求提交到硬件或转发到其他队列后，通过注册完成例程来接收操作完成的通知。

完成例程的注册通过WdfRequestSetCompletionRoutine实现，其函数原型如下：

VOID
WdfRequestSetCompletionRoutine(
    _In_ WDFREQUEST Request,
    _In_ PFN_WDF_REQUEST_COMPLETION_ROUTINE CompletionRoutine,
    _In_opt_ WDFCONTEXT Context
    );

完成例程回调函数必须遵循以下签名：

VOID
EvtRequestCompletionRoutine(
    _In_ WDFREQUEST Request,
    _In_ WDFIOTARGET Target,
    _In_ PWDF_REQUEST_COMPLETION_PARAMS Params,
    _In_ WDFCONTEXT Context
    );

4.5 完成例程中的关键操作

在完成例程中，驱动通常需要执行以下操作：

1. 检查完成状态： 通过 Params->IoStatus.Status 判断操作是否成功。
2. 获取传输字节数： 通过 Params->IoStatus.Information 获取实际传输的字节数。
3. 处理错误： 如果硬件返回错误，驱动可能需要重试或记录错误日志。
4. 完成原始请求： 调用 WdfRequestComplete 或 WdfRequestCompleteWithInformation 通知上层请求已完成。

// 完成例程实现示例
VOID
EvtReadCompletionRoutine(
    _In_ WDFREQUEST Request,
    _In_ WDFIOTARGET Target,
    _In_ PWDF_REQUEST_COMPLETION_PARAMS Params,
    _In_ WDFCONTEXT Context
    )
{
    NTSTATUS status = Params->IoStatus.Status;
    size_t information = (size_t)Params->IoStatus.Information;

    if (!NT_SUCCESS(status)) {
        // 硬件操作失败，记录错误
        TraceEvents(TRACE_LEVEL_ERROR, DBG_READ,
                    "Read failed with status 0x%X\n", status);
        WdfRequestComplete(Request, status);
        return;
    }

    // 成功：将实际读取的字节数返回给上层
    WdfRequestCompleteWithInformation(
        Request,
        STATUS_SUCCESS,
        information
        );
}

4.6 异步读取与请求转发

对于需要长时间等待硬件响应的读取操作，驱动不应在EvtIoRead中同步等待。正确的做法是将请求转发到专用队列，由DpcForIsr或专用线程完成操作。

// 将读取请求转发到手动队列进行异步处理
VOID
EvtIoRead(
    _In_ WDFQUEUE Queue,
    _In_ WDFREQUEST Request,
    _In_ size_t Length
    )
{
    NTSTATUS status;
    WDFQUEUE manualQueue;

    // 获取驱动定义的异步处理队列
    manualQueue = GetDeviceContext(Queue)->AsyncReadQueue;

    // 转发请求到手动队列
    status = WdfRequestForwardToIoQueue(
        Request,
        manualQueue
        );

    if (!NT_SUCCESS(status)) {
        WdfRequestComplete(Request, status);
    }
    // 请求已转发，EvtIoRead返回
}

在异步队列中，驱动可以注册EvtIoDefault回调来处理转发的请求，并在硬件中断的DpcForIsr中完成请求。

4.7 常见故障排查清单