WDF/KMDF驱动开发：并发、对象生命周期与I/O队列避坑

简介：《Developing Drivers with the Windows Driver Foundation》是一本由 WDF 开发团队参与撰写、面向 Windows 驱动开发者的系统性技术指南，适合具备 C 语言与 Win32 编程基础、希望从零掌握驱动程序开发的中高级开发者，也可作为 KMDF 与 UMDF 两条技术路线的案头参考。资源为 1 个 PDF 文件，压缩包约 8.25MB，正文近 928 页，内容完整、便于离线检索与长期查阅。全书按六大板块组织：先介绍 WDF 与 Windows 驱动基础，再剖析内核模式与用户模式两种框架，随后依次展开 WDF 对象模型、驱动结构与初始化、即插即用与电源管理、I/O 流与分派、I/O 目标、同步与并发、驱动跟踪与诊断、WDF 支持对象及 UMDF 模板，并进一步覆盖线程上下文与 IRQL、硬件资源与中断、DMA 等进阶主题，末尾落到驱动编译、安装、测试、调试、PREfast 与静态驱动验证器（Static Driver Verifier）等工程实践。书中配有大量代码示例与最佳实践，可帮助读者理解框架设计思路、把驱动开发中的常见坑点转化为可落地的实现方案，已有 564 人学习。

1. 驱动崩溃不是硬件坏了，而是没人替你把并发规则执行完

内核转储里绝大多数蓝屏的栈顶都落在某个驱动回调上，触发点却常常不是硬件真坏了。Windows 驱动开发者熟悉的一种玄学是：功能测试全部通过，加一个拔插场景就崩，回溯只能看到“谁崩的”，看不到“谁破坏了规则”。Windows Driver Foundation（WDF）值得读透的地方，不在它多封装了一层 API，而在于它把那些藏在文档角落里、靠血泪经验口口相传的规则，变成了框架强制执行的结构约束。搞懂这一层，你看到 WdfObjectDelete 、 WdfRequestComplete 时才明白自己在跟谁打交道，松开手之后谁还欠着账。

2. WDM 的复杂度从哪来：PnP、电源与 I/O 三股并发为什么把状态机推给驱动

2.1 同一个设备对象，三类事件在同时到达

旧驱动模型（WDM）里一个功能设备对象会同时收到三类 IRP：功能请求（ IRP_MJ_READ 、 IRP_MJ_WRITE 、 IRP_MJ_DEVICE_CONTROL ）、即插即用请求（ IRP_MJ_PNP ，带 IRP_MN_START_DEVICE 、 IRP_MN_REMOVE_DEVICE 、 IRP_MN_SURPRISE_REMOVAL 这些 minor function）、电源请求（ IRP_MJ_POWER ，带 IRP_MN_SET_POWER 、 IRP_MN_QUERY_POWER 、 IRP_MN_WAIT_WAKE ）。这三股流走的是同一套 IRP 栈，而 IRP 栈是逐层下推的结构，每层驱动靠 IoGetCurrentIrpStackLocation 拿到属于自己的那一格参数。

麻烦在于三者的生命周期互相穿插。读写请求可能正在 DMA 传输途中，电源降级请求就到了；设备移除可能发生在队列里还压着十几个请求的时候。WDM 为了让支持 PnP 的驱动和不支持 PnP 的老驱动共存，把“谁先谁后”的仲裁权完全下放给了驱动。于是每个驱动都得自己维护一套状态标志： Started 、 Removing 、 SurpriseRemoved 、 PowerD0 ，再加上对正在处理请求的引用计数。

这套组合拳写一次是手艺，写一百次就是事故源。

2.2 状态机外溢：为什么驱动开发者被迫维护设备状态

一个典型的 WDM 驱动要在 AddDevice 里创建设备对象，在 IRP_MN_START_DEVICE 里取 CM_RESOURCE_LIST 、映射寄存器、连接中断，然后在 StartDevice 完成之前把所有功能 IRP 排队，不能访问还没映射的硬件。移除路径上又要拒绝新 I/O、等 in-flight 请求归零、断开中断、解除映射、最后删设备对象。

