简介：面向 Windows 底层驱动开发者的 PCI/PCIe 驱动资料包，基于 WDM 模型梳理 PCI 设备驱动的核心开发路径，从 PnP 枚举、电源管理、IRP 请求处理到配置空间访问均有涉及，适合用它补齐从零编写驱动所需的关键认知。压缩包共 20 个文件、约 110KB，以 h/cpp 源码、vcxproj 工程、inf 安装脚本和 sln 解决方案为主，目录按驱动示例与测试程序分开展示，方便对照工程结构逐项编译与调试。内容以 HelloWDM 示例驱动为线索，详细呈现驱动对象与设备对象的建立、中断及内存资源映射、PDO/FDO 的层次关系、设备枚举探测等 WDM 核心概念；同时覆盖 IRP 分发、电源管理中的挂起恢复策略，能够帮助开发者理解 PCIe 设备在 Windows 下如何被识别、配置和接管，并迁移到其他 PCI/PCIe 设备驱动开发中。已有 331 人学习下载，适合有一定 C 语言基础、希望深入底层硬件开发的驱动工程师。

1. 为什么说 WDM 是 PCI/PCIe 驱动开发的必修课：这套示例工程的含金量

在 Windows 上做 PCI/PCIe 驱动开发，WDM 是一个绕不开的起点。WDM（Windows Driver Model）定义了驱动与 PnP、电源、I/O 管理器交互的基本框架，WDK 则是你把它变成可加载内核模块的整套工具链。这套WDM_PCI_Driver.zip最难得的地方，是它把驱动端工程（HelloWDM）和用户态测试工程（Test）打包在了同一个解决方案里——这正好回答了新手最容易卡住的问题：驱动写完，怎么证明它活着？如果你是刚接触 PCI 驱动的开发者，或者手头正好有一块 PCIe 板卡需要写功能驱动，这套包可以直接当脚手架用；对熟手来说，它是一个结构干净的 WDM 参考骨架，拿来对照自己的代码分层也没问题。

2. 工程骨架与源码解读：HelloWDM 与 Test 的分工逻辑

2.1 文件清单：每个文件在驱动工程里的真实角色

先看整体。压缩包打开后是DriverDev.sln解决方案文件，下面挂两个工程：WDM_Driver（驱动端）和Test（用户态验证端）。我把文件按角色拆成一张表，对照着看就不会迷路。

拆包时有个细节值得注意：.dsp和.vcxproj同时存在，说明这套代码是从 VC6/DDK 时代一路迁移到现代 WDK 的。这意味着它保留了最朴素的 WDM 写法，反而比那些堆满宏封装的新代码更容易读懂。你不需要关心其余几个.user/.filters文件，它们只是 VS 的界面配置，不影响编译结果。

2.2 HelloWDM 驱动端：DriverEntry 与 AddDevice 的基本骨架

驱动端的核心逻辑集中在HelloWDM.cpp。虽然这套包里没有给出 HelloWDM 的完整源码，但从文件构成（Ioctls.h、guid.h、HelloWDM.inf）可以确认：这是一个标准 WDM 功能驱动，典型实现会像我下面写出来的这样。DriverEntry 是内核加载驱动的第一站，职责非常明确：设置分发例程、注册 AddDevice、提供卸载例程。

