基于WDM模型的虚拟串口驱动实战案例-平芜编程栈

深入Windows内核：手把手打造一个WDM虚拟串口驱动

你有没有遇到过这种情况——手头有一套老旧的工业控制软件，死死绑定在“COM3”上不放，可现在的笔记本连个RS-232接口都没有？或者你想测试一段串口通信协议，却苦于没有真实设备可用？

别急。今天我们不靠硬件，也不用第三方工具，直接从零开始，在Windows内核里“造”一个真正的虚拟串口。它能被系统识别为标准COM端口，支持ReadFile、WriteFile、GetCommState等所有Win32 API操作，甚至PuTTY都能连上去收发数据。

这不是模拟器，不是用户态代理，而是一个基于WDM（Windows Driver Model）的完整内核驱动。我们将一步步拆解它的设计逻辑，深入IRP调度、设备对象创建、IOCTL处理的核心机制，并最终实现一个可运行的虚拟串行端口。

准备好了吗？我们从最底层开始。

为什么是WDM？现代驱动开发的基石

要写驱动，先得明白平台规则。在Windows世界里，WDM虽已不算“最新”，但它仍是理解内核驱动架构的必经之路。

WDM不是一种编程语言，也不是SDK，而是一套驱动分层模型和通信规范。它定义了驱动如何与操作系统交互：如何响应即插即用事件、如何处理电源状态切换、如何接收I/O请求。

它的核心思想很简单：

“一切皆为设备对象，一切操作皆由IRP驱动。”

当你调用CreateFile("\\\\.\\COM3")时，Windows并不会直接跳转到你的代码。相反，I/O管理器会生成一个叫I/O Request Packet（IRP）的结构体，然后把它沿着“设备栈”一层层往下传。谁负责这个COM3，谁就得接住这个IRP并妥善处理。

所以我们的任务就清晰了：
1. 创建一个逻辑设备对象；
2. 注册自己来处理针对该设备的所有IRP；
3. 让系统相信这是一个真实的串口。

听起来复杂？其实关键入口只有几个函数。让我们先看看整个驱动的起点——DriverEntry。

NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath) { NTSTATUS status = STATUS_SUCCESS; // 统一派遣函数（可选） for (int i = 0; i <= IRP_MJ_MAXIMUM_FUNCTION; ++i) { DriverObject->MajorFunction[i] = DispatchGeneral; } // 关键功能重定向 DriverObject->MajorFunction[IRP_MJ_CREATE] = DispatchCreate; DriverObject->MajorFunction[IRP_MJ_CLOSE] = DispatchClose; DriverObject->MajorFunction[IRP_MJ_READ] = DispatchRead; DriverObject->MajorFunction[IRP_MJ_WRITE] = DispatchWrite; DriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] = DispatchControl; DriverObject->MajorFunction[IRP_MJ_PNP] = DispatchPnp; DriverObject->DriverUnload = VirtualSerialUnload; status = CreateVirtualSerialDevice(DriverObject); if (!NT_SUCCESS(status)) { return status; } return STATUS_SUCCESS; }

这段代码看似简单，实则奠定了整个驱动的骨架。其中最关键的一步是注册派遣函数表（MajorFunction）。每个IRP都有一个主功能码（Major Function Code），比如IRP_MJ_READ表示读操作，IRP_MJ_WRITE表示写操作。我们告诉系统：“凡是发给我的读请求，请交给DispatchRead处理”。

最后调用CreateVirtualSerialDevice()才是真正“出生”的时刻——我们要在这里创建两个东西：

设备对象（DEVICE_OBJECT）：代表这个虚拟串口本身；
符号链接（Symbolic Link）：把\Device\VSerial0映射成用户可见的COM3。

NTSTATUS CreateVirtualSerialDevice(PDRIVER_OBJECT drvObj) { UNICODE_STRING devName = RTL_CONSTANT_STRING(L"\\Device\\VSerial0"); UNICODE_STRING symLink = RTL_CONSTANT_STRING(L"\\DosDevices\\COM3"); PDEVICE_OBJECT devObj = NULL; NTSTATUS status = IoCreateDevice( drvObj, sizeof(DEVICE_EXTENSION), // 私有数据区 &devName, FILE_DEVICE_SERIAL_PORT, 0, FALSE, &devObj ); if (!NT_SUCCESS(status)) { return status; } // 设置标志位，允许直接I/O devObj->Flags |= DO_DIRECT_IO; // 创建符号链接 status = IoCreateSymbolicLink(&symLink, &devName); if (!NT_SUCCESS(status)) { IoDeleteDevice(devObj); return status; } // 清除正在删除标志 devObj->Flags &= ~DO_DEVICE_INITIALIZING; return STATUS_SUCCESS; }

注意这里用了FILE_DEVICE_SERIAL_PORT作为设备类型，这是让系统将它识别为串口的关键。否则即使名字叫COM3，也未必能被串口API正确识别。

到这里，系统已经知道：“哦，有个叫COM3的新串口上线了。”但还不能用，因为我们还没初始化内部状态。

虚拟串口的本质：仿真而非模拟

很多人误以为“虚拟串口”就是随便开个管道转发数据。错。真正合格的虚拟串口必须完全兼容Windows串口子系统的语义行为。

这意味着什么？

应用程序可能会做这些事：
- 调用SetCommState设置波特率为115200；
- 查询当前是否启用RTS/CTS流控；
- 使用WaitCommEvent等待字符到达；
- 修改超时参数；

哪怕你根本没有物理引脚，你也得“假装”有。

这就引出了一个重要概念：设备扩展（Device Extension）。

每个DEVICE_OBJECT都可以附带一块私有内存区域，用来保存驱动自己的运行状态。我们在IoCreateDevice时申请了sizeof(DEVICE_EXTENSION)字节空间，现在可以这样定义它：

typedef struct _DEVICE_EXTENSION { PDEVICE_OBJECT DeviceObject; ULONG CurrentBaudRate; UCHAR DataBits; UCHAR StopBits; ULONG Parity; BOOLEAN IsOpened; KEVENT RxReadyEvent; // 接收就绪事件 CHAR RingBuffer[4096]; // 简单环形缓冲区 ULONG Head, Tail; // 读写指针 KSPIN_LOCK BufferLock; // 多线程保护 } DEVICE_EXTENSION, *PDEVICE_EXTENSION;

看到没？我们连“波特率”、“数据位”、“停止位”都存下来了。虽然对纯软件来说这些值毫无意义，但为了兼容性，我们必须维护它们。

当应用调用GetCommState(hCom, &dcb)时，系统底层会发送一个IOCTL_SERIAL_GET_BAUD_RATE控制码。你的驱动必须响应回去，否则API就会失败。

来看具体实现：

NTSTATUS DispatchControl(PDEVICE_OBJECT DeviceObject, PIRP Irp) { PIO_STACK_LOCATION stack = IoGetCurrentIrpStackLocation(Irp); ULONG ioctlCode = stack->Parameters.DeviceIoControl.IoControlCode; PDEVICE_EXTENSION pDevExt = (PDEVICE_EXTENSION)DeviceObject->DeviceExtension; switch (ioctlCode) { case IOCTL_SERIAL_GET_BAUD_RATE: { PSERIAL_BAUD_RATE rate = (PSERIAL_BAUD_RATE)Irp->AssociatedIrp.SystemBuffer; if (stack->Parameters.DeviceIoControl.OutputBufferLength >= sizeof(SERIAL_BAUD_RATE)) { rate->BaudRate = pDevExt->CurrentBaudRate; Irp->IoStatus.Information = sizeof(SERIAL_BAUD_RATE); } else { Irp->IoStatus.Status = STATUS_BUFFER_TOO_SMALL; } break; } case IOCTL_SERIAL_SET_BAUD_RATE: { PSERIAL_BAUD_RATE rate = (PSERIAL_BAUD_RATE)Irp->AssociatedIrp.SystemBuffer; pDevExt->CurrentBaudRate = rate->BaudRate; Irp->IoStatus.Information = 0; break; } case IOCTL_SERIAL_GET_LINE_CONTROL: { PSERIAL_LINE_CONTROL lc = (PSERIAL_LINE_CONTROL)Irp->AssociatedIrp.SystemBuffer; lc->StopBits = pDevExt->StopBits; lc->Parity = pDevExt->Parity; lc->WordLength = pDevExt->DataBits; Irp->IoStatus.Information = sizeof(SERIAL_LINE_CONTROL); break; } default: Irp->IoStatus.Status = STATUS_INVALID_DEVICE_REQUEST; break; } Irp->IoStatus.Status = STATUS_SUCCESS; IoCompleteRequest(Irp, IO_NO_INCREMENT); return Irp->IoStatus.Status; }

看到了吗？我们只是把之前存在pDevExt里的值原样返回。没有硬件参与，全是状态机仿真。

正是这种精细的协议级兼容，使得像Modbus调试工具、PLC编程软件这类“老派”程序也能毫无察觉地使用虚拟串口。

数据怎么流动？读写与事件机制揭秘

接下来是最实用的部分：数据如何进出？

假设你在Python中写了这么一行：

ser.write(b'Hello')

背后发生了什么？

Python调用WriteFile；
I/O管理器生成IRP_MJ_WRITE；
我们的DispatchWrite被触发；
驱动从IRP中取出数据，放入缓冲区或转发出去。

来看DispatchWrite的典型实现：

NTSTATUS DispatchWrite(PDEVICE_OBJECT DeviceObject, PIRP Irp) { PDEVICE_EXTENSION pDevExt = (PDEVICE_EXTENSION)DeviceObject->DeviceExtension; PIO_STACK_LOCATION stack = IoGetCurrentIrpStackLocation(Irp); PUCHAR userBuffer = (PUCHAR)MmGetSystemAddressForMdlSafe(Irp->MdlAddress, NormalPagePriority); if (!userBuffer) { Irp->IoStatus.Status = STATUS_INSUFFICIENT_RESOURCES; goto Complete; } ULONG byteToWrite = stack->Parameters.Write.Length; ULONG written = 0; // 加锁保护环形缓冲区 KIRQL oldIrql; KeAcquireSpinLock(&pDevExt->BufferLock, &oldIrql); for (ULONG i = 0; i < byteToWrite; ++i) { ULONG next = (pDevExt->Head + 1) % sizeof(pDevExt->RingBuffer); if (next == pDevExt->Tail) { break; // 缓冲区满 } pDevExt->RingBuffer[pDevExt->Head] = userBuffer[i]; pDevExt->Head = next; written++; } KeReleaseSpinLock(&pDevExt->BufferLock, oldIrql); // 激活等待接收的线程 if (written > 0) { KeSetEvent(&pDevExt->RxReadyEvent, IO_NO_INCREMENT, FALSE); } Irp->IoStatus.Information = written; Irp->IoStatus.Status = STATUS_SUCCESS; Complete: IoCompleteRequest(Irp, IO_NO_INCREMENT); return Irp->IoStatus.Status; }

这里有几个关键点：
- 使用MmGetSystemAddressForMdlSafe安全访问用户缓冲区；
- 采用自旋锁保护共享资源（因为可能在DISPATCH_LEVEL执行）；
- 写入成功后触发RxReadyEvent，通知等待接收的一方。

那么读呢？类似地，DispatchRead会从环形缓冲区取数据：

NTSTATUS DispatchRead(PDEVICE_OBJECT DeviceObject, PIRP Irp) { PDEVICE_EXTENSION pDevExt = (PDEVICE_EXTENSION)DeviceObject->DeviceExtension; PIO_STACK_LOCATION stack = IoGetCurrentIrpStackLocation(Irp); PUCHAR userBuffer = (PUCHAR)MmGetSystemAddressForMdlSafe(Irp->MdlAddress, NormalPagePriority); if (!userBuffer) { Irp->IoStatus.Status = STATUS_INSUFFICIENT_RESOURCES; goto Complete; } ULONG requested = stack->Parameters.Read.Length; ULONG readCount = 0; KIRQL oldIrql; KeAcquireSpinLock(&pDevExt->BufferLock, &oldIrql); while (readCount < requested && pDevExt->Tail != pDevExt->Head) { userBuffer[readCount++] = pDevExt->RingBuffer[pDevExt->Tail]; pDevExt->Tail = (pDevExt->Tail + 1) % sizeof(pDevExt->RingBuffer); } KeReleaseSpinLock(&pDevExt->BufferLock, oldIrql); Irp->IoStatus.Information = readCount; Irp->IoStatus.Status = STATUS_SUCCESS; Complete: IoCompleteRequest(Irp, IO_NO_INCREMENT); return Irp->IoStatus.Status; }

至此，基本的双向通信能力就具备了。你可以打开两个串口助手，一个往COM3写，另一个从COM3读，数据就能通起来。

当然，更高级的做法是把这部分数据转发到TCP socket、命名管道或另一个虚拟COM口，实现“虚拟串口对”或“串口转网络”。

实战中的坑与避坑指南

你以为编译通过就能用了？内核编程远没那么简单。以下是你一定会踩的几个坑：

❌ 坑一：忘记完成IRP导致系统卡死

每一个进入派遣函数的IRP，必须被完成（IoCompleteRequest）。漏掉这一句，系统就会一直等下去，最终超时崩溃。

建议模式：统一出口处理。

NTSTATUS DispatchRead(...) { ... Complete: IoCompleteRequest(Irp, IO_NO_INCREMENT); return Irp->IoStatus.Status; }

❌ 坑二：未验证用户缓冲区引发蓝屏

如果用户传了一个非法指针（如NULL或受保护地址），直接访问会导致BSOD。务必使用MDL机制或ProbeForRead检查。

改进版：

__try { ProbeForRead(userBuffer, length, 1); // 安全拷贝 } __except(EXCEPTION_EXECUTE_HANDLER) { Irp->IoStatus.Status = GetExceptionCode(); goto Complete; }

❌ 坑三：忽略PnP处理导致无法卸载

如果你不处理IRP_MN_REMOVE_DEVICE，尝试删除设备时系统会报错：“设备正被使用”。

必须在DispatchPnp中正确处理移除流程：

case IRP_MN_REMOVE_DEVICE: IoSkipCurrentIrpStackLocation(Irp); status = IoCallDriver(pDevExt->LowerDevice, Irp); // 如果有下层驱动 // 删除符号链接 UNICODE_STRING symLink = RTL_CONSTANT_STRING(L"\\DosDevices\\COM3"); IoDeleteSymbolicLink(&symLink); // 删除设备 IoDeleteDevice(DeviceObject); return status;

✅ 最佳实践清单

项目	建议
内存访问	使用`MmGetSystemAddressForMdlSafe`或SEH保护
同步机制	自旋锁用于短临界区，避免阻塞
日志输出	使用`DbgPrint("VSerial: Opened at %d bps\n", rate);`配合WinDbg查看
数字签名	64位Windows强制要求驱动签名才能加载
调试工具	WinDbg + !drvobj / !devobj 查看设备状态

这项技术能做什么？超越想象的应用场景

你可能觉得：“我干嘛要自己写驱动？” 但一旦掌握这项能力，你能做的事远超预期。

场景一：工业软件平滑迁移

某工厂的SCADA系统只能通过COM1读取传感器数据。现在传感器改用Wi-Fi上报，怎么办？

方案：写一个虚拟串口驱动，接收MQTT消息，自动注入到COM1的接收缓冲区。原系统无须修改一行代码，照样工作。

场景二：嵌入式开发远程调试

MCU通过UART打印日志，但现场没人会用串口工具。我们可以让板载Linux启动一个服务，将/dev/ttyS0的数据通过SSH隧道转发到云端虚拟串口，开发者用浏览器就能查看实时日志。

场景三：安全审计与协议分析

在金融POS终端中，插入虚拟串口层，记录所有与密码键盘之间的通信内容（脱敏后），用于事后审计或异常检测。

场景四：云环境下的设备仿真

在Azure VM中运行医疗设备仿真器，对外暴露虚拟COM口供上位机连接，内部则对接FHIR REST API完成数据同步。

结语：通往系统级编程的大门已开启

我们刚刚完成了一次完整的旅程：从DriverEntry入口，到设备创建、IRP处理、串口仿真、数据流转，再到实际应用场景。

这个虚拟串口驱动虽然基础，但它涵盖了WDM开发的几乎所有核心要素：
- 驱动生命周期管理；
- 设备对象与符号链接；
- IRP调度与完成机制；
- PnP与电源管理；
- 用户态交互与安全性保障。

更重要的是，你学会了如何思考内核级问题：不是“怎么让功能跑起来”，而是“如何让它像原生组件一样可靠、合规、安全”。

未来你可以在此基础上继续拓展：
- 改用KMDF简化开发；
- 实现一对虚拟串口互连（VSPD模式）；
- 添加加密模块，打造“安全串口”；
- 结合Hyper-V合成设备接口，实现跨虚拟机串口通信。

如果你正在从事工控、物联网、边缘计算或系统安全方向的工作，掌握这项技能会让你在团队中脱颖而出。

毕竟，大多数人只会用API，而你已经知道API背后的真相。

如果你希望获取本文示例的完整工程代码（含.inf安装文件、WDK编译配置），欢迎留言交流。也可以分享你在实际项目中遇到的串口难题，我们一起探讨解决方案。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

基于WDM模型的虚拟串口驱动实战案例