这几步任何一步漏了，后果都不是“功能不对”，而是“随机蓝屏”。尤其在 IRP_MN_SURPRISE_REMOVAL 场景下，设备已经物理消失但 IRP 还在下发，驱动如果没有“移除后立即让所有请求以失败完成”的机制，就会在访问已经释放的寄存器地址时触发一个无意义的崩溃。

更隐蔽的是取消。异步可取消 I/O 从一开始就设计在系统里，但很多驱动只处理了“请求进来了”，没处理“请求被用户按 Ctrl+C 取消了”，于是 WdfRequest 对应的缓冲区被释放之后，硬件 DMA 还在往那块内存写。

2.3 WDF 的切分：框架管状态，驱动管策略

WDF 的核心判断是：上面那些排队、状态、清理、取消处理，全是通用模式，和具体硬件无关，可以被抽走。于是框架持有设备状态机，驱动只需实现几个语义明确的回调；I/O 请求被收进队列对象，队列的开关和 PnP、电源事件自动联动——设备没启动时队列不交付请求，设备移除时队列被排空。

// 驱动入口：把"驱动对象"的创建交给框架
NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath)
{
    WDF_DRIVER_CONFIG config;

    // EvtDriverDeviceAdd 是设备对象出现的唯一入口
    WDF_DRIVER_CONFIG_INIT(&config, EvtDriverDeviceAdd);

    // 无需手写 DriverObject->MajorFunction[] 分派表
    return WdfDriverCreate(DriverObject, RegistryPath,
                           WDF_NO_OBJECT_ATTRIBUTES,
                           &config,
                           WDF_NO_HANDLE);
}

这里 WdfDriverCreate 做三件事：创建 WDFDRIVER 对象并挂在 WDM 的 DRIVER_OBJECT 上；接管 PnP 和电源两类 IRP 的默认分派；把 EvtDriverDeviceAdd 注册成框架回调。参数 WDF_NO_OBJECT_ATTRIBUTES 表示这个驱动对象用默认属性、没有父对象、不需要上下文区。 RegistryPath 是传给框架用于读注册表参数的路径，驱动自己一般不需要再处理它。

EvtDriverDeviceAdd 里做的事对应 WDM 的 AddDevice ，但驱动不再需要手工调用 IoCreateDevice 。

3. WDF 对象模型：为什么句柄、上下文和父子清理能替代全局状态

3.1 COM-lite：不用注册表式 COM 的取舍

WDF 的对象模型借了 COM 的形，没借 COM 的神。它有引用计数、有接口、有对象生命周期，但没有注册表、没有类型库、没有跨进程封送。驱动侧看到的是不透明句柄 WDFDEVICE 、 WDFQUEUE 、 WDFREQUEST ，而不是裸指针。所有对象必须由 WdfXxxCreate 创建，创建时填入一个 WDF_OBJECT_ATTRIBUTES 。

为什么不做完整 COM：内核环境不允许异常，RTTI 和元数据查询的开销在非分页内存里不划算， QueryInterface 那套动态发现机制对一个只有二十来种固定对象类型的框架来说是纯负担。框架内部维护句柄表，把句柄映射到真实对象指针，驱动拿句柄去调 API 时由框架完成一次查表。

代价是热路径上多一次间接寻址。收益是：句柄在被销毁之后可以被标记成失效状态，调试版本里直接断言，而不是让你拿着悬空指针去踩别的东西。这类错误在 WDM 时代往往要花几天才能在 dump 里定位。

3.2 对象上下文：把驱动的全局变量塞进对象内存

WDM 驱动常见的做法是维护一张“设备对象指针 → 私有数据结构指针”的全局链表，还要自己加锁保护这张表。WDF 把这个模式内建成上下文区：创建对象时声明一个上下文类型，框架在对象尾部多分配一块内存，驱动通过 WdfObjectGet_XXX 直接取。

// 设备私有状态：声明之后框架知道要分配多大空间
typedef struct _DEVICE_CONTEXT {
    WDFDEVICE    Device;
    WDFQUEUE     DefaultQueue;
    WDFINTERRUPT Interrupt;
    ULONG        PendingIoCount;
    BOOLEAN      HardwareReady;
} DEVICE_CONTEXT, *PDEVICE_CONTEXT;

