尧图网站建设 
简介基于WDM模型的PCI驱动开发资料包面向Windows平台底层驱动开发者可系统理解PCI设备与操作系统的交互机制并掌握WDK工具链下PCI/PCIe驱动的编写与调试流程。包内共20个文件以C源码.cpp/.h、工程配置文件.vcxproj/.sln/.dsw及INF安装文件等为主整体仅110KB结构紧凑便于快速对照学习。目前已有331人学习/下载具备切实的参考价值。内容围绕MyDriver与Test两个工程展开覆盖PnP即插即用、电源管理、IRP请求处理、设备与驱动对象链接、PCI配置空间读取等关键概念同时附有驱动测试与检查工程方便进行设备枚举和功能验证。通过阅读源码并结合WDK实践可形成从驱动框架搭建到实际部署的完整路径为后续扩展其他PCI/PCIe设备开发打下扎实基础。1. 从一块识别不到的 PCIe 板卡说起为什么还得啃 WDM 驱动拿到一块 PCIe 接口的采集卡或 FPGA 开发板插上 Windows 主机设备管理器里出现一个带黄色感叹号的未知设备这是绝大多数驱动开发入行的起点。你想要的无非是让它被系统认出来、能读写它的寄存器、能把它的中断和 DMA 用起来。这个目标在 Windows 下有多种实现路径而WDM_PCI_Driver这个标题指向的就是用WDMWindows Driver Model配合WDKWindows Driver Kit手写一个 PCI/PCIe 功能驱动。WDM 是 Windows 2000 时代定下的驱动模型到今天仍然没有过时。原因是 PCI/PCIe 设备的基本交互方式——配置空间、BAR 空间、中断、DMA——三十年来没有本质变化WDM 提供的 IRP 分发、PnP 启动、电源管理这套框架依然是把这些资源正确接进 Windows 的最底层途径。后面出现的 KMDF/WDF 只是把 WDM 的样板代码封装了一层真正要跟硬件打交道的地方你迟早还是得回到 WDM 的语义上来。这篇笔记适合两类人一是刚被分配了 PCIe 驱动任务、手里只有一块板卡和一份寄存器手册的嵌入式工程师二是做过 Linux 下 PCI 驱动、第一次转 Windows 平台的老手。我会把环境搭建、驱动骨架、BAR 访问、中断处理、常见翻车点一路写到底所有代码都基于 WDK 的通用框架你可以直接当模板用。2. WDM、WDF 与 KMDFPCI 驱动在 Windows 下的选型别一上来就写代码2.1 为什么老项目大量停留在 WDM新项目该怎么选WDM 和 WDFWindows Driver Frameworks的关系不是替代而是继承。WDF 里的 KMDF 把 PnP、电源管理、即插即启动这些固定流程封装成回调让驱动开发者不用手动处理 IRP_MJ_PNP 和 IRP_MN_START_DEVICE。好处是代码量少、不容易把状态机写错坏处是封装层在调试某些硬件异常时会变成黑匣子——你想在设备启动序列中间插一步自定义操作得弄清楚框架在哪一环调用你的 EvtDevicePrepareHardware以及失败时返回值怎么传递。WDM 恰恰相反一切从 DriverEntry 开始全部靠你手动注册 Dispatch routines然后按 IRP 的走向一步步走。它在今天仍然大量存在主要因为三类场景存量驱动维护大量工控机、医疗设备、老式采集卡上的驱动是 2005 年前后写的 WDM没人愿意冒风险重写成 KMDF。需要最底层控制KMDF 对某些 PCIe 高级特性比如多 BAR 的资源配置顺序、MSI/MSI-X 的逐个向量控制做了框架层面的默认行为绕开它反而比在它里面做定制更直接。学习价值WDM 把所有机制都摊在明面上读懂 WDM 再去看 KMDF 的封装会有一种原来它替我干了这些的透彻感。我做这类驱动时的选型原则是板卡是自家 FPGA、寄存器手册齐全、生命周期长就用 WDM如果是帮客户包一层简单 PCIe 设备、对方只看交付速度KMDF 更合适。本文按 WDM 为主线展开但避坑章节里也会提 KMDF 的对应注意点。2.2 WDM 驱动处理硬件事件的核心机制IRP 与 PnP 回调在 WDM 的世界里应用程序通过 CreateFile/DeviceIoControl 与驱动通信内核里的一切都是一条条 IRPI/O Request Packet。PCI 驱动最关心的 IRP 类型有IRP 类型对应请求驱动里该做的事IRP_MJ_CREATECreateFile 打开设备增加打开计数可做权限检查IRP_MJ_DEVICE_CONTROLDeviceIoControl 发控制码按 IOCTL 分发读写 BAR、控制中断、启动 DMAIRP_MJ_READ / WRITE应用程序读/写可选很多 PCI 驱动只用 IOCTL 间接访问IRP_MJ_PNP 子码: IRP_MN_START_DEVICE系统分配硬件资源映射 BAR、连接中断、初始化设备IRP_MJ_PNP 子码: IRP_MN_REMOVE_DEVICE设备被拔出/禁用释放中断、解除映射、删除设备对象这套机制对 PCIe 设备的一个重要含义是你的驱动不是一个主动去探测硬件的程序而是被动响应系统 PnP 管理器的调用。系统枚举 PCIe 总线、读设备的 Vendor ID / Device ID、找到匹配的 INF 后加载你的驱动然后按顺序发送 START_DEVICE、给你分配资源。因此 WDM 驱动里没有入口检测硬件这种逻辑——一切从 DriverEntry 注册回调开始硬件在 START_DEVICE 才真正被激活。2.3 一个 WDM PCI 驱动的完整链路DriverEntry 到 START_DEVICE一个最小可工作的 WDM PCI 驱动文件结构通常是这样的WDM_PCI_Driver/ ├── driver.c // DriverEntry、IRP 分发表、设备控制 ├── hw_access.c // BAR 映射、寄存器读写、中断处理 ├── hw_access.h ├── driver.inf // 硬件 ID、驱动安装信息 └── sources / .vcxproj // 构建配置WDK 下用 MSBuild 编译链路的关键节点是 DriverEntry→AddDevice→START_DEVICE。DriverEntry 里你要做的是设置 DriverObject 的各个 MajorFunction、创建设备扩展结构模板、然后调用 IoCreateDevice 创建设备对象。AddDevice 是 PnP 管理器在发现匹配硬件时回调你的地方在这里创建设备对象、建立设备链接符号链接名比如 \Device\PCIeDev0 和 \DosDevices\PCIeDev0。到这一步设备对象存在了但硬件资源还没有分配。真正的资源交接发生在 IRP_MN_START_DEVICE 处理里系统在 Parameters.StartDevice.AllocatedResources 中给出设备的资源列表驱动在这里提取 PhysicalMemory 范围对应 BAR 空间、中断向量/级别然后调用 MmMapIoSpace 把物理地址映射到非分页池中断用 IoConnectInterrupt 挂接。这也是 WDM 与用户态驱动最大的感受差异用户态读写寄存器像访问内存一样简单内核态却要时刻记着我现在在 IRQL 级别多少、这段代码能不能分页、这个操作能不能睡眠。绝大部分蓝屏和驱动开发翻车根源都在这里。3. 搭建 WDK 开发环境版本匹配、目标机配置与常见绕弯路3.1 WDK 与 Visual Studio 版本的配套关系这是新手第一个坑安装 WDK 最忌讳的就是版本随意配。WDK 不是独立编译工具链它依赖 Visual Studio 的 MSBuild 集成。官方版本的配套关系如下Visual Studio 版本对应 WDK 版本支持的 Windows 目标VS 2019 16.xWDK 10.0.19041.x 及以上Windows 10 1809 / Server 2019VS 2022 17.xWDK 10.0.22621.x 及以上Windows 10 2004 / Server 2022VS 2017WDK 10.0.16299.xWindows 10 1709常见翻车是装了 VS 2022 却下载了非常老版本的 WDK安装器直接提示不支持当前的 Visual Studio 版本。我的做法是先确认目标运行环境是 Win10 还是 Win11再按微软官方页面上匹配关系倒推选版本。如果你在 Win11 上做开发、目标机也是 Win11直接选 WDK 10.0.22621 对应的最新版即可。安装完 WDK 后在 VS 里新建项目时选择Empty WDM Driver模板。这里有个值得注意的点WDK 自带模板生成的项目是 KMDF 的WDM 的话选 Empty WDM Driver 才行。项目创建后确认两个配置Target Platform 选 Desktop而不是 Universal驱动类型选 Kernel。这两个地方选错编译出来的 INF 会带有错误装饰导致真机安装时签名校验失败。3.2 目标机、调试机与 WinDbg 的连接配置WDM 驱动开发必须有目标机——本机改驱动、本机测试一旦蓝屏开发环境跟着遭殃而且很多设备在开发机上根本没有物理插槽。标准做法是准备一台独立的调试目标机可以是旧电脑目标机通过网口或串口与开发机相连开发机上用 WinDbg 做内核调试。配置调试机时注意这几步在目标机上以管理员身份执行bcdedit /debug on bcdedit /dbgsettings net hostip:192.168.1.100 port:50000 key:1.2.3.4这里 hostip 是开发机的 IPport 是 WinDbg 监听端口key 是调试会话密钥。目标机重启后开机阶段会等待调试器连接。测试驱动前建议先把目标机系统设置为自动重新启动关闭——否则蓝屏一闪而过你连 Bugcheck 信息都看不到bcdedit /set {current} bootstatuspolicy displayallfailures连接调试会话时开发机 WinDbg 选择 File→Kernel Debug→Net填入目标机 IP 和端口。连接成功后那条命令提示符变成kd你就可以在驱动加载前下断点了。3.3 签名配置与测试签名模式跑通驱动安装的最后一道坎64 位 Windows 要求驱动必须签名开发阶段不想买 EV 证书就打开测试签名模式bcdedit /set testsigning on之后生成的自签名测试证书需要导入目标机的受信任的根证书颁发机构和受信任的发布者存储。这里有个隐蔽的坑WDK 编译驱动时默认生成的是 .cer 证书文件你需要在目标机上右键 CER 文件选择安装证书手工选存储位置为本地计算机→受信任的根证书颁发机构。如果只双击导入到当前用户存储INF 安装时会报错驱动程序无法验证此设备的签名。更彻底的做法是用工具包里的 inf2cat 和 signtool 对驱动包做交叉签名cross-sign先用 makecert 生成测试证书再用 signtool sign 对 .sys 文件签名最后用 inf2cat 生成目录文件并签名。步骤多但一次配好后面每次编译只需要跑一个批处理。我一般把这套签名流程写成一个 build_and_sign.bat放在项目根目录内容大致是echo off set SYS_FILEWDM_PCI_Driver.sys signtool sign /v /s My /n MyTestCert /t http://timestamp.digicert.com /f testcert.pfx %SYS_FILE% inf2cat /driver:. /os:10_X64 signtool sign /v /f testcert.pfx /t http://timestamp.digicert.com WDM_PCI_Driver.cat注意 inf2cat 的/driver:参数必须指向包含 .inf 和 .sys 的目录如果这一行报错Unable to produce catalog多半是 INF 里 Manufacturer 段的 Provider 名与签名机构不一致。这个点我后面避坑章节还会再提。4. 写一个可编译的 WDM PCIe 驱动骨架从 DriverEntry 到 BAR 空间访问4.1 DriverEntry 与设备创建三行关键代码背后的必要逻辑先给一个最简 DriverEntry它在整个 PCI 驱动生命周期里只做一次NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath) { NTSTATUS status; UNICODE_STRING deviceName; UNICODE_STRING symLinkName; PDEVICE_OBJECT deviceObject NULL; // 注册派发例程未注册的 MajorFunction 会被系统默认处理为 STATUS_INVALID_DEVICE_REQUEST DriverObject-MajorFunction[IRP_MJ_CREATE] PciDrvCreateClose; DriverObject-MajorFunction[IRP_MJ_CLOSE] PciDrvCreateClose; DriverObject-MajorFunction[IRP_MJ_DEVICE_CONTROL] PciDrvDeviceControl; DriverObject-MajorFunction[IRP_MJ_PNP] PciDrvPnP; DriverObject-DriverUnload PciDrvUnload; // 创建设备对象 RtlInitUnicodeString(deviceName, L\\Device\\PciDev0); status IoCreateDevice(DriverObject, sizeof(DEVICE_EXTENSION), deviceName, FILE_DEVICE_UNKNOWN, FILE_DEVICE_SECURE_OPEN, FALSE, deviceObject); if (!NT_SUCCESS(status)) { return status; } // 创建符号链接让 Win32 应用可以通过 CreateFile 打开设备 RtlInitUnicodeString(symLinkName, L\\DosDevices\\PciDev0); status IoCreateSymbolicLink(symLinkName, deviceName); if (!NT_SUCCESS(status)) { IoDeleteDevice(deviceObject); return status; } // 设备扩展清零并初始化 PDEVICE_EXTENSION dx (PDEVICE_EXTENSION)deviceObject-DeviceExtension; memset(dx, 0, sizeof(DEVICE_EXTENSION)); dx-DeviceObject deviceObject; return STATUS_SUCCESS; }代码逻辑上最关键的一点是设备扩展Device Extension的设计。这个结构体是你的驱动在设备生命周期内的记事本——BAR 映射后的虚拟地址、中断对象指针、设备状态标志都存在这里。每次 IRP 到达时你通过 IoGetCurrentIrpStackLocation 拿到 IRP 栈的位置再通过 DeviceObject-DeviceExtension 取回这些数据。设备扩展的设计直接决定了驱动在多设备实例下能否正常工作因此从 DriverEntry 起就应该规划好它的字段。IoCreateDevice 的 FILE_DEVICE_SECURE_OPEN 标志建议加上否则任何进程只要知道符号链接名就能打开设备这对工业设备来说等于裸奔。从安全角度WDM 里没有现成的权限控制机制需要你在 IRP_MJ_CREATE 里自己检查进程状态或使用访问控制列表但至少加上这个标志能让系统默认拦掉大部分非法访问。4.2 START_DEVICE把 BAR 空间变成可访问的内存设备对象创建完毕等 PnP 管理器把资源分配好再真正初始化硬件。标准写法是在 IRP_MJ_PNP 处理函数里分派子码NTSTATUS PciDrvPnP(PDEVICE_OBJECT deviceObject, PIRP irp) { PIO_STACK_LOCATION irpStack IoGetCurrentIrpStackLocation(irp); PDEVICE_EXTENSION dx (PDEVICE_EXTENSION)deviceObject-DeviceExtension; switch (irpStack-MinorFunction) { case IRP_MN_START_DEVICE: return PciDrvStartDevice(dx, irp); case IRP_MN_REMOVE_DEVICE: if (dx-InterruptObject) { IoDisconnectInterrupt(dx-InterruptObject); dx-InterruptObject NULL; } if (dx-BarVirtualAddress) { MmUnmapIoSpace(dx-BarVirtualAddress, dx-BarLength); dx-BarVirtualAddress NULL; } return PciDrvFinishRemoveDevice(dx, irp); default: IoSkipCurrentIrpStackLocation(irp); return IoCallDriver(dx-LowerDeviceObject, irp); // 下层设备对象在 AddDevice 时挂接 } }START_DEVICE 的具体处理里资源提取是关键NTSTATUS PciDrvStartDevice(PDEVICE_EXTENSION dx, PIRP irp) { PCM_PARTIAL_RESOURCE_LIST resourceList; ULONG i; PHYSICAL_ADDRESS barPhys; ULONG barLength; resourceList irp-Parameters.StartDevice.AllocatedResources-List[0].PartialResourceList; for (i 0; i resourceList-Count; i) { PCM_PARTIAL_RESOURCE_DESCRIPTOR desc resourceList-PartialDescriptors[i]; if (desc-Type CmResourceTypeMemory) { // 取 BAR0 对应的物理地址和长度 barPhys desc-u.Memory.Start; barLength desc-u.Memory.Length; dx-BarPhysicalAddress barPhys; dx-BarLength barLength; // 把物理地址映射到内核虚拟地址之后才能直接读写 dx-BarVirtualAddress MmMapIoSpace(barPhys, barLength, MmNonCached); if (!dx-BarVirtualAddress) { return STATUS_INSUFFICIENT_RESOURCES; } // 清掉 BAR 空间里的遗留状态防止设备在上电假死状态 WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress 0x00), 0xFFFFFFFF); KdPrint((PCI: BAR0 mapped at %p, len %lu\n, dx-BarVirtualAddress, barLength)); break; } } if (resourceList-Count) { // 挂接中断——注意PCIe MSI/MSI-X 在 WDM 里也是用 CmResourceTypeInterrupt 上报 for (i 0; i resourceList-Count; i) { PCM_PARTIAL_RESOURCE_DESCRIPTOR desc resourceList-PartialDescriptors[i]; if (desc-Type CmResourceTypeInterrupt) { IoConnectInterrupt(dx-InterruptObject, PciDrvIsr, // 中断服务例程 dx, // 传给 ISR 的上下文 NULL, desc-u.Interrupt.Vector, desc-u.Interrupt.Level, desc-u.Interrupt.Affinity); KdPrint((PCI: Interrupt connected vector%lu\n, desc-u.Interrupt.Vector)); break; } } } IoCompleteRequest(irp, IO_NO_INCREMENT); return STATUS_SUCCESS; }这里有一点必须说清楚BAR 空间映射用 MmMapIoSpace 时缓存属性必须指定为 MmNonCached。PCIe 设备的寄存器映射到 CPU 地址空间后如果 CPU 的缓存策略把它当普通内存读同一个寄存器可能得到旧值——因为硬件端改变了数据但 CPU 缓存还没失效。这个玄学问题一旦出现表现就是死循环读状态寄存器永远等不到设备就绪。另一个选择是 MmMapIoSpace 的变种 MmMapIoSpaceEx 可以指定更多属性但默认场景 MmNonCached 就是对的。WRITE_REGISTER_ULONG 这类宏的本质是 _declspec(noinline) 的内联函数它保证编译器和 CPU 都不会对这个 volatile 地址的访问做重排。访问 PCIe 设备寄存器时永远不要用直接解引用指针的方式除非你明确知道自己在做什么并加了 volatile 强制但即便如此用 WRITE_REGISTER* 系列才是 WDK 推荐做法。4.3 设备控制IOCTL让用户态程序安全地读写你的寄存器驱动写完用户态程序要能访问。通常做法是定义一组 IOCTL把读某个偏移的寄存器、写某个偏移的寄存器、获取设备状态这些操作暴露出去#define IOCTL_PCI_READ_REG CTL_CODE(FILE_DEVICE_UNKNOWN, 0x800, METHOD_BUFFERED, FILE_ANY_ACCESS) #define IOCTL_PCI_WRITE_REG CTL_CODE(FILE_DEVICE_UNKNOWN, 0x801, METHOD_BUFFERED, FILE_ANY_ACCESS) NTSTATUS PciDrvDeviceControl(PDEVICE_OBJECT deviceObject, PIRP irp) { PIO_STACK_LOCATION irpStack IoGetCurrentIrpStackLocation(irp); PDEVICE_EXTENSION dx (PDEVICE_EXTENSION)deviceObject-DeviceExtension; ULONG ioctlCode irpStack-Parameters.DeviceIoControl.IoControlCode; PVOID systemBuffer irp-AssociatedIrp.SystemBuffer; ULONG inputLen irpStack-Parameters.DeviceIoControl.InputBufferLength; ULONG outputLen irpStack-Parameters.DeviceIoControl.OutputBufferLength; NTSTATUS status STATUS_SUCCESS; ULONG bytesReturned 0; switch (ioctlCode) { case IOCTL_PCI_READ_REG: { if (inputLen sizeof(PCI_REG_ACCESS) || outputLen sizeof(ULONG)) { status STATUS_BUFFER_TOO_SMALL; break; } PCI_REG_ACCESS *access (PCI_REG_ACCESS *)systemBuffer; if (access-Offset sizeof(ULONG) dx-BarLength) { status STATUS_INVALID_PARAMETER; break; } *(PULONG)systemBuffer READ_REGISTER_ULONG( (PULONG)((PUCHAR)dx-BarVirtualAddress access-Offset)); bytesReturned sizeof(ULONG); break; } case IOCTL_PCI_WRITE_REG: { if (inputLen sizeof(PCI_REG_ACCESS)) { status STATUS_BUFFER_TOO_SMALL; break; } PCI_REG_ACCESS *access (PCI_REG_ACCESS *)systemBuffer; if (access-Offset sizeof(ULONG) dx-BarLength) { status STATUS_INVALID_PARAMETER; break; } WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress access-Offset), access-Value); bytesReturned sizeof(PCI_REG_ACCESS); break; } default: status STATUS_INVALID_DEVICE_REQUEST; break; } irp-IoStatus.Status status; irp-IoStatus.Information bytesReturned; IoCompleteRequest(irp, IO_NO_INCREMENT); return status; }参数说明里IOCTL 的 METHOD_BUFFERED 方式对小型寄存器访问是够用的它把输入输出都放在系统缓冲区里内核帮你处理好用户态/内核态内存拷贝。缺点是每次 IOCTL 调用都会有一次系统缓冲区分配如果采集场景要求高频率读寄存器比如每毫秒读取一次状态位效率会不够。高频场景应该改用 METHOD_IN_DIRECT 或 METHOD_OUT_DIRECT配合用户态 MDL 做直接 IO但线程同步和缓冲区生命周期管理就没这么省心。这里没有加任何锁。如果你的设备控制函数会被多线程并发调用必须用自旋锁或者互斥锁保护对寄存器序列的访问。否则两个线程交错写一个多字节的寄存器组设备可能收到一个中间状态。驱动里的竞争条件不一定会立刻蓝屏但表现往往是偶发性设备不响应——这种问题最难排查全靠锁提前防住。4.4 中断与 DPC为什么 ISR 里绝对不能直接做耗时操作WDM 的中断处理分两部分ISRInterrupt Service Routine在 DIRQL 执行必须极短剩下的工作在 DPCDeferred Procedure Call里完成。ISR 只做两件事——判断中断是否来自你的设备、如果是否认则返回 FALSE 让系统继续分发如果是则清除中断源写入中断状态寄存器并调度 DPCBOOLEAN PciDrvIsr(PKINTERRUPT InterruptObject, PVOID Context) { PDEVICE_EXTENSION dx (PDEVICE_EXTENSION)Context; ULONG status READ_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress INT_STATUS_REG)); if (!(status INT_STATUS_VALID)) { return FALSE; // 不是本设备中断 } // 立刻清中断源避免同一中断反复触发 WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress INT_STATUS_REG), status); // 调度 DPC 做后续工作 KeInsertQueueDpc(dx-InterruptDpc, NULL, NULL); return TRUE; }DPC 例程里可以做需要加锁的、稍重的操作比如读取一大块 FIFO 数据、更新计数器、向用户态应用发通知事件VOID PciDrvDpc(KDPC *Dpc, PVOID Context, PVOID SystemArgument1, PVOID SystemArgument2) { PDEVICE_EXTENSION dx (PDEVICE_EXTENSION)Context; // 从 FIFO 搬数据 ULONG count READ_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress FIFO_COUNT_REG)); while (count 0) { dx-FifoData[dx-FifoIndex] READ_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress FIFO_DATA_REG)); count--; } if (dx-FifoIndex FIFO_THRESHOLD) { KeSetEvent(dx-DataReadyEvent, IO_NO_INCREMENT, FALSE); } }强调一点ISR 里如果执行超过几十微秒会拖累整个系统的中断响应甚至导致其他设备的中断超时。像读取 PCIe 设备 FIFO 这种事原则上也可以全部放 DPCISR 只做中断仲裁。另外如果设备支持 MSI/MSI-XWDM 层不需要区分——资源列表里报什么你就连什么ISR 签名一样。4.5 DMA 传输的最小实现缓冲区锁页与地址映射PCIe 驱动的高吞吐场景绕不开 DMA。WDM 下最简单的方式是让用户态程序提供一个缓冲区驱动用 MmProbeAndLockPages 锁页后把物理地址给设备做 DMA 传输// 假设 METHOD_OUT_DIRECTirp-MdlAddress 指向用户缓冲区 NTSTATUS PciDrvStartDma(PDEVICE_EXTENSION dx, PIRP irp) { PMDL mdl irp-MdlAddress; if (!mdl) { return STATUS_INVALID_PARAMETER; } // 锁页防止用户缓冲被换出物理内存 __try { MmProbeAndLockPages(mdl, UserMode, IoReadAccess); } __except (EXCEPTION_EXECUTE_HANDLER) { return STATUS_INVALID_USER_BUFFER; } PHYSICAL_ADDRESS pa MmGetMdlPhysicalAddress(mdl); ULONG len MmGetMdlByteCount(mdl); // 通知设备 DMA 目标地址和长度 WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress DMA_ADDR_LO_REG), (ULONG)pa.QuadPart); WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress DMA_ADDR_HI_REG), (ULONG)(pa.QuadPart 32)); WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress DMA_LEN_REG), len); WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress DMA_GO_REG), 1); return STATUS_PENDING; }注意DMA 的方向如果是从设备到内存用户缓冲区的缓存属性必须一致。MmProbeAndLockPages 锁住的页面可能仍带 CPU 缓存导致设备写内存后 CPU 读出来是旧数据。解决方法是让设备侧关闭 FIFO 的 snoop或者改用 MmAllocateContiguousMemory 分配一致性内存做中转。工业级的做法是单独开一个环形缓冲区用生产者-消费者指针管理避免 DMA 完成后还有缓存同步的开销。DMA 完成的中断响应就是 4.4 里的 ISRDPC 流程的延伸ISR 处理传输完成中断DPC 里检查 DMA 状态寄存器、解锁页面、完成挂起的 IRP然后用户态被唤醒。这个完整闭环是 PCIe 驱动性能的核心一步做错就是数据错误或者驱动挂死。5. WDM PCIe 驱动开发的避坑指南现象、原因、解决5.1 现象编译报错 STATUS_INVALID_DEVICE_REQUEST或 IRP 无法下发到驱动原因最常见的原因是 DriverEntry 里没有注册 IRP_MJ_PNP或注册了但 Inc 函数没有正确导出。很多人会漏掉DriverObject-MajorFunction[IRP_MJ_POWER]系统在设备启动序列里发电源 IRP 时得不到响应默认按失败处理导致设备启动中断。电源 IRP 也是 WDM 驱动被忽视的大头特别在从休眠恢复时最容易翻车。解决DriverEntry 里把 PnP 和 Power 都显式注册单独处理函数。即使你的设备不需要特殊电源管理也要写一个例程原样向下传递并在完成后设置 IoStatus 为 STATUS_SUCCESS。我见过不少项目在这上面栽跟头设备在冷启动后立即工作正常但睡眠唤醒后主机直接蓝屏或者设备丢失——这就是 Power IRP 没有正确透传的下场。5.2 现象设备在设备管理器里显示代码 10设备无法启动原因START_DEVICE 处理返回了非成功状态。可能是 MmMapIoSpace 失败通常是 BAR 资源被 BIOS 分配在了 32 位地址空间之外或者 INF 中请求的资源范围超出实际分配的长度、也可能是中断连接失败。但新手最容易忽略的是你的 StartDevice 函数根本没有被 PnP 管理器调用因为 AddDevice 里没有设置设备状态为开始。解决调试器里在 PciDrvStartDevice 入口下断点看有没有命中。没命中说明 AddDevice 有问题或 INF 硬件 ID 不匹配命中了返回值的具体 NTSTATUS 就是线索。0xC0000001 是无效参数、0xC000009A 是资源不足对应着查。另外很多 PCIe 板卡上电默认处于复位态START_DEVICE 时 BAR 空间读回来全是 0xFF。如果驱动在这个状态下做校验比如读版本号寄存器就会报设备未就绪。正确顺序是先做复位释放写控制寄存器或置 PERST 引脚再轮询设备就绪位超时再返回失败。5.3 现象访问 BAR 空间后系统冻屏或蓝屏IRQL_NOT_LESS_OR_EQUAL原因这是 PCI 驱动最经典的蓝屏原因无外乎三种BAR 虚地址已被 MmUnmapIoSpace 释放后仍被访问、读写寄存器的位置超出了映射长度、或者把分页地址当成 BAR 地址在用。还有一种隐蔽场景PCIe 设备处于 D3 电源状态时对 BAR 空间发起的访问会得到全 0xFF 响应某些硬件桥片会把这种访问直接变成 Machine Check Exception表现为冻屏而不是蓝屏。解决代码里杜绝裸指针访问必须走 READ_REGISTER_* 系列。访问之前检查 dx-BarVirtualAddress 非空和偏移不越界。设备挂起后要做一次电源状态恢复置 PERST 的重置序列、或重新完成一次 START_DEVICE 周期再重新映射。这部分的坑在于 WDM 里设备的电源状态由 IRP_MJ_POWER 管理如果你只处理 PnP 不处理电源系统进入 S3 后设备就处于未知状态了。5.4 现象ISR 被调用但中断状态寄存器是 0或中断永远不来原因PCIe 的中断线是 Level 触发的INTx而 Windows 的中断模型期望中断服务例程明确判断中断是否属于本设备。如果设备的中断状态寄存器未置位但 ISR 返回 TRUE系统会认为这个中断已处理实际上别的设备的中断被吞掉了结果就是系统中其他设备随机卡死。反过来如果 ISR 里没读中断状态寄存器就直接返回 FALSE本设备的中断就被认成杂散中断触发次数多了 Windows 会直接禁用中断向量。解决 ISR 的第一条指令就是读取中断状态寄存器并做位检查。必须记住返回 TRUE 前先清中断源。如果设备支持 MSI优先在 FPGA 里配置成 MSI因为 MSI 是边沿触发、发送即知归属省掉这一整类排查问题。注意MSI 在 WDM 资源列表里也是 CmResourceTypeInterrupt但 Vector 不能自己指定——所以要能区分两种方式不要硬编码期望的 Vector。5.5 现象驱动签名校验失败或 INF 安装后设备仍显示未知设备原因64 位系统强制签名而 WDK 默认的测试签名只是让本地内核允许未签名驱动加载INF 安装时针对 .cat 或 .sys 的签名校验依然严格。另一个常见问题是 INF 里的 Hardware ID 字符串写错导致设备管理器里无法匹配。解决先用设备管理器的详细信息→硬件 ID查到真实值比如PCI\VEN_1234DEV_5678SUBSYS_00011234把它原样写进 INF 的[Models]段[Version] Signature$Windows NT$ ClassSystem ClassGuid{4D36E97D-E325-11CE-BFC1-08002BE10318} Provider%ProviderName% CatalogFileWDM_PCI_Driver.cat DriverVer06/28/2024,1.0.0.0 [Manufacturer] %ProviderName%DriverInstall,NTamd64 [DriverInstall.NTamd64] CopyFilesFilesToCopy [FilesToCopy] WDM_PCI_Driver.sys [DriverInstall.NTamd64.Services] AddServiceWDM_PCI_Driver,0x00000002,ServiceInstall [ServiceInstall] DisplayName%ServiceName% ServiceType1 StartType3 ErrorControl1 ServiceBinary%12%\WDM_PCI_Driver.sys [Strings] ProviderNameMyCompany ServiceNameWDM PCI Driver同时确认 INF 文件编码为 UTF-8 无 BOM否则字符串段里的非 ASCII 字符会让驱动安装服务报错。签名方面测试签名只要保证签名证书安全导入目标机、并在目录文件里包含 INF 中列出的全部文件即可。6. 把骨架变成工程验证驱动的加载状态与三个进阶检查习惯驱动编译通过、能安装只是开始。代码写完之后我一般会按下面的清单做一轮验证排查把问题在交付前尽量消化掉。第一步查看驱动加载是否真的成功。设备管理器里确认设备没有感叹号然后打开 C:\Windows\System32\drivers 确认 .sys 文件存在。进一步用内核调试器lm m WDM_PCI_Driver看模块是否加载再用!devnode 0 1查看设备节点状态。这一轮能筛掉 80% 的 INF 和签名问题。第二步验证 BAR 空间访问的有效性。用 IOCTL 读一个已知寄存器比对与寄存器手册预期值的差异。推荐用一个简单的用户态控制台程序循环读写 1000 次每次检查返回值落在合法范围。如果出现个别读取值异常优先怀疑缓存一致性和读写宏使用不规范——而不是硬件坏了。这是 PCIe 驱动最容易自欺欺人的地方一次读写正常不代表驱动是对的FPGA 或设备端缓冲未稳定时偶发错误是常见现象。第三步中断链路验证。把 IRP_MJ_DEVICE_CONTROL 里加一个等待中断事件的 IOCTL用户态调用后阻塞等待 KeSetEvent。然后在硬件侧手动触发一次中断FPGA 调试时往往有测试按钮观察驱动是否在几十毫秒内响应。这个测试是中断链路是否完整的最直接证据。如果没有响应按 5.4 节的排查法看 ISR 有没有被调用、返回值是什么。第四步检查资源释放路径。把设备禁用再启用设备管理器右键禁用/启用循环 20 次观察内存泄漏和设备节点泄漏。WDM 驱动的 REMOVE_DEVICE 处理极容易漏掉 MmUnmapIoSpace 或 IoDisconnectInterrupt而又因为设备仍然存在虚拟机里根本看不出异常。手工做这种热插拔模拟能暴露大量生命周期问题。最后一条个人习惯每次改动寄存器访问相关代码后都做一次全量编译 目标机重启 冷启动验证。PCIe 设备在热启动CtrlAltDel 重启下和冷启动关机再开机下的枚举时序有差异很多驱动问题只在冷启动出现。这是老工程师拿经验换来的教训——一次交付前没有做冷启动验证对方现场一开机设备就丢最后发现是驱动在 START_DEVICE 里等了一个在热启动下早已置位、但冷启动下要晚 200ms 才置位的状态位。从此之后冷启动永远在我的测试清单第一位。希望这篇笔记能把 WDM 写 PCI/PCIe 驱动的全链路讲清楚。从环境搭建到骨架代码从 BAR 访问到中断处理每一步都值得你在自己板卡上做一次最小验证——然后你会发现真正花时间的从来不是写第一版驱动而是你在 5.4 和 5.5 节看到的那些玄学问题它们才是 Windows 驱动开发的经验沉淀所在。本文还有配套的精品资源点击获取 WDM驱动开发实战：从零编写PCIe板卡功能驱动
简介基于WDM模型的PCI驱动开发资料包面向Windows平台底层驱动开发者可系统理解PCI设备与操作系统的交互机制并掌握WDK工具链下PCI/PCIe驱动的编写与调试流程。包内共20个文件以C源码.cpp/.h、工程配置文件.vcxproj/.sln/.dsw及INF安装文件等为主整体仅110KB结构紧凑便于快速对照学习。目前已有331人学习/下载具备切实的参考价值。内容围绕MyDriver与Test两个工程展开覆盖PnP即插即用、电源管理、IRP请求处理、设备与驱动对象链接、PCI配置空间读取等关键概念同时附有驱动测试与检查工程方便进行设备枚举和功能验证。通过阅读源码并结合WDK实践可形成从驱动框架搭建到实际部署的完整路径为后续扩展其他PCI/PCIe设备开发打下扎实基础。1. 从一块识别不到的 PCIe 板卡说起为什么还得啃 WDM 驱动拿到一块 PCIe 接口的采集卡或 FPGA 开发板插上 Windows 主机设备管理器里出现一个带黄色感叹号的未知设备这是绝大多数驱动开发入行的起点。你想要的无非是让它被系统认出来、能读写它的寄存器、能把它的中断和 DMA 用起来。这个目标在 Windows 下有多种实现路径而WDM_PCI_Driver这个标题指向的就是用WDMWindows Driver Model配合WDKWindows Driver Kit手写一个 PCI/PCIe 功能驱动。WDM 是 Windows 2000 时代定下的驱动模型到今天仍然没有过时。原因是 PCI/PCIe 设备的基本交互方式——配置空间、BAR 空间、中断、DMA——三十年来没有本质变化WDM 提供的 IRP 分发、PnP 启动、电源管理这套框架依然是把这些资源正确接进 Windows 的最底层途径。后面出现的 KMDF/WDF 只是把 WDM 的样板代码封装了一层真正要跟硬件打交道的地方你迟早还是得回到 WDM 的语义上来。这篇笔记适合两类人一是刚被分配了 PCIe 驱动任务、手里只有一块板卡和一份寄存器手册的嵌入式工程师二是做过 Linux 下 PCI 驱动、第一次转 Windows 平台的老手。我会把环境搭建、驱动骨架、BAR 访问、中断处理、常见翻车点一路写到底所有代码都基于 WDK 的通用框架你可以直接当模板用。2. WDM、WDF 与 KMDFPCI 驱动在 Windows 下的选型别一上来就写代码2.1 为什么老项目大量停留在 WDM新项目该怎么选WDM 和 WDFWindows Driver Frameworks的关系不是替代而是继承。WDF 里的 KMDF 把 PnP、电源管理、即插即启动这些固定流程封装成回调让驱动开发者不用手动处理 IRP_MJ_PNP 和 IRP_MN_START_DEVICE。好处是代码量少、不容易把状态机写错坏处是封装层在调试某些硬件异常时会变成黑匣子——你想在设备启动序列中间插一步自定义操作得弄清楚框架在哪一环调用你的 EvtDevicePrepareHardware以及失败时返回值怎么传递。WDM 恰恰相反一切从 DriverEntry 开始全部靠你手动注册 Dispatch routines然后按 IRP 的走向一步步走。它在今天仍然大量存在主要因为三类场景存量驱动维护大量工控机、医疗设备、老式采集卡上的驱动是 2005 年前后写的 WDM没人愿意冒风险重写成 KMDF。需要最底层控制KMDF 对某些 PCIe 高级特性比如多 BAR 的资源配置顺序、MSI/MSI-X 的逐个向量控制做了框架层面的默认行为绕开它反而比在它里面做定制更直接。学习价值WDM 把所有机制都摊在明面上读懂 WDM 再去看 KMDF 的封装会有一种原来它替我干了这些的透彻感。我做这类驱动时的选型原则是板卡是自家 FPGA、寄存器手册齐全、生命周期长就用 WDM如果是帮客户包一层简单 PCIe 设备、对方只看交付速度KMDF 更合适。本文按 WDM 为主线展开但避坑章节里也会提 KMDF 的对应注意点。2.2 WDM 驱动处理硬件事件的核心机制IRP 与 PnP 回调在 WDM 的世界里应用程序通过 CreateFile/DeviceIoControl 与驱动通信内核里的一切都是一条条 IRPI/O Request Packet。PCI 驱动最关心的 IRP 类型有IRP 类型对应请求驱动里该做的事IRP_MJ_CREATECreateFile 打开设备增加打开计数可做权限检查IRP_MJ_DEVICE_CONTROLDeviceIoControl 发控制码按 IOCTL 分发读写 BAR、控制中断、启动 DMAIRP_MJ_READ / WRITE应用程序读/写可选很多 PCI 驱动只用 IOCTL 间接访问IRP_MJ_PNP 子码: IRP_MN_START_DEVICE系统分配硬件资源映射 BAR、连接中断、初始化设备IRP_MJ_PNP 子码: IRP_MN_REMOVE_DEVICE设备被拔出/禁用释放中断、解除映射、删除设备对象这套机制对 PCIe 设备的一个重要含义是你的驱动不是一个主动去探测硬件的程序而是被动响应系统 PnP 管理器的调用。系统枚举 PCIe 总线、读设备的 Vendor ID / Device ID、找到匹配的 INF 后加载你的驱动然后按顺序发送 START_DEVICE、给你分配资源。因此 WDM 驱动里没有入口检测硬件这种逻辑——一切从 DriverEntry 注册回调开始硬件在 START_DEVICE 才真正被激活。2.3 一个 WDM PCI 驱动的完整链路DriverEntry 到 START_DEVICE一个最小可工作的 WDM PCI 驱动文件结构通常是这样的WDM_PCI_Driver/ ├── driver.c // DriverEntry、IRP 分发表、设备控制 ├── hw_access.c // BAR 映射、寄存器读写、中断处理 ├── hw_access.h ├── driver.inf // 硬件 ID、驱动安装信息 └── sources / .vcxproj // 构建配置WDK 下用 MSBuild 编译链路的关键节点是 DriverEntry→AddDevice→START_DEVICE。DriverEntry 里你要做的是设置 DriverObject 的各个 MajorFunction、创建设备扩展结构模板、然后调用 IoCreateDevice 创建设备对象。AddDevice 是 PnP 管理器在发现匹配硬件时回调你的地方在这里创建设备对象、建立设备链接符号链接名比如 \Device\PCIeDev0 和 \DosDevices\PCIeDev0。到这一步设备对象存在了但硬件资源还没有分配。真正的资源交接发生在 IRP_MN_START_DEVICE 处理里系统在 Parameters.StartDevice.AllocatedResources 中给出设备的资源列表驱动在这里提取 PhysicalMemory 范围对应 BAR 空间、中断向量/级别然后调用 MmMapIoSpace 把物理地址映射到非分页池中断用 IoConnectInterrupt 挂接。这也是 WDM 与用户态驱动最大的感受差异用户态读写寄存器像访问内存一样简单内核态却要时刻记着我现在在 IRQL 级别多少、这段代码能不能分页、这个操作能不能睡眠。绝大部分蓝屏和驱动开发翻车根源都在这里。3. 搭建 WDK 开发环境版本匹配、目标机配置与常见绕弯路3.1 WDK 与 Visual Studio 版本的配套关系这是新手第一个坑安装 WDK 最忌讳的就是版本随意配。WDK 不是独立编译工具链它依赖 Visual Studio 的 MSBuild 集成。官方版本的配套关系如下Visual Studio 版本对应 WDK 版本支持的 Windows 目标VS 2019 16.xWDK 10.0.19041.x 及以上Windows 10 1809 / Server 2019VS 2022 17.xWDK 10.0.22621.x 及以上Windows 10 2004 / Server 2022VS 2017WDK 10.0.16299.xWindows 10 1709常见翻车是装了 VS 2022 却下载了非常老版本的 WDK安装器直接提示不支持当前的 Visual Studio 版本。我的做法是先确认目标运行环境是 Win10 还是 Win11再按微软官方页面上匹配关系倒推选版本。如果你在 Win11 上做开发、目标机也是 Win11直接选 WDK 10.0.22621 对应的最新版即可。安装完 WDK 后在 VS 里新建项目时选择Empty WDM Driver模板。这里有个值得注意的点WDK 自带模板生成的项目是 KMDF 的WDM 的话选 Empty WDM Driver 才行。项目创建后确认两个配置Target Platform 选 Desktop而不是 Universal驱动类型选 Kernel。这两个地方选错编译出来的 INF 会带有错误装饰导致真机安装时签名校验失败。3.2 目标机、调试机与 WinDbg 的连接配置WDM 驱动开发必须有目标机——本机改驱动、本机测试一旦蓝屏开发环境跟着遭殃而且很多设备在开发机上根本没有物理插槽。标准做法是准备一台独立的调试目标机可以是旧电脑目标机通过网口或串口与开发机相连开发机上用 WinDbg 做内核调试。配置调试机时注意这几步在目标机上以管理员身份执行bcdedit /debug on bcdedit /dbgsettings net hostip:192.168.1.100 port:50000 key:1.2.3.4这里 hostip 是开发机的 IPport 是 WinDbg 监听端口key 是调试会话密钥。目标机重启后开机阶段会等待调试器连接。测试驱动前建议先把目标机系统设置为自动重新启动关闭——否则蓝屏一闪而过你连 Bugcheck 信息都看不到bcdedit /set {current} bootstatuspolicy displayallfailures连接调试会话时开发机 WinDbg 选择 File→Kernel Debug→Net填入目标机 IP 和端口。连接成功后那条命令提示符变成kd你就可以在驱动加载前下断点了。3.3 签名配置与测试签名模式跑通驱动安装的最后一道坎64 位 Windows 要求驱动必须签名开发阶段不想买 EV 证书就打开测试签名模式bcdedit /set testsigning on之后生成的自签名测试证书需要导入目标机的受信任的根证书颁发机构和受信任的发布者存储。这里有个隐蔽的坑WDK 编译驱动时默认生成的是 .cer 证书文件你需要在目标机上右键 CER 文件选择安装证书手工选存储位置为本地计算机→受信任的根证书颁发机构。如果只双击导入到当前用户存储INF 安装时会报错驱动程序无法验证此设备的签名。更彻底的做法是用工具包里的 inf2cat 和 signtool 对驱动包做交叉签名cross-sign先用 makecert 生成测试证书再用 signtool sign 对 .sys 文件签名最后用 inf2cat 生成目录文件并签名。步骤多但一次配好后面每次编译只需要跑一个批处理。我一般把这套签名流程写成一个 build_and_sign.bat放在项目根目录内容大致是echo off set SYS_FILEWDM_PCI_Driver.sys signtool sign /v /s My /n MyTestCert /t http://timestamp.digicert.com /f testcert.pfx %SYS_FILE% inf2cat /driver:. /os:10_X64 signtool sign /v /f testcert.pfx /t http://timestamp.digicert.com WDM_PCI_Driver.cat注意 inf2cat 的/driver:参数必须指向包含 .inf 和 .sys 的目录如果这一行报错Unable to produce catalog多半是 INF 里 Manufacturer 段的 Provider 名与签名机构不一致。这个点我后面避坑章节还会再提。4. 写一个可编译的 WDM PCIe 驱动骨架从 DriverEntry 到 BAR 空间访问4.1 DriverEntry 与设备创建三行关键代码背后的必要逻辑先给一个最简 DriverEntry它在整个 PCI 驱动生命周期里只做一次NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath) { NTSTATUS status; UNICODE_STRING deviceName; UNICODE_STRING symLinkName; PDEVICE_OBJECT deviceObject NULL; // 注册派发例程未注册的 MajorFunction 会被系统默认处理为 STATUS_INVALID_DEVICE_REQUEST DriverObject-MajorFunction[IRP_MJ_CREATE] PciDrvCreateClose; DriverObject-MajorFunction[IRP_MJ_CLOSE] PciDrvCreateClose; DriverObject-MajorFunction[IRP_MJ_DEVICE_CONTROL] PciDrvDeviceControl; DriverObject-MajorFunction[IRP_MJ_PNP] PciDrvPnP; DriverObject-DriverUnload PciDrvUnload; // 创建设备对象 RtlInitUnicodeString(deviceName, L\\Device\\PciDev0); status IoCreateDevice(DriverObject, sizeof(DEVICE_EXTENSION), deviceName, FILE_DEVICE_UNKNOWN, FILE_DEVICE_SECURE_OPEN, FALSE, deviceObject); if (!NT_SUCCESS(status)) { return status; } // 创建符号链接让 Win32 应用可以通过 CreateFile 打开设备 RtlInitUnicodeString(symLinkName, L\\DosDevices\\PciDev0); status IoCreateSymbolicLink(symLinkName, deviceName); if (!NT_SUCCESS(status)) { IoDeleteDevice(deviceObject); return status; } // 设备扩展清零并初始化 PDEVICE_EXTENSION dx (PDEVICE_EXTENSION)deviceObject-DeviceExtension; memset(dx, 0, sizeof(DEVICE_EXTENSION)); dx-DeviceObject deviceObject; return STATUS_SUCCESS; }代码逻辑上最关键的一点是设备扩展Device Extension的设计。这个结构体是你的驱动在设备生命周期内的记事本——BAR 映射后的虚拟地址、中断对象指针、设备状态标志都存在这里。每次 IRP 到达时你通过 IoGetCurrentIrpStackLocation 拿到 IRP 栈的位置再通过 DeviceObject-DeviceExtension 取回这些数据。设备扩展的设计直接决定了驱动在多设备实例下能否正常工作因此从 DriverEntry 起就应该规划好它的字段。IoCreateDevice 的 FILE_DEVICE_SECURE_OPEN 标志建议加上否则任何进程只要知道符号链接名就能打开设备这对工业设备来说等于裸奔。从安全角度WDM 里没有现成的权限控制机制需要你在 IRP_MJ_CREATE 里自己检查进程状态或使用访问控制列表但至少加上这个标志能让系统默认拦掉大部分非法访问。4.2 START_DEVICE把 BAR 空间变成可访问的内存设备对象创建完毕等 PnP 管理器把资源分配好再真正初始化硬件。标准写法是在 IRP_MJ_PNP 处理函数里分派子码NTSTATUS PciDrvPnP(PDEVICE_OBJECT deviceObject, PIRP irp) { PIO_STACK_LOCATION irpStack IoGetCurrentIrpStackLocation(irp); PDEVICE_EXTENSION dx (PDEVICE_EXTENSION)deviceObject-DeviceExtension; switch (irpStack-MinorFunction) { case IRP_MN_START_DEVICE: return PciDrvStartDevice(dx, irp); case IRP_MN_REMOVE_DEVICE: if (dx-InterruptObject) { IoDisconnectInterrupt(dx-InterruptObject); dx-InterruptObject NULL; } if (dx-BarVirtualAddress) { MmUnmapIoSpace(dx-BarVirtualAddress, dx-BarLength); dx-BarVirtualAddress NULL; } return PciDrvFinishRemoveDevice(dx, irp); default: IoSkipCurrentIrpStackLocation(irp); return IoCallDriver(dx-LowerDeviceObject, irp); // 下层设备对象在 AddDevice 时挂接 } }START_DEVICE 的具体处理里资源提取是关键NTSTATUS PciDrvStartDevice(PDEVICE_EXTENSION dx, PIRP irp) { PCM_PARTIAL_RESOURCE_LIST resourceList; ULONG i; PHYSICAL_ADDRESS barPhys; ULONG barLength; resourceList irp-Parameters.StartDevice.AllocatedResources-List[0].PartialResourceList; for (i 0; i resourceList-Count; i) { PCM_PARTIAL_RESOURCE_DESCRIPTOR desc resourceList-PartialDescriptors[i]; if (desc-Type CmResourceTypeMemory) { // 取 BAR0 对应的物理地址和长度 barPhys desc-u.Memory.Start; barLength desc-u.Memory.Length; dx-BarPhysicalAddress barPhys; dx-BarLength barLength; // 把物理地址映射到内核虚拟地址之后才能直接读写 dx-BarVirtualAddress MmMapIoSpace(barPhys, barLength, MmNonCached); if (!dx-BarVirtualAddress) { return STATUS_INSUFFICIENT_RESOURCES; } // 清掉 BAR 空间里的遗留状态防止设备在上电假死状态 WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress 0x00), 0xFFFFFFFF); KdPrint((PCI: BAR0 mapped at %p, len %lu\n, dx-BarVirtualAddress, barLength)); break; } } if (resourceList-Count) { // 挂接中断——注意PCIe MSI/MSI-X 在 WDM 里也是用 CmResourceTypeInterrupt 上报 for (i 0; i resourceList-Count; i) { PCM_PARTIAL_RESOURCE_DESCRIPTOR desc resourceList-PartialDescriptors[i]; if (desc-Type CmResourceTypeInterrupt) { IoConnectInterrupt(dx-InterruptObject, PciDrvIsr, // 中断服务例程 dx, // 传给 ISR 的上下文 NULL, desc-u.Interrupt.Vector, desc-u.Interrupt.Level, desc-u.Interrupt.Affinity); KdPrint((PCI: Interrupt connected vector%lu\n, desc-u.Interrupt.Vector)); break; } } } IoCompleteRequest(irp, IO_NO_INCREMENT); return STATUS_SUCCESS; }这里有一点必须说清楚BAR 空间映射用 MmMapIoSpace 时缓存属性必须指定为 MmNonCached。PCIe 设备的寄存器映射到 CPU 地址空间后如果 CPU 的缓存策略把它当普通内存读同一个寄存器可能得到旧值——因为硬件端改变了数据但 CPU 缓存还没失效。这个玄学问题一旦出现表现就是死循环读状态寄存器永远等不到设备就绪。另一个选择是 MmMapIoSpace 的变种 MmMapIoSpaceEx 可以指定更多属性但默认场景 MmNonCached 就是对的。WRITE_REGISTER_ULONG 这类宏的本质是 _declspec(noinline) 的内联函数它保证编译器和 CPU 都不会对这个 volatile 地址的访问做重排。访问 PCIe 设备寄存器时永远不要用直接解引用指针的方式除非你明确知道自己在做什么并加了 volatile 强制但即便如此用 WRITE_REGISTER* 系列才是 WDK 推荐做法。4.3 设备控制IOCTL让用户态程序安全地读写你的寄存器驱动写完用户态程序要能访问。通常做法是定义一组 IOCTL把读某个偏移的寄存器、写某个偏移的寄存器、获取设备状态这些操作暴露出去#define IOCTL_PCI_READ_REG CTL_CODE(FILE_DEVICE_UNKNOWN, 0x800, METHOD_BUFFERED, FILE_ANY_ACCESS) #define IOCTL_PCI_WRITE_REG CTL_CODE(FILE_DEVICE_UNKNOWN, 0x801, METHOD_BUFFERED, FILE_ANY_ACCESS) NTSTATUS PciDrvDeviceControl(PDEVICE_OBJECT deviceObject, PIRP irp) { PIO_STACK_LOCATION irpStack IoGetCurrentIrpStackLocation(irp); PDEVICE_EXTENSION dx (PDEVICE_EXTENSION)deviceObject-DeviceExtension; ULONG ioctlCode irpStack-Parameters.DeviceIoControl.IoControlCode; PVOID systemBuffer irp-AssociatedIrp.SystemBuffer; ULONG inputLen irpStack-Parameters.DeviceIoControl.InputBufferLength; ULONG outputLen irpStack-Parameters.DeviceIoControl.OutputBufferLength; NTSTATUS status STATUS_SUCCESS; ULONG bytesReturned 0; switch (ioctlCode) { case IOCTL_PCI_READ_REG: { if (inputLen sizeof(PCI_REG_ACCESS) || outputLen sizeof(ULONG)) { status STATUS_BUFFER_TOO_SMALL; break; } PCI_REG_ACCESS *access (PCI_REG_ACCESS *)systemBuffer; if (access-Offset sizeof(ULONG) dx-BarLength) { status STATUS_INVALID_PARAMETER; break; } *(PULONG)systemBuffer READ_REGISTER_ULONG( (PULONG)((PUCHAR)dx-BarVirtualAddress access-Offset)); bytesReturned sizeof(ULONG); break; } case IOCTL_PCI_WRITE_REG: { if (inputLen sizeof(PCI_REG_ACCESS)) { status STATUS_BUFFER_TOO_SMALL; break; } PCI_REG_ACCESS *access (PCI_REG_ACCESS *)systemBuffer; if (access-Offset sizeof(ULONG) dx-BarLength) { status STATUS_INVALID_PARAMETER; break; } WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress access-Offset), access-Value); bytesReturned sizeof(PCI_REG_ACCESS); break; } default: status STATUS_INVALID_DEVICE_REQUEST; break; } irp-IoStatus.Status status; irp-IoStatus.Information bytesReturned; IoCompleteRequest(irp, IO_NO_INCREMENT); return status; }参数说明里IOCTL 的 METHOD_BUFFERED 方式对小型寄存器访问是够用的它把输入输出都放在系统缓冲区里内核帮你处理好用户态/内核态内存拷贝。缺点是每次 IOCTL 调用都会有一次系统缓冲区分配如果采集场景要求高频率读寄存器比如每毫秒读取一次状态位效率会不够。高频场景应该改用 METHOD_IN_DIRECT 或 METHOD_OUT_DIRECT配合用户态 MDL 做直接 IO但线程同步和缓冲区生命周期管理就没这么省心。这里没有加任何锁。如果你的设备控制函数会被多线程并发调用必须用自旋锁或者互斥锁保护对寄存器序列的访问。否则两个线程交错写一个多字节的寄存器组设备可能收到一个中间状态。驱动里的竞争条件不一定会立刻蓝屏但表现往往是偶发性设备不响应——这种问题最难排查全靠锁提前防住。4.4 中断与 DPC为什么 ISR 里绝对不能直接做耗时操作WDM 的中断处理分两部分ISRInterrupt Service Routine在 DIRQL 执行必须极短剩下的工作在 DPCDeferred Procedure Call里完成。ISR 只做两件事——判断中断是否来自你的设备、如果是否认则返回 FALSE 让系统继续分发如果是则清除中断源写入中断状态寄存器并调度 DPCBOOLEAN PciDrvIsr(PKINTERRUPT InterruptObject, PVOID Context) { PDEVICE_EXTENSION dx (PDEVICE_EXTENSION)Context; ULONG status READ_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress INT_STATUS_REG)); if (!(status INT_STATUS_VALID)) { return FALSE; // 不是本设备中断 } // 立刻清中断源避免同一中断反复触发 WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress INT_STATUS_REG), status); // 调度 DPC 做后续工作 KeInsertQueueDpc(dx-InterruptDpc, NULL, NULL); return TRUE; }DPC 例程里可以做需要加锁的、稍重的操作比如读取一大块 FIFO 数据、更新计数器、向用户态应用发通知事件VOID PciDrvDpc(KDPC *Dpc, PVOID Context, PVOID SystemArgument1, PVOID SystemArgument2) { PDEVICE_EXTENSION dx (PDEVICE_EXTENSION)Context; // 从 FIFO 搬数据 ULONG count READ_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress FIFO_COUNT_REG)); while (count 0) { dx-FifoData[dx-FifoIndex] READ_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress FIFO_DATA_REG)); count--; } if (dx-FifoIndex FIFO_THRESHOLD) { KeSetEvent(dx-DataReadyEvent, IO_NO_INCREMENT, FALSE); } }强调一点ISR 里如果执行超过几十微秒会拖累整个系统的中断响应甚至导致其他设备的中断超时。像读取 PCIe 设备 FIFO 这种事原则上也可以全部放 DPCISR 只做中断仲裁。另外如果设备支持 MSI/MSI-XWDM 层不需要区分——资源列表里报什么你就连什么ISR 签名一样。4.5 DMA 传输的最小实现缓冲区锁页与地址映射PCIe 驱动的高吞吐场景绕不开 DMA。WDM 下最简单的方式是让用户态程序提供一个缓冲区驱动用 MmProbeAndLockPages 锁页后把物理地址给设备做 DMA 传输// 假设 METHOD_OUT_DIRECTirp-MdlAddress 指向用户缓冲区 NTSTATUS PciDrvStartDma(PDEVICE_EXTENSION dx, PIRP irp) { PMDL mdl irp-MdlAddress; if (!mdl) { return STATUS_INVALID_PARAMETER; } // 锁页防止用户缓冲被换出物理内存 __try { MmProbeAndLockPages(mdl, UserMode, IoReadAccess); } __except (EXCEPTION_EXECUTE_HANDLER) { return STATUS_INVALID_USER_BUFFER; } PHYSICAL_ADDRESS pa MmGetMdlPhysicalAddress(mdl); ULONG len MmGetMdlByteCount(mdl); // 通知设备 DMA 目标地址和长度 WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress DMA_ADDR_LO_REG), (ULONG)pa.QuadPart); WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress DMA_ADDR_HI_REG), (ULONG)(pa.QuadPart 32)); WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress DMA_LEN_REG), len); WRITE_REGISTER_ULONG((PULONG)((PUCHAR)dx-BarVirtualAddress DMA_GO_REG), 1); return STATUS_PENDING; }注意DMA 的方向如果是从设备到内存用户缓冲区的缓存属性必须一致。MmProbeAndLockPages 锁住的页面可能仍带 CPU 缓存导致设备写内存后 CPU 读出来是旧数据。解决方法是让设备侧关闭 FIFO 的 snoop或者改用 MmAllocateContiguousMemory 分配一致性内存做中转。工业级的做法是单独开一个环形缓冲区用生产者-消费者指针管理避免 DMA 完成后还有缓存同步的开销。DMA 完成的中断响应就是 4.4 里的 ISRDPC 流程的延伸ISR 处理传输完成中断DPC 里检查 DMA 状态寄存器、解锁页面、完成挂起的 IRP然后用户态被唤醒。这个完整闭环是 PCIe 驱动性能的核心一步做错就是数据错误或者驱动挂死。5. WDM PCIe 驱动开发的避坑指南现象、原因、解决5.1 现象编译报错 STATUS_INVALID_DEVICE_REQUEST或 IRP 无法下发到驱动原因最常见的原因是 DriverEntry 里没有注册 IRP_MJ_PNP或注册了但 Inc 函数没有正确导出。很多人会漏掉DriverObject-MajorFunction[IRP_MJ_POWER]系统在设备启动序列里发电源 IRP 时得不到响应默认按失败处理导致设备启动中断。电源 IRP 也是 WDM 驱动被忽视的大头特别在从休眠恢复时最容易翻车。解决DriverEntry 里把 PnP 和 Power 都显式注册单独处理函数。即使你的设备不需要特殊电源管理也要写一个例程原样向下传递并在完成后设置 IoStatus 为 STATUS_SUCCESS。我见过不少项目在这上面栽跟头设备在冷启动后立即工作正常但睡眠唤醒后主机直接蓝屏或者设备丢失——这就是 Power IRP 没有正确透传的下场。5.2 现象设备在设备管理器里显示代码 10设备无法启动原因START_DEVICE 处理返回了非成功状态。可能是 MmMapIoSpace 失败通常是 BAR 资源被 BIOS 分配在了 32 位地址空间之外或者 INF 中请求的资源范围超出实际分配的长度、也可能是中断连接失败。但新手最容易忽略的是你的 StartDevice 函数根本没有被 PnP 管理器调用因为 AddDevice 里没有设置设备状态为开始。解决调试器里在 PciDrvStartDevice 入口下断点看有没有命中。没命中说明 AddDevice 有问题或 INF 硬件 ID 不匹配命中了返回值的具体 NTSTATUS 就是线索。0xC0000001 是无效参数、0xC000009A 是资源不足对应着查。另外很多 PCIe 板卡上电默认处于复位态START_DEVICE 时 BAR 空间读回来全是 0xFF。如果驱动在这个状态下做校验比如读版本号寄存器就会报设备未就绪。正确顺序是先做复位释放写控制寄存器或置 PERST 引脚再轮询设备就绪位超时再返回失败。5.3 现象访问 BAR 空间后系统冻屏或蓝屏IRQL_NOT_LESS_OR_EQUAL原因这是 PCI 驱动最经典的蓝屏原因无外乎三种BAR 虚地址已被 MmUnmapIoSpace 释放后仍被访问、读写寄存器的位置超出了映射长度、或者把分页地址当成 BAR 地址在用。还有一种隐蔽场景PCIe 设备处于 D3 电源状态时对 BAR 空间发起的访问会得到全 0xFF 响应某些硬件桥片会把这种访问直接变成 Machine Check Exception表现为冻屏而不是蓝屏。解决代码里杜绝裸指针访问必须走 READ_REGISTER_* 系列。访问之前检查 dx-BarVirtualAddress 非空和偏移不越界。设备挂起后要做一次电源状态恢复置 PERST 的重置序列、或重新完成一次 START_DEVICE 周期再重新映射。这部分的坑在于 WDM 里设备的电源状态由 IRP_MJ_POWER 管理如果你只处理 PnP 不处理电源系统进入 S3 后设备就处于未知状态了。5.4 现象ISR 被调用但中断状态寄存器是 0或中断永远不来原因PCIe 的中断线是 Level 触发的INTx而 Windows 的中断模型期望中断服务例程明确判断中断是否属于本设备。如果设备的中断状态寄存器未置位但 ISR 返回 TRUE系统会认为这个中断已处理实际上别的设备的中断被吞掉了结果就是系统中其他设备随机卡死。反过来如果 ISR 里没读中断状态寄存器就直接返回 FALSE本设备的中断就被认成杂散中断触发次数多了 Windows 会直接禁用中断向量。解决 ISR 的第一条指令就是读取中断状态寄存器并做位检查。必须记住返回 TRUE 前先清中断源。如果设备支持 MSI优先在 FPGA 里配置成 MSI因为 MSI 是边沿触发、发送即知归属省掉这一整类排查问题。注意MSI 在 WDM 资源列表里也是 CmResourceTypeInterrupt但 Vector 不能自己指定——所以要能区分两种方式不要硬编码期望的 Vector。5.5 现象驱动签名校验失败或 INF 安装后设备仍显示未知设备原因64 位系统强制签名而 WDK 默认的测试签名只是让本地内核允许未签名驱动加载INF 安装时针对 .cat 或 .sys 的签名校验依然严格。另一个常见问题是 INF 里的 Hardware ID 字符串写错导致设备管理器里无法匹配。解决先用设备管理器的详细信息→硬件 ID查到真实值比如PCI\VEN_1234DEV_5678SUBSYS_00011234把它原样写进 INF 的[Models]段[Version] Signature$Windows NT$ ClassSystem ClassGuid{4D36E97D-E325-11CE-BFC1-08002BE10318} Provider%ProviderName% CatalogFileWDM_PCI_Driver.cat DriverVer06/28/2024,1.0.0.0 [Manufacturer] %ProviderName%DriverInstall,NTamd64 [DriverInstall.NTamd64] CopyFilesFilesToCopy [FilesToCopy] WDM_PCI_Driver.sys [DriverInstall.NTamd64.Services] AddServiceWDM_PCI_Driver,0x00000002,ServiceInstall [ServiceInstall] DisplayName%ServiceName% ServiceType1 StartType3 ErrorControl1 ServiceBinary%12%\WDM_PCI_Driver.sys [Strings] ProviderNameMyCompany ServiceNameWDM PCI Driver同时确认 INF 文件编码为 UTF-8 无 BOM否则字符串段里的非 ASCII 字符会让驱动安装服务报错。签名方面测试签名只要保证签名证书安全导入目标机、并在目录文件里包含 INF 中列出的全部文件即可。6. 把骨架变成工程验证驱动的加载状态与三个进阶检查习惯驱动编译通过、能安装只是开始。代码写完之后我一般会按下面的清单做一轮验证排查把问题在交付前尽量消化掉。第一步查看驱动加载是否真的成功。设备管理器里确认设备没有感叹号然后打开 C:\Windows\System32\drivers 确认 .sys 文件存在。进一步用内核调试器lm m WDM_PCI_Driver看模块是否加载再用!devnode 0 1查看设备节点状态。这一轮能筛掉 80% 的 INF 和签名问题。第二步验证 BAR 空间访问的有效性。用 IOCTL 读一个已知寄存器比对与寄存器手册预期值的差异。推荐用一个简单的用户态控制台程序循环读写 1000 次每次检查返回值落在合法范围。如果出现个别读取值异常优先怀疑缓存一致性和读写宏使用不规范——而不是硬件坏了。这是 PCIe 驱动最容易自欺欺人的地方一次读写正常不代表驱动是对的FPGA 或设备端缓冲未稳定时偶发错误是常见现象。第三步中断链路验证。把 IRP_MJ_DEVICE_CONTROL 里加一个等待中断事件的 IOCTL用户态调用后阻塞等待 KeSetEvent。然后在硬件侧手动触发一次中断FPGA 调试时往往有测试按钮观察驱动是否在几十毫秒内响应。这个测试是中断链路是否完整的最直接证据。如果没有响应按 5.4 节的排查法看 ISR 有没有被调用、返回值是什么。第四步检查资源释放路径。把设备禁用再启用设备管理器右键禁用/启用循环 20 次观察内存泄漏和设备节点泄漏。WDM 驱动的 REMOVE_DEVICE 处理极容易漏掉 MmUnmapIoSpace 或 IoDisconnectInterrupt而又因为设备仍然存在虚拟机里根本看不出异常。手工做这种热插拔模拟能暴露大量生命周期问题。最后一条个人习惯每次改动寄存器访问相关代码后都做一次全量编译 目标机重启 冷启动验证。PCIe 设备在热启动CtrlAltDel 重启下和冷启动关机再开机下的枚举时序有差异很多驱动问题只在冷启动出现。这是老工程师拿经验换来的教训——一次交付前没有做冷启动验证对方现场一开机设备就丢最后发现是驱动在 START_DEVICE 里等了一个在热启动下早已置位、但冷启动下要晚 200ms 才置位的状态位。从此之后冷启动永远在我的测试清单第一位。希望这篇笔记能把 WDM 写 PCI/PCIe 驱动的全链路讲清楚。从环境搭建到骨架代码从 BAR 访问到中断处理每一步都值得你在自己板卡上做一次最小验证——然后你会发现真正花时间的从来不是写第一版驱动而是你在 5.4 和 5.5 节看到的那些玄学问题它们才是 Windows 驱动开发的经验沉淀所在。本文还有配套的精品资源点击获取