基于Windows Driver Framework的驱动开发示例

用WDF打造虚拟串口驱动：从内核机制到工业级实战

你有没有遇到过这样的场景？开发一个Modbus通信程序，却因为手头没有真实的串口设备而寸步难行；或者想在一台只有USB接口的现代笔记本上调试老式工控机协议，结果发现连COM端口都找不到。更头疼的是，测试团队要求同时模拟十几个串口进行压力测试——难道真要插十几根USB转串口线？

这正是虚拟串口驱动（virtual serial port driver）大显身手的时候。

它不是简单的“软件伪装”，而是一套运行在Windows内核深处的精密系统，能让你的电脑凭空变出COM1、COM2……直到COM256，而且应用程序完全察觉不到这是“假”的。更重要的是，借助微软现代驱动框架Windows Driver Framework（WDF），我们不再需要像过去那样直接与复杂的IRP、自旋锁和即插即用状态机搏斗。

今天，我们就来拆解这套技术的核心逻辑，看看如何用相对“友好”的方式，在内核层构建一个稳定可靠的虚拟串口。

为什么传统串口驱动开发让人望而生畏？

在深入WDF之前，先理解问题的根源。

传统的Windows驱动模型（WDM）就像是让你徒手造一辆汽车：你需要自己设计发动机、变速箱、刹车系统，还要处理所有机械联动细节。每一个I/O请求包（IRP）都要手动解析、完成、释放；资源管理全靠开发者自觉；稍有不慎就会导致蓝屏死机。

尤其是串口这类对时序敏感的设备，你还得模拟波特率、奇偶校验、流控信号（RTS/CTS），甚至中断响应。这对大多数应用开发者来说，门槛太高了。

而WDF的出现，就像提供了标准化的汽车制造平台。你可以专注于“这辆车要跑什么路线”、“乘客体验如何”，而不是螺栓拧几圈才算紧固。

WDF到底改变了什么？

不再是“过程式编程”，而是“事件驱动+对象模型”

WDF最根本的转变在于抽象层次的提升。它把一堆零散的函数指针回调，封装成了清晰的对象结构：

WDFDRIVER：代表整个驱动实例
WDFDEVICE：代表一个逻辑设备（比如COM4）
WDFQUEUE：代表I/O队列（读、写、控制命令）
WDFREQUEST：每个具体的I/O操作请求

这些对象都有明确的生命周期和引用计数，框架自动帮你管理内存释放。你不需要再写成堆的ObDereferenceObject或担心对象提前被销毁。

更重要的是，WDF采用事件回调机制。你只需告诉系统：“当有人打开设备时，请调用我的EvtDeviceAdd函数”；“当收到数据读取请求时，请执行EvtIoRead”。

系统会在合适的时机自动触发这些函数，你只需要关注业务逻辑本身。

内建的安全机制：同步、资源保护、错误隔离

KMDF默认为设备和队列提供多线程访问保护。例如，设置队列为WdfIoQueueDispatchSequential模式后，同一时间只有一个线程能进入该队列的处理函数，天然避免并发冲突。

如果你确实需要并行处理，也可以选择WdfIoQueueDispatchParallel，并通过WDFWAITLOCK等高级同步原语控制共享资源访问。

此外，WDF与Windows验证工具（如Static Driver Verifier）深度集成，能在编译期发现潜在的资源泄漏、未完成请求等问题，极大提升了驱动稳定性。

构建你的第一个虚拟串口：不只是“Hello World”

下面这段代码虽然简短，但它已经是一个可加载、可识别的虚拟串口骨架：

#include <ntddk.h> #include <wdf.h> typedef struct _DEVICE_CONTEXT { WDFQUEUE ReadQueue; WDFQUEUE WriteQueue; } DEVICE_CONTEXT, *PDEVICE_CONTEXT; WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(DEVICE_CONTEXT, GetDeviceContext) NTSTATUS DriverEntry(_In_ PDRIVER_OBJECT DriverObject, _In_ PUNICODE_STRING RegistryPath) { WDF_DRIVER_CONFIG config; WDFDRIVER hDriver; WDF_DRIVER_CONFIG_INIT(&config, WDF_NO_EVENT_CALLBACK); config.EvtDriverUnload = EvtDriverUnload; return WdfDriverCreate(DriverObject, RegistryPath, WDF_NO_OBJECT_ATTRIBUTES, &config, &hDriver); }

注意这里的DriverEntry有多简洁？没有注册一堆分发函数，也没有手动创建设备对象。一切交给WdfDriverCreate去处理。

真正的核心在EvtDeviceAdd中展开：