// 展开成一个静态类型描述符，同时生成取值函数
WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(DEVICE_CONTEXT, GetDeviceContext)

NTSTATUS EvtDriverDeviceAdd(WDFDRIVER Driver, PWDFDEVICE_INIT DeviceInit)
{
    WDF_OBJECT_ATTRIBUTES attrs;
    WDFDEVICE device;

    // ContextSize 由宏推导，驱动不再手工填
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attrs, DEVICE_CONTEXT);

    NTSTATUS status = WdfDeviceCreate(&DeviceInit, &attrs, &device);
    if (!NT_SUCCESS(status)) return status;

    PDEVICE_CONTEXT ctx = GetDeviceContext(device);
    ctx->Device = device;
    ctx->HardwareReady = FALSE;
    return STATUS_SUCCESS;
}

WDF_DECLARE_CONTEXT_TYPE_WITH_NAME 这个宏在编译期生成一个静态的 WDF_OBJECT_CONTEXT_TYPE_INFO 结构，里面记录上下文大小和一个用于调试输出的类型名。 WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE 把它的指针塞进属性结构，框架分配对象时按这个大小一起分配。

这样做的机制含义是：上下文的内存和对象的内存是同一次分配、同一段生命周期。对象被删除时上下文自然消失，不存在“对象还在但私有数据被提前释放”这种时序漏洞。

3.3 父子关系与引用计数：谁负责删除，什么时候删

每个对象创建时都可以指定 ParentObject 。父对象被删除时，挂在上面的子对象按创建逆序自动删除。 WDFDEVICE 被删除时，它下面的默认队列、中断对象、定时器全部跟着走，驱动不用写一行清理代码。

引用计数（ WdfObjectReference / WdfObjectDereference ）解决的是另一个问题：一个对象被多方持有，但没人知道最后一个持有者是谁。比如一个请求对象被交给 I/O 目标异步发送，同时驱动想保留一个引用用于后续查询状态。

这里最容易翻车的地方是默认值。 WDF_NO_OBJECT_ATTRIBUTES 意味着没有父对象，谁创建谁负责删除。临时创建的 WDFMEMORY 、 WDFSTRING 如果忘了指定父对象又忘了显式 WdfObjectDelete ，在驱动验证工具的对象追踪里就会表现为句柄计数一路涨。本地跑几百次启停可能看不出来，压力一上来内存就被啃掉。

提示：临时对象的 ParentObject 优先设成当前 WDFREQUEST 或 WDFDEVICE ，让生命周期跟着业务对象走，比手工配对的 Delete 可靠得多。

4. I/O 队列、请求生命周期与同步：KMDF 怎么把并发收敛成回调约定

4.1 队列是分派的基本单位，不是 IRP 的皮

内核模式框架（KMDF）里，功能 IRP 进入驱动后先被转换成 WDFREQUEST ，压进队列对象，再按队列配置的回调交给驱动。三种分派模型决定了并发度：

分派类型	回调交付方式	适用场景
WdfIoQueueDispatchSequential	一次一个，前一个完成或挂起后才交付下一个	控制面 IOCTL、有共享硬件状态的读写
WdfIoQueueDispatchParallel	可同时交付多个，受队列深度约束	无共享状态的高吞吐读
WdfIoQueueDispatchManual	驱动自己调用 WdfIoQueueRetrieveNextRequest 取	转发型驱动、需要自己控制出入列时机

WDF_IO_QUEUE_CONFIG qcfg;

// 默认队列：未被其他队列认领的 IRP 都送到这里
WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(&qcfg, WdfIoQueueDispatchSequential);
qcfg.EvtIoRead          = EvtIoRead;
qcfg.EvtIoWrite         = EvtIoWrite;
qcfg.EvtIoDeviceControl = EvtIoDeviceControl;

NTSTATUS status = WdfIoQueueCreate(device, &qcfg,
                                   WDF_NO_OBJECT_ATTRIBUTES,
                                   &queue);

WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE 创建的是默认队列，框架把所有没被专门队列接走的请求都投递到这里。没有为某个 EvtIoXxx 赋值时，框架对该类型的请求默认以 STATUS_INVALID_DEVICE_REQUEST 完成，这个默认行为本身就是一道防线——总比让未实现的请求挂在半空好。

