从零搭建 Windows 虚拟串口驱动测试环境：实战全解析
你有没有遇到过这样的场景？
调试一个嵌入式设备时，手边只有两三个物理 COM 口，却要同时模拟主从机通信；写了个串口协议解析器，但没有真实硬件可用，只能靠“猜”数据格式；更别提频繁插拔带来的接触不良、系统识别异常……这些看似琐碎的问题，在驱动开发中却足以拖慢整个进度。
这时候，虚拟串口驱动（Virtual Serial Port Driver）就成了你的“救星”。它不是什么黑科技，而是每个底层开发者都该掌握的实用技能——用软件模拟出标准 COM 端口行为，让应用程序像操作真实串口一样读写数据，而背后其实根本没有 UART 芯片。
本文将带你从零开始，在 Windows 上亲手搭建一套完整可调试的虚拟串口驱动环境。我们不讲空泛理论，只聚焦于：如何选型框架、怎么配置工具链、怎样部署并验证功能，以及最关键的——当蓝屏出现时，如何快速定位问题。
全程基于KMDF + WinDbg技术栈，代码可复现，步骤可落地，适合有一定 C 和操作系统基础的开发者进阶使用。
为什么是 KMDF？现代驱动开发的正确打开方式
如果你还停留在 WDM（Windows Driver Model）时代，那现在是时候升级了。微软早在 Vista 时代就推出了WDF（Windows Driver Framework），其中KMDF（Kernel-Mode Driver Framework）成为内核驱动开发的事实标准。
相比传统 WDM 手动管理 IRP、引用计数和资源释放的繁琐模式，KMDF 提供了一套面向对象的抽象模型：
WDFDEVICE表示设备WDFQUEUE处理 I/O 请求WDFREQUEST对应每一个读写或控制请求- 回调机制自动处理 PnP（即插即用）、电源状态切换等复杂逻辑
这意味着你可以把注意力集中在“我要做什么”，而不是“我该怎么避免内存泄漏”。
举个例子：在 WDM 中，你要手动完成IoCompleteRequest、处理取消例程、确保每个路径都正确释放 buffer；而在 KMDF 中，只要调用WdfRequestComplete()，框架会自动帮你做完一切安全检查。
这不仅降低了出错概率，也让代码结构更清晰，更适合团队协作与长期维护。
核心架构设计：我们要造一个“假”串口，但它得像真的
目标很明确：创建一个能被 Windows 识别为 COMx 的设备，支持常见的串口操作，比如：
- 打开关闭端口（
CreateFile("\\\\.\\COM5")） - 设置波特率、校验位等参数
- 发送接收数据（
ReadFile/WriteFile） - 查询状态（
GetCommState）
为了让系统把它当“亲儿子”对待，我们需要让它满足两个条件：
- 设备类必须是 Ports
- 响应所有 IOCTL_SERIAL_* 控制码
前者靠 INF 文件声明，后者由驱动内部实现。
INF 文件的关键配置
[Version] Signature="$WINDOWS NT$" Class=Ports ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} Provider=%ManufacturerName% DriverVer=01/01/2024,1.0.0.0 [Manufacturer] %ManufacturerName%=DeviceList,NTamd64 [DeviceList.NTamd64] "Virtual Serial Port" = VSP_Inst, ROOT\VIRT_SERIAL [VSP_Inst] CopyFiles=Drivers_Dir [Drivers_Dir] MyVirtualSerial.sys [VSP_Inst.Services] AddService=MyVirtualSerial,%SPSVCINST_ASSOCSERVICE%,MyVirtualSerial_Service [MyVirtualSerial_Service] ServiceType=1 StartType=3 ErrorControl=1 ServiceBinary=%12%\MyVirtualSerial.sys [Strings] ManufacturerName="MyCompany"重点说明：
-Class=Ports告诉系统这是一个端口设备。
-ROOT\VIRT_SERIAL是伪总线设备 ID，无需真实硬件即可安装。
-AddService注册服务，系统会在启动时加载.sys文件。
- 安装后，PnP Manager 会自动为其分配 COMx 编号（如 COM5）。
💡 小贴士：可以用
pnputil /add-driver MyVirtualSerial.inf /install命令行一键安装。
驱动主体逻辑：从DriverEntry开始的第一步
KMDF 驱动入口函数非常简洁：
NTSTATUS DriverEntry( _In_ PDRIVER_OBJECT DriverObject, _In_ PUNICODE_STRING RegistryPath ) { WDF_DRIVER_CONFIG config; NTSTATUS status; WDF_DRIVER_CONFIG_INIT(&config, EvtDeviceAdd); status = WdfDriverCreate(DriverObject, RegistryPath, WDF_NO_OBJECT_ATTRIBUTES, &config, WDF_NO_HANDLE); if (!NT_SUCCESS(status)) { KdPrint(("WdfDriverCreate failed: 0x%x\n", status)); return status; } return STATUS_SUCCESS; }这段代码做了三件事：
1. 初始化驱动配置结构；
2. 指定设备添加回调EvtDeviceAdd；
3. 创建 KMDF 驱动对象。
真正的设备初始化发生在EvtDeviceAdd回调中。
设备初始化与 I/O 队列设置
NTSTATUS EvtDeviceAdd( _In_ WDFDRIVER Driver, _Inout_ PWDFDEVICE_INIT DeviceInit ) { WDF_OBJECT_ATTRIBUTES attrs; WDFDEVICE hDevice; NTSTATUS status; // 设置设备名称和类型 WdfDeviceInitSetDeviceType(DeviceInit, FILE_DEVICE_SERIAL_PORT); WdfDeviceInitSetIoType(DeviceInit, WdfDeviceIoDirect); // 创建设备 WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attrs, DEVICE_CONTEXT); 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 = OnRead; queueConfig.EvtIoWrite = OnWrite; queueConfig.EvtIoDeviceControl = OnDeviceControl; status = WdfIoQueueCreate(hDevice, &queueConfig, WDF_NO_OBJECT_ATTRIBUTES, WDF_NO_HANDLE); if (!NT_SUCCESS(status)) { return status; } // 初始化上下文 DEVICE_CONTEXT* ctx = GetDeviceContext(hDevice); ctx->CurrentBaudRate = 115200; InitializeListHead(&ctx->PendingReads); KeInitializeSpinLock(&ctx->Lock); return STATUS_SUCCESS; }这里有几个关键点需要注意：
FILE_DEVICE_SERIAL_PORT是串口设备的标准设备类型，有助于兼容性。- 使用
WdfDeviceIoDirect模式，表示用户缓冲区会被锁定并映射到内核空间，适合大块数据传输。 - I/O 队列设为顺序调度（
DispatchSequential），保证读写不会乱序。 - 自定义
DEVICE_CONTEXT存储波特率、缓冲区指针等运行时状态。
实现串口核心控制码：让 API 查询返回“真”值
应用程序常通过GetCommState获取当前串口配置，这实际上发送的是IOCTL_SERIAL_GET_BAUD_RATE请求。我们必须正确响应这类 IOCTL。
VOID OnDeviceControl( WDFQUEUE Queue, WDFREQUEST Request, size_t OutputLength, size_t InputLength, ULONG IoControlCode ) { NTSTATUS status = STATUS_INVALID_DEVICE_REQUEST; switch (IoControlCode) { case IOCTL_SERIAL_GET_BAUD_RATE: { PSERIAL_BAUD_RATE brate; size_t len; DEVICE_CONTEXT* ctx = GetDeviceContext(WdfIoQueueGetDevice(Queue)); status = WdfRequestRetrieveOutputBuffer(Request, sizeof(SERIAL_BAUD_RATE), (PVOID*)&brate, &len); if (NT_SUCCESS(status)) { brate->BaudRate = ctx->CurrentBaudRate; WdfRequestCompleteWithInformation(Request, STATUS_SUCCESS, sizeof(SERIAL_BAUD_RATE)); } break; } case IOCTL_SERIAL_SET_BAUD_RATE: { PSERIAL_BAUD_RATE brate; status = WdfRequestRetrieveInputBuffer(Request, sizeof(SERIAL_BAUD_RATE), (PVOID*)&brate, NULL); if (NT_SUCCESS(status)) { DEVICE_CONTEXT* ctx = GetDeviceContext(WdfIoQueueGetDevice(Queue)); ctx->CurrentBaudRate = brate->BaudRate; WdfRequestComplete(Request, STATUS_SUCCESS); } break; } default: WdfRequestComplete(Request, status); break; } }虽然波特率只是记个数，并不会真正去配置寄存器，但这个“假装认真”的过程决定了上层工具是否认可你的驱动。
类似地，你还应实现以下常用 IOCTL：
-IOCTL_SERIAL_GET_LINE_CONTROL
-IOCTL_SERIAL_GET_TIMEOUTS
-IOCTL_SERIAL_CLEAR_STATS
否则某些严谨的应用程序（如 LabVIEW 或工业 HMI 软件）可能会拒绝连接。
数据收发模拟：环形缓冲区 + DPC 触发事件
真正的串口有 FIFO 缓冲区和中断机制。我们在软件中也要模拟这一点。
使用环形缓冲区模拟接收队列
typedef struct _RX_BUFFER { UCHAR Buffer[4096]; ULONG Head; // 写入位置 ULONG Tail; // 读取位置 KSPIN_LOCK Lock; } RX_BUFFER;每当有新数据“到达”（例如来自另一个虚拟端口或定时注入），就将其写入Head，然后触发一个 DPC 来通知等待读取的线程：
KeInsertQueueDpc(&ctx->DataReadyDpc, NULL, NULL);在 DPC 中唤醒挂起的读请求：
VOID OnDataReadyDpc( _In_ KDPC* Dpc, _In_opt_ PVOID DeferredContext, _In_opt_ PVOID SystemArgument1, _In_opt_ PVOID SystemArgument2 ) { DEVICE_CONTEXT* ctx = (DEVICE_CONTEXT*)DeferredContext; WDFREQUEST req; // 取出挂起的读请求 if (RemoveHeadList(&ctx->PendingReads)) { req = (WDFREQUEST)CONTAINING_RECORD(...); // 填充数据并完成请求 size_t bytesRead = CopyFromRingBuffer(...); WdfRequestCompleteWithInformation(req, STATUS_SUCCESS, bytesRead); } }这样就实现了类似于真实中断的行为：数据一到，立刻唤醒应用层。
调试才是硬功夫：WinDbg 实战排错指南
再完美的代码也逃不过蓝屏。关键是你能不能快速找到原因。
准备调试环境
推荐使用双机调试模式：
- 主机：运行 WinDbg Preview（Microsoft Store 下载）
- 目标机：开启内核调试
在目标机执行：
bcdedit /debug on bcdedit /dbgsettings serial debugport:1 baudrate:115200主机连接串口或使用虚拟机管道即可建立调试会话。
必备调试命令清单
| 命令 | 功能 |
|---|---|
.sympath SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols | 设置符号服务器 |
.reload /f MyVirtualSerial.sys | 强制重新加载符号 |
bu MyVirtualSerial!DriverEntry | 在驱动入口设断点 |
g | 继续运行 |
!devnode 0 1 | 查看所有设备节点 |
!drvobj MyVirtualSerial 2 | 查看驱动详细信息 |
kb | 显示调用栈 |
当你看到蓝屏错误码（如IRQL_NOT_LESS_OR_EQUAL），第一时间输入kb看堆栈，通常就能定位到非法指针访问的位置。
最常见的几个坑
忘记初始化自旋锁
c KeInitializeSpinLock(&ctx->Lock); // 必须！未保护用户缓冲区访问
即使是WdfRequestRetrieveInputBuffer，在某些情况下仍需__try/__except包裹。对象生命周期管理不当
WDF 是自动清理的，但如果你手动创建了 Timer、DPC 或 WorkItem，记得在EvtDeviceContextCleanup中显式删除。INF 中缺少 PortNumberLocation 注册表项
导致系统不分配 COMx 号。务必加上：
```inf
[VSP_Inst.HW]
AddReg = ComPortNumber
[ComPortNumber]
HKR,”PortNumberLocation”,0x00010001,0,0,0,0
```
应用验证：用 PuTTY 和串口助手打通最后一公里
一切准备就绪后，打开设备管理器，你应该能看到类似：
端口 (COM & LPT) └─ Virtual Serial Port (COM5)接着用 PuTTY 打开 COM5，设置波特率为 115200，点击“Open”。
然后在驱动中模拟一条数据注入：
InjectReceivedData(ctx, "Hello from virtual port!\r\n", 25);如果 PuTTY 正确显示消息，恭喜你——你已经成功构建了一个功能完整的虚拟串口！
还可以进一步测试：
- 多次打开/关闭是否正常？
- 写入大量数据是否会丢包？
- 更改波特率后再查询，值是否一致？
这些才是真实场景下的稳定性考验。
工程建议：不只是跑通，更要健壮
当你打算把这个驱动用于 CI/CD 或自动化测试平台时，以下几个设计原则尤为重要：
✅ 命名隔离
不要用\\Device\\Serial0这种通用名，容易与其他驱动冲突。建议前缀唯一：
static const WCHAR DEVICE_NAME[] = L"\\Device\\VSPort_%d";✅ 支持多实例
修改 INF 中的硬件 ID 后缀，允许安装多个不同实例：
"Virtual Serial Port 1" = VSP_Inst1, ROOT\VIRT_SERIAL1 "Virtual Serial Port 2" = VSP_Inst2, ROOT\VIRT_SERIAL2✅ 日志分级控制
集成 WPP（Windows Software Trace Preprocessor），实现动态日志开关：
DoTraceMessage(INFO, "Received %d bytes", length);发布时关闭详细日志，避免性能损耗。
✅ 模拟异常场景
主动注入延迟、丢包、CRC 错误等故障，测试上层协议栈的容错能力。这是物理设备难以做到的优势。
结语：掌握虚拟串口，你就掌握了通信链路的主动权
虚拟串口驱动的价值远不止于“省几根线”。它是：
- 自动化测试的基础组件
- 协议仿真与中间件开发的理想载体
- 驱动学习的最佳入门项目
- CI/CD 流水线中不可或缺的一环
更重要的是，一旦你能从零写出一个稳定运行的 KMDF 驱动，你会发现其他类型的驱动（如 HID、USB、Network）其本质逻辑都是相通的——无非是对象管理、I/O 处理、资源同步。
所以，别再等硬件到位了。打开 Visual Studio，新建一个 KMDF 驱动工程，今天就开始动手吧。
如果你在实现过程中遇到了具体问题——比如符号加载失败、断点不命中、或者 COM 口无法分配——欢迎留言讨论，我们一起解决。