extern "C" NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath) { NTSTATUS status = STATUS_SUCCESS; // 卸载例程：驱动被移除时回收资源 DriverObject->DriverUnload = HelloWDMSampleUnload; // 分发例程：决定这个驱动能响应哪些 IRP DriverObject->MajorFunction[IRP_MJ_CREATE] = HelloWDMCreate; DriverObject->MajorFunction[IRP_MJ_CLOSE] = HelloWDMClose; DriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] = HelloWDMDeviceControl; DriverObject->MajorFunction[IRP_MJ_PNP] = HelloWDMPnp; // AddDevice：PnP 管理器为每个设备实例调用它 DriverObject->DriverExtension->AddDevice = HelloWDMAddDevice; return status; }

这段代码的逻辑是：把 IRP 的分发处理函数挂到驱动对象上。IRP_MJ_CREATE对应 CreateFile，IRP_MJ_CLOSE对应 CloseHandle，IRP_MJ_DEVICE_CONTROL对应 DeviceIoControl。如果你连MajorFunction[IRP_MJ_DEVICE_CONTROL]都没设置，用户态发控制码就会直接得到 STATUS_INVALID_DEVICE_REQUEST，这是新手最容易翻车的地方之一。

AddDevice 例程是 WDM 的生命线。PnP 管理器检测到设备后，会先由总线驱动创建 PDO，再调用功能驱动的 AddDevice 创建设备对象（FDO）并把它挂到设备栈上：

NTSTATUS HelloWDMAddDevice(PDRIVER_OBJECT DriverObject, PDEVICE_OBJECT pdo) { PDEVICE_OBJECT fdo = NULL; NTSTATUS status = IoCreateDevice( DriverObject, sizeof(DEVICE_EXTENSION), // 设备扩展：保存设备状态与资源 &helloWDMBuffer, // 设备名称，如 \Device\HelloWDM FILE_DEVICE_UNKNOWN, // 设备类型：PCI 设备常用 UNKNOWN 0, FALSE, // 非独占 &fdo); if (!NT_SUCCESS(status)) { return status; } // 创建设备后紧接着创建符号链接，用户态才能用 \\.\HelloWDM 打开 IoCreateSymbolicLink(&helloWDMSymbolicLinkName, &helloWDMBuffer); // 把 PDO 指针和设备扩展关联，后面处理 PnP 事件要用 DEVICE_EXTENSION *pDevExt = (DEVICE_EXTENSION*)fdo->DeviceExtension; pDevExt->pdo = pdo; return STATUS_SUCCESS; }

这里最关键的两个参数是sizeof(DEVICE_EXTENSION)和FILE_DEVICE_UNKNOWN。设备扩展是驱动私有的数据结构，大小由你自己定，常见做法是往里面放自旋锁、中断对象指针、BAR 映射地址；FILE_DEVICE_UNKNOWN则是告诉 I/O 管理器这是一个未分类的设备，PCI 这类自定义硬件基本都这么选。IoCreateDevice 成功后，必须做符号链接，否则用户态找不到设备——这个动作和guid.h里定义的 GUID 配合，构成设备在系统里的对外身份。

2.3 Test 用户态程序：CreateFile 与 DeviceIoControl 的调用链

Test 工程是整个包的验证入口。它的 main.cpp 做三件事：打开设备、发控制码、打印结果。按这套包的设计意图，典型流程是：

#include <windows.h> #include <stdio.h> #include "..\WDM_Driver\Ioctls.h" int main() { // 打开设备：符号链接名在用户态表现为 \\.\HelloWDM HANDLE hDevice = CreateFile(L"\\\\.\\HelloWDM", GENERIC_READ | GENERIC_WRITE, 0, NULL, OPEN_EXISTING, 0, NULL); if (hDevice == INVALID_HANDLE_VALUE) { printf("Open failed, error = %d\n", GetLastError()); return 1; } DWORD bytesReturned = 0; // 发起自定义控制码，让驱动执行一次寄存器读取操作 BOOL ok = DeviceIoControl(hDevice, IOCTL_HELLOWDM_READ_REGISTER, NULL, 0, &regValue, sizeof(regValue), &bytesReturned, NULL); if (ok) { printf("Driver answered, value = 0x%x\n", regValue); } else { printf("IOCTL failed, error = %d\n", GetLastError()); } CloseHandle(hDevice); return 0; }

注意CreateFile的第一个参数：在驱动里创建符号链接时写的是\DosDevices\HelloWDM，到了用户态就变成\\.\HelloWDM。如果驱动端只创建设备名、忘记创建符号链接，这里会返回 ERROR_FILE_NOT_FOUND。DeviceIoControl的倒数第二个参数&bytesReturned用来接收驱动返回的输出字节数，这在 METHOD_BUFFERED 模式下能帮你判断驱动是否正确填入了输出缓冲。整个 Test 工程的价值在于：它是你验证驱动存活的探针，先跑通它再去翻 PCIe 协议栈，能省掉大量猜测时间。

3. WDM 的核心机制：PnP、IRP、电源管理与 PCIe 配置空间读取

3.1 IRP 分发与 I/O 路径：数据如何穿过设备栈

WDM 里没有直接的函数调用，所有 I/O 操作都被封装成 IRP（I/O Request Packet）。用户态的 ReadFile、WriteFile、DeviceIoControl 最终都会变成内核里的 IRP，从设备栈顶往下走，被各层的分发例程处理。

在 HelloWDM 这种最简单的功能驱动里，你只需要处理自己关心的 IRP，其余 IRP_MJ_PNP、IRP_MJ_POWER 之类的可以回调系统默认处理。但IRP_MJ_DEVICE_CONTROL必须自己处理，因为设备控制码只有驱动自己认识。处理完 IRP 后，要把IoStatus.Status和IoStatus.Information填好，再调用IoCompleteRequest结束这一次 I/O。

NTSTATUS HelloWDMDeviceControl(PDEVICE_OBJECT fdo, PIRP Irp) { PIO_STACK_LOCATION irpSp = IoGetCurrentIrpStackLocation(Irp); ULONG ioctlCode = irpSp->Parameters.DeviceIoControl.IoControlCode; // 按控制码分派 switch (ioctlCode) { case IOCTL_HELLOWDM_READ_REGISTER: // 从输出缓冲取地址，读取寄存器值 break; default: Irp->IoStatus.Status = STATUS_INVALID_DEVICE_REQUEST; Irp->IoStatus.Information = 0; IoCompleteRequest(Irp, IO_NO_INCREMENT); return STATUS_INVALID_DEVICE_REQUEST; } Irp->IoStatus.Status = STATUS_SUCCESS; Irp->IoStatus.Information = sizeof(ULONG); IoCompleteRequest(Irp, IO_NO_INCREMENT); return STATUS_SUCCESS; }

IoGetCurrentIrpStackLocation返回的是本次 IRP 在设备栈中当前层的参数区，控制码和输入输出缓冲区长度都从这里取。IoStatus.Information在 IOCTL 里表示实际传回用户态的字节数，用户态DeviceIoControl的&bytesReturned就是它。这套代码看起来简单，但它是所有 PCI/PCIe 功能驱动里最核心的一段：寄存器读写、中断控制、DMA 启动全部从这个 switch 入口分流出去。

3.2 PnP 与 PDO/FDO：设备栈如何搭起来

WDM 的 PnP 模型可以拆成三句话理解：总线驱动枚举硬件时创建 PDO，功能驱动在 AddDevice 里创建 FDO，两者上下叠起来就构成设备栈。包里的摘要反复强调 PDO 和 FDO，因为这两个对象决定了你的驱动在哪个层级干活。

PCIe 设备插上后，PCI 总线驱动会读它的配置空间，确认 Vendor ID 和 Device ID，找到匹配的 .inf 后加载对应功能驱动，调用AddDevice。所以AddDevice里拿到的pdo就是总线驱动创建的物理设备对象，你的 FDO 要挂在它上面。设备栈看起来是这样的：

Filter DO（可选） FDO（你的功能驱动创建） PDO（PCI 总线驱动创建）

设备栈搭好后，所有发给这个设备的 IRP 从栈顶往下传。这就是为什么你的分发例程能收到 IRP：它挂在栈中间某层。驱动里拿到IRP_MN_START_DEVICE时，系统会把分配好的资源（BAR 地址、中断向量）通过IoGetDeviceProperty或资源列表传给你，这一步是 PCI 驱动真正接触硬件的起点。PCIe 热插拔场景下，设备拔出会触发IRP_MN_SURPRISE_REMOVAL，WDM 驱动如果没处理它而继续访问硬件地址，轻则蓝屏重则卡死系统，这一点在后面避坑章会细说。

3.3 PCIe 配置空间：Vendor ID、Device ID 与 BAR 的读取方式

PCIe 枚举过程和传统 PCI 一脉相承：系统上电后，PCI 总线驱动从总线 0 开始逐条扫描，访问每个设备的配置空间。配置空间是每个 PCIe 设备都有的 256 字节结构，开头的 Vendor ID、Device ID 决定了系统该加载哪个驱动。你写驱动时，同样要面对配置空间——至少要读到 BAR 寄存器，才能拿到设备的 MMIO 基地址。

WDM 里访问配置空间的常见做法是给父总线驱动发 IRP 而不是直接 in/out。代码层面，通过IRP_MJ_PNP+IRP_MN_READ_CONFIG交给 PCI 总线驱动处理，它会代为访问配置空间并返回数据。用这套包的 Test 工程反向验证时，建议先读一次配置空间头部的 Vendor ID 和 Device ID，确认驱动和设备真的「握手」成功了。

配置空间里和你最相关的几个偏移量：0x00是 Vendor ID，0x02是 Device ID，0x10到0x24是 6 个 BAR 寄存器。其中 BAR0 通常映射设备的主要寄存器区域，驱动拿到 BAR0 的物理地址后，用MmMapIoSpace映射成内核虚拟地址，之后就能用READ_REGISTER_ULONG和WRITE_REGISTER_ULONG读写设备寄存器了。很多人把配置空间读取和寄存器访问混为一谈，实际上前者是枚举和识别设备用的，后者才是设备真正开始工作后的日常操作。

3.4 电源管理：设备挂起与恢复

WDM 的电源管理对 PCI 驱动来说往往是「不处理就出问题」。Windows 在系统休眠或设备空闲时，会向设备栈下发IRP_MJ_POWER。如果你的驱动在处理 IRP 时直接返回 STATUS_SUCCESS 而不调用PoStartNextPowerIrp，整个设备的电源状态可能一直停留在 D0 导致无法进入低功耗。

处理电源 IRP 的常见套路是：用PoRequestPowerIrp请求设备电源状态转换，并设置一个完成例程在转换结束后释放自旋锁。如果你不需要做复杂的电源管理，至少要在设备扩展里记录当前电源状态，防止在 D3 状态下访问 BAR 寄存器——低功耗状态下很多设备已经断电，读写寄存器会直接触发总线错误。这一点在笔记本平台上尤其明显：合盖再打开，设备没了，驱动还在访问旧地址，这就是典型的 WDM 电源翻车现场。

4. 编译与部署：从 WDK 工程到可加载驱动的完整流程

4.1 用 Visual Studio 与 WDK 打开工程并选择目标平台

拿到这套包后，第一步不是改代码，而是先让它编译通过。用 Visual Studio 打开DriverDev.sln，如果提示工程升级，直接确认即可。解决方案里MyDriver.vcxproj是驱动工程，右键属性注意三个地方：目标平台选 x64（现在几乎不会有人再做 32 位驱动）、配置类型选「驱动程序」、目标 OS 版本按你机器上的 Windows 版本走。老工程从 VC6 迁移过来时，常常会出现 SDK 版本和 WDK 版本不匹配的错误，解决方法是把这个工程的目标 SDK 版本改成当前机器已安装的版本，WDK 的版本要求可以在项目属性中的「驱动程序设置」里看到。

编译命令也可以直接用 MSBuild：

"<WDK安装路径>\bin\Windows Kits\10\Tools\bin\10.0.xxx.0\x64\Inf2Cat.exe" /driver:.\x64\Debug\ /os:10_X64

不过手动敲命令不如在 VS 里按 F7 来得快。构建成功后会生成.sys文件，它和HelloWDM.inf摆在一起，就是最终要装进系统的两个核心文件。如果编译报错说找不到wdm.h或ntddk.h，说明工程引用没连上 WDK，需要在 VC++ 目录里把包含路径指向 Windows Kits 的 Include 目录。

4.2 测试签名与 .inf：让设备管理器认定为可安装驱动

64 位 Windows 强制要求内核驱动有数字签名，未签名驱动在正常模式下会被拒绝加载。开发阶段有两类路径：一是用测试签名让驱动临时可加载，二是直接用Signtool做测试证书签名。测试签名是开发中最常用的路径，操作如下：

bcdedit /set testsigning on

然后重启系统。重启后桌面右下角出现「测试模式」水印，表示测试签名已生效。再用Signtool给驱动签名：

signtool sign /v /s TestCertStoreName /n MyTestCertName /t http://timestamp.digicert.com .\x64\Debug\MyDriver.sys

签完名后，HelloWDM.inf里必须正确写好硬件 ID，否则设备管理器无法匹配设备。

[Version] Signature = "$WINDOWS NT$" Class = System Provider = %ProviderName% DriverVer = 05/01/2024,1.0.0.0 [Manufacturer] %ProviderName% = DeviceList, NTamd64 [DeviceList.NTamd64] %DeviceDesc% = DriverInstall, PCI\VEN_10EE&DEV_9038

这个 INF 的关键在最后一行：PCI\VEN_10EE&DEV_9038是 PCIe 设备的硬件 ID，格式是厂商 ID 加设备 ID。你的设备具体 ID 是多少，可以用设备管理器里「详细信息 → 硬件 ID」查出来，然后照格式改。如果这里填错，驱动装不上，设备管理器会一直显示「找不到驱动程序」。

4.3 部署与调试：设备管理器加载、DbgView 看输出与 WinDbg 联调

驱动编译签名完成后，部署步骤很简单：把MyDriver.sys和HelloWDM.inf拷到一个文件夹，右键 inf 选「安装」，或者打开设备管理器，对未知设备手动更新驱动程序并指向这个文件夹。加载成功后，设备类型会从「其他设备」跳转到「系统设备」分类下，状态栏不再有黄色感叹号。

调试是 WDM 驱动开发的日常。最简单的方式是用 DbgView 捕获内核输出：

DbgPrint("HelloWDM: Device started, BAR0 = 0x%p\n", pDevExt->bar0Addr);

用DbgPrintEx输出带级别的调试信息也是常见做法，但它和DbgPrint的区别只是多了一个级别参数，输出行为基本一致。打开 DbgView，勾选 Capture Kernel，就能实时看到驱动的打印。这套组合拳对大多数加载失败和 IOCTL 无响应问题都够用。真正需要断点调试时，再上 WinDbg 走双机调试，但那是另一个量级的工作量，新手不建议一上来就碰。

5. 避坑：WDM PCI/PCIe 驱动开发中的典型坑

5.1 加载阶段的坑：Code 10 与符号链接打不开

第一个高频坑是设备管理器报 Code 10。现象：驱动安装后设备前面有黄色感叹号，属性里显示「设备无法启动」。原因多数是 DriverEntry 里没有正确初始化某个必要字段，比如漏掉DriverObject->DriverUnload，或者 AddDevice 返回了失败而未做清理。解决：先看 DbgView 输出，Code 10 的常见伴随现象是驱动加载到一半被回滚，打印里会残留最后一次 DbgPrint 的位置，用日志缩小问题范围；再把 IRP_MJ_DEVICE_CONTROL 之类的分发例程都先设成空函数，逐步加逻辑，定位是哪一个例程导致失败。

第二个是用户态打不开设备。现象：Test 工程的CreateFile返回 INVALID_HANDLE_VALUE，错误码是 2（文件找不到）。原因：驱动里IoCreateSymbolicLink失败了，或者符号链接名称写得不对。解决：确认要用\DosDevices\HelloWDM这种完整 DOS 设备名，而不是只写\Device\HelloWDM；同时检查IoCreateSymbolicLink的返回值，失败时多半是因为设备名已经被别的驱动占用。这条路我走过不止一次，最后发现只是链接名少了个斜杠，血泪教训。

5.2 I/O 阶段的坑：IOCTL 缓冲区与指针长度

第三个坑是 DeviceIoControl 返回错误码 87（参数不正确）。现象：IOCTL 发出去立刻失败，但驱动里看起来什么都没执行。原因：用户态定义的 IOCTL 控制码和驱动端Ioctls.h里不一致，或者 METHOD_BUFFERED 模式下输出缓冲区长度小于驱动要返回的数据。解决：确认用户态和驱动端共用同一份Ioctls.h，CTL_CODE 宏里的 DeviceType、FunctionCode、Method、Access 四个参数完全一致才能对上；然后用DeviceIoControl的nOutBufferSize参数传入足够大的缓冲区，驱动端在返回前把IoStatus.Information设为实际写入长度。

第四个坑和 64 位平台有关。现象：驱动从用户态缓冲区里读结构体时，指针字段全部错乱。原因：用户态程序是 32 位编译的，结构体里又放了HANDLE或指针，传到 64 位驱动里大小变成 8 字节，导致偏移量错位。解决：内核驱动不直接传指针，统一用METHOD_BUFFERED模式，让 I/O 管理器复制缓冲区；如果结构体里带指针，改成用 64 位整数存储。这条在 PCIe 驱动里特别常见，因为很多自定义 IOCTL 都会传寄存器地址。

5.3 硬件交互的坑：PCIe 枚举、PERST 与资源冲突

第五个坑在 PCIe 硬件层面，常见于自研板卡。现象：设备有时能枚举到，有时设备管理器直接空白，驱动加载后访问 BAR 寄存器导致蓝屏。原因：PCIe 设备没有拉对 PERST# 复位时序，板卡在上电初期还没就绪，总线枚举时配置空间读到全 FF，系统认为没有设备。解决：查硬件原理图确认 PERST# 的上电时序是否满足 PCIe 规范——它必须晚于主电源稳定且至少保持 100ms 低电平；如果是驱动问题，另一个可能是 BAR 资源冲突，到设备管理器里看资源选项卡，检查是否和别的设备抢了同一段内存。现成硬件里这个问题集中在 PCIe 热插拔场景，设备拔出后驱动还在读写 BAR，同样蓝屏。处理方法是正确响应IRP_MN_SURPRISE_REMOVAL，在该例程里释放MmMapIoSpace映射并注销中断。

第六个坑相对隐蔽：跨平台测试时「在自己电脑上正常」。我把同一个驱动从开发机搬到测试机后，IOCTL 全挂，查了一天才发现测试机系统是 32 位 Version 1607，而驱动编译时选的 CRT 版本太高。解决：内核驱动尽量用 WDK 自带的运行库，不要依赖新版 UCRT；发布前至少在 Win10 和 Win11、x64 和 x86 环境各跑一遍 Test 工程。这套包里的.dsp旧工程其实就是个提醒：WDM 驱动兼容性好的写法，反而是越简单越不容易坏。

6. 验证与进阶：从 Test 自测到 KMDF 迁移的升级路径

6.1 用 Test 工程做回环自测：确认设备栈和 I/O 通路

驱动签名安装成功后，先用 Test 工程做一次完整的回环自测：打开设备、发送一个读寄存器控制码、检查返回值。这个方法能验证整个链路：符号链接是否正确创建、IRP 分发是否挂对、设备栈是否完整。我一般会先加一个最简 IOCTL，让驱动直接返回一个固定值，用户态打印出来；数值一致，说明通路已通，接下来再谈寄存器读写。这个「先回环、再实操」的顺序，比直接上硬件寄存器调试要稳得多。

// 驱动端：极简回环处理 case IOCTL_HELLOWDM_ECHO: *(ULONG*)Irp->AssociatedIrp.SystemBuffer = 0x12345678; Irp->IoStatus.Information = sizeof(ULONG); break; // 用户态：发出回环请求 DeviceIoControl(hDevice, IOCTL_HELLOWDM_ECHO, NULL, 0, &outBuf, sizeof(outBuf), &bytesReturned, NULL); if (outBuf == 0x12345678) { printf("Echo OK: driver is alive\n"); }

METHOD_BUFFERED模式下，驱动直接操作Irp->AssociatedIrp.SystemBuffer就是用户态传入的缓冲区，I/O 管理器会在完成后自动复制回用户态。这就是回环自测的全部秘密：不碰硬件，先证明驱动框架活着。

6.2 从 WDM 到 KMDF：迁移映射与新一代驱动选型

如果你接下来要为 PCIe 设备写正式产品驱动，不建议继续在裸 WDM 上堆代码，而是把这份工程当作理解底层机制的教材，然后迁移到 KMDF。KMDF 帮你处理了大部分 PnP、电源、队列机制，同样的功能代码量能减少一半以上。

我最早写 PCIe 驱动时也是入门阶段直接啃裸 WDM，走了不少弯路，后来切到 KMDF 才明白什么叫「框架兜底」。但回看这套包，它始终值得留一份在身边——KMDF 文档里解释 PnP 和电源时，底层讲的还是 WDM 那一套机制。从那以后，我每次拿到一个新板卡，都会先按这套流程把 HelloWDM 式的骨架跑通，再用 KMDF 重写业务逻辑，最后用 Test 工程的回环用例做回归。这套「先通链路、再上框架」的习惯，帮我挡掉了大量后半程才暴露的底层问题。希望这套经验对你也有用。

本文还有配套的精品资源，点击获取