DispatchType 的选择本质上是吞吐和正确性的交换。顺序队列把并发压到 1，硬件寄存器状态不需要加锁；并行队列省掉了框架层的串行化开销，但驱动得自己保证访问硬件时的互斥。

4.2 请求生命周期与取消：EvtRequestCancel 和 in-flight 记录

WDFREQUEST 在队列里时是可取消的；一旦交付给驱动，是否可取消由驱动说了算。驱动通过 WdfRequestMarkCancelableEx 注册取消回调，此后取消事件可能在另一个线程上与当前回调并发发生。

VOID EvtIoRead(WDFQUEUE Queue, WDFREQUEST Request, size_t Length)
{
    PDEVICE_CONTEXT ctx = GetDeviceContext(WdfIoQueueGetDevice(Queue));

    // 标记可取消；返回失败说明请求已处于取消中
    NTSTATUS status = WdfRequestMarkCancelableEx(Request, EvtRequestCancel);
    if (!NT_SUCCESS(status)) {
        WdfRequestComplete(Request, status);
        return;
    }

    // 此处可以把 Request 交给 I/O 目标异步发送
    ctx->PendingIoCount++;
}

WdfRequestMarkCancelableEx 和 WdfRequestMarkCancelable 的区别在于失败语义： Ex 版本在请求已被取消时同步返回失败，驱动必须立刻完成请求，不能再往下走；非 Ex 版本内部做了更重的同步，适合在 PASSIVE_LEVEL 且不追求极致延迟的场景。

框架在队列内部维护一张 in-flight 请求表。这张表是 PnP 移除路径上的关键： WdfIoQueuePurge 会把还没开始处理的请求以 STATUS_CANCELLED 完成掉，然后阻止新请求入队； WdfIoQueueDrain 则会让已交付的请求走完再关闭。没有这张表，驱动只能自己数引用，而自己数的引用十次有八次会在移除时漏掉一个。

4.3 自动同步作用域：为什么回调里不用自己抢锁

对象可以配置同步作用域： WdfSynchronizationScopeNone （默认，回调可并发）、 WdfSynchronizationScopeDevice （同一设备上的回调自动串行）、 WdfSynchronizationScopeQueue （队列级）。配置成设备级之后，框架在执行任何该设备的回调之前先获取一个内部锁，回调执行完再释放。

机制上，这个锁是一个自旋锁，意味着回调实际上运行在 DISPATCH_LEVEL 。这就是为什么很多人打开自动同步之后开始出现 PASSIVE_LEVEL 断言失败：回调里调用了会阻塞的 API，比如 WdfRequestSend 的同步版本、或者任何等待型对象。

我的理解是：自动同步适合低频控制面，用一点点吞吐换掉一整类竞态 bug；数据面要么拆成手动锁分段（ WDFWAITLOCK 保护慢路径、 WDFSPINLOCK 保护快路径），要么把阻塞操作下移到工作项里执行再回到回调完成请求。

4.4 I/O Target：转发请求时 IRP 栈怎么被折叠

WDFIOTARGET 是对“向下层驱动发请求”这件事的封装。本地目标是当前设备栈的下一层，远程目标是用 WdfIoTargetOpen 打开的另一条设备栈，特殊目标用来向 PDO 发送请求。 WdfRequestSend 会先把 WDFREQUEST 格式化成 IRP、填好下一层栈位置，再 IoCallDriver ；异步返回后，完成例程把 IRP 再转回 WDFREQUEST 交还给驱动。

转发型驱动容易踩的坑是格式选项。 WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET 表示不关心完成结果，此时框架会立刻回收请求对象，驱动不能再持有句柄。如果需要读下层返回的数据，必须走带完成回调的异步路径，并在完成例程里拷贝数据、完成原始请求。

5. 避坑与排查：WDF 开发里最容易翻车的五个点

5.1 在 PrepareHardware 之前就访问硬件寄存器

现象： START_DEVICE 阶段设备初始化偶发失败，或者访问寄存器时拿到全 0xFF，重试一次又正常。