NTSTATUS EvtDeviceAdd(_In_ WDFDRIVER Driver, _Inout_ PWDFDEVICE_INIT DeviceInit) { WDF_OBJECT_ATTRIBUTES attrs; WDFDEVICE hDevice; // 告诉系统：我是一个串口设备 WdfDeviceInitSetDeviceType(DeviceInit, FILE_DEVICE_SERIAL_PORT); WdfDeviceInitSetIoType(DeviceInit, WdfDeviceIoDirect); WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attrs, DEVICE_CONTEXT); NTSTATUS status = WdfDeviceCreate(&DeviceInit, &attrs, &hDevice); if (!NT_SUCCESS(status)) return status; // 创建I/O队列 WDF_IO_QUEUE_CONFIG queueConfig; WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(&queueConfig, WdfIoQueueDispatchSequential); queueConfig.EvtIoRead = EvtIoRead; queueConfig.EvtIoWrite = EvtIoWrite; queueConfig.EvtIoDeviceControl = EvtIoDeviceControl; // 控制命令 status = WdfIoQueueCreate(hDevice, &queueConfig, WDF_NO_OBJECT_ATTRIBUTES, NULL); if (!NT_SUCCESS(status)) return status; // 暴露给用户空间：这就是COM4 WdfDeviceCreateSymbolicLink(hDevice, L"\\DosDevices\\COM4"); return STATUS_SUCCESS; }

关键点解析：

FILE_DEVICE_SERIAL_PORT是让系统识别为串口的关键标志。否则即使名字叫COM4，也不会出现在设备管理器的“端口”列表下。
使用WdfDeviceIoDirect意味着I/O缓冲区会被锁定在物理内存中，适合直接传递给硬件——虽然是虚拟设备，但保持兼容性很重要。
WdfDeviceCreateSymbolicLink创建符号链接，这是用户态程序通过\\.\COM4访问设备的桥梁。

让虚拟串口真正“活”起来：不只是回声

很多人写的虚拟串口只能做一件事：你写什么，它就在日志里打印什么。但这远远不够。真实的应用期望能设置波特率、查询状态、控制流信号。

这就必须处理各种IOCTL控制码。来看一个典型实现：

VOID EvtIoDeviceControl(_In_ WDFQUEUE Queue, _In_ WDFREQUEST Request, _In_ size_t OutputBufferLength, _In_ size_t InputBufferLength, _In_ ULONG IoControlCode) { PDEVICE_CONTEXT devCtx = GetDeviceContext(WdfIoQueueGetDevice(Queue)); NTSTATUS status = STATUS_SUCCESS; ULONG info = 0; switch (IoControlCode) { case IOCTL_SERIAL_GET_BAUD_RATE: { PSERIAL_BAUD_RATE baudRate = (PSERIAL_BAUD_RATE) WdfRequestWdmGetIrp(Request)->UserBuffer; if (baudRate && OutputBufferLength >= sizeof(SERIAL_BAUD_RATE)) { baudRate->BaudRate = 115200; info = sizeof(SERIAL_BAUD_RATE); } else { status = STATUS_BUFFER_TOO_SMALL; } break; } case IOCTL_SERIAL_SET_BAUD_RATE: { PSERIAL_BAUD_RATE baudRate = (PSERIAL_BAUD_RATE) WdfRequestWdmGetIrp(Request)->UserBuffer; if (baudRate) { KdPrint(("Virtual COM: Baud rate set to %lu\n", baudRate->BaudRate)); // 可在此更新内部状态 } info = 0; break; } case IOCTL_SERIAL_GET_LINE_CONTROL: case IOCTL_SERIAL_SET_LINE_CONTROL: // 模拟数据位、停止位、校验位 status = STATUS_SUCCESS; // 简化处理，实际应填充结构体 info = 0; break; default: status = STATUS_INVALID_DEVICE_REQUEST; break; } WdfRequestCompleteWithInformation(Request, status, info); }

这个函数拦截了常见的串口配置请求。尽管我们并不真的去配置某个UART芯片，但必须返回合理的响应，否则某些严谨的串口库（如.NET SerialPort）会直接报错退出。

数据怎么流动？读写请求的背后

当应用程序调用ReadFile时，内核最终会生成一个IRP_MJ_READ请求，由WDF转发到EvtIoRead：

VOID EvtIoRead(_In_ WDFQUEUE Queue, _In_ WDFREQUEST Request, _In_ size_t Length) { char* simulated_data = "RESPONSE_FROM_VIRTUAL_DEVICE\n"; size_t actual_len = strlen(simulated_data); PVOID outputBuffer; // 获取输出缓冲区 if (!NT_SUCCESS(WdfRequestRetrieveOutputBuffer(Request, Length, &outputBuffer, NULL))) { WdfRequestComplete(Request, STATUS_INVALID_PARAMETER); return; } // 复制模拟数据（注意边界） RtlCopyBytes(outputBuffer, simulated_data, min(Length, actual_len)); // 完成请求，并告知实际传输字节数 WdfRequestCompleteWithInformation(Request, STATUS_SUCCESS, min(Length, actual_len)); }

这里有个重要细节：必须调用WdfRequestCompleteWithInformation并传入实际字节数。否则ReadFile将永远阻塞，或者返回0字节。

同理，WriteFile到达驱动后：

VOID EvtIoWrite(_In_ WDFQUEUE Queue, _In_ WDFREQUEST Request, _In_ size_t Length) { PVOID inputBuffer; size_t lenCopied; if (NT_SUCCESS(WdfRequestRetrieveInputBuffer(Request, Length, &inputBuffer, &lenCopied))) { KdPrint(("VSPD: Received %zu bytes: '%.*s'\n", lenCopied, (int)min(lenCopied, 32), (char*)inputBuffer)); // 在此可添加转发至网络、保存日志、触发响应等逻辑 } WdfRequestCompleteWithInformation(Request, STATUS_SUCCESS, Length); }