原因：资源映射发生在 EvtDevicePrepareHardware 里，硬件上电发生在 EvtDeviceD0Entry 里，这两个回调的顺序和职责被很多人混在一起用。 PrepareHardware 阶段设备可能还没进入 D0，读寄存器没有意义。

解决：把 WdfCmResourceList 的解析、 MmMapIoSpace 类映射、中断连接全部放在 PrepareHardware ；把实际上电初始化序列、寄存器复位放在 D0Entry ，并保证 D0Exit 里成对撤销。这两个回调的配对关系是框架强制的，不要试图合并。

5.2 完成请求之后还继续使用那个句柄

现象：随机蓝屏，栈顶停在 WdfRequestComplete 或者某个 IRQL 断言上，dump 里的参数看起来完全正常。

原因：调用 WdfRequestComplete 意味着所有权交还框架，框架可能立刻把这个对象回收并复用给下一个请求。此时驱动手里的句柄指向的已经是别人的请求。

解决：完成前把需要的字段全部拷到局部变量，完成之后除了返回不要做任何事。需要“完成了还要干点别的”的场景，正确顺序是先干完别的、再完成请求。

5.3 打开自动同步之后调用阻塞型 API

现象：驱动在压力测试下死锁，或者调试版本里 ASSERT 报出 IRQL_NOT_LESS_OR_EQUAL 。

原因： WdfSynchronizationScopeDevice 的回调持有自旋锁，运行在 DISPATCH_LEVEL 。在回调里等待一个事件、调用同步发送、申请分页内存，都是在这个上下文里做不被允许的事。

解决：去掉自动同步，改用手动 WDFWAITLOCK 保护真正需要互斥的那几行；或者把阻塞操作封进 WDFWORKITEM ，工作项跑在 PASSIVE_LEVEL ，执行完再调 WdfRequestComplete 。

5.4 移除路径上忘了排空队列

现象：设备热插拔后偶发崩溃，dump 里能看到移除完成之后还有请求在访问已释放的映射地址。

原因： EvtDeviceReleaseHardware 里解除了映射、断开了中断，但默认队列还开着。框架仍然会把新到的 IRP 交付给回调，回调一访问硬件就崩。

解决：移除路径上的顺序固定为停 I/O 目标、purge 所有队列、等 in-flight 归零、再断开中断、最后 ReleaseHardware 。这个顺序不能凭感觉调整。

5.5 本地反复启停正常，一上验证工具就爆对象泄漏

现象：功能测试几百次启停都不出错，打开驱动验证工具和框架自带的验证器之后，句柄计数单调上升。

原因：临时 WDFMEMORY 、 WDFSTRING 、 WDFCOLLECTION 创建时没给 ParentObject ，也没显式删除。运行期因为内存压力不明显，问题被掩盖。

解决：统一给临时对象设父对象，让它跟着当前请求或者设备走；本地调试时长期开着框架验证器的对象追踪，别等到发布前才跑一遍。

6. 从静态分析到框架内建验证：为什么“可验证性”被当成设计目标

框架带来的最大变化，是把一批原本只能靠代码评审发现的问题，变成了工具能自动判定的性质。源码级静态分析在编译期扫描低 IRQL 访问分页内存、格式化字符串、缓冲区越界这类模式；静态驱动验证器走得更远，它把驱动源码连同框架和系统的接口契约一起转成可判定的模型，对每个被拒绝的路径给出反例，验证的是“每个请求完成路径上取消标记是否配对”这类跨函数性质，而不是单行语法。

框架侧则内建了运行期验证：句柄追踪检查对象泄漏，对象生命周期检查在删除顺序不对时直接断言，内存里的环形跟踪缓冲在蓝屏之后能把框架内部最近发生的事件还原出来，等于给驱动装了一个黑匣子。

这套设计的取舍在于：框架能保证的，只有它自己定义的那部分契约。一旦你为了某个特殊需求穿透到框架底下直接操作 IRP，前面所有的同步保证、生命周期保证、验证工具的可判定性会同时失效，而且失效是静默的——编译过、跑得动、偶尔崩。

从那以后我每次要动“框架外”的代码之前，都会强制走一遍这个判断：这个能力框架里真的没有，还是我只是没找到对应的对象和回调。希望帮到你。

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