📚 课程目录第1章 KMDF概述

KMDF框架中断处理与设备栈遍历实战 - 第1节

1.1 KMDF 框架简介

Kernel-Mode Driver Framework（KMDF）是微软为 Windows 驱动开发提供的一种面向对象、事件驱动的框架，属于 Windows Driver Foundation（WDF）的一部分。KMDF 封装了传统 WDM 驱动中大量重复、易错的样板代码，让开发者能够专注于设备特有的逻辑，而非底层 IRP 处理细节。

KMDF 核心设计理念：“约定优于配置”——框架接管 PnP 与电源管理、I/O 队列、DMA 等通用任务，驱动只需注册回调（EvtXxx）即可响应事件。

KMDF 的主要特性

简化开发模型：驱动只需实现少量 EvtXxx 回调函数，框架自动处理 IRP 分发与同步。
内置 PnP 与电源管理：框架自动响应设备添加、移除、休眠、唤醒等状态变化。
I/O 队列自动化：框架提供顺序、并行、手动三种队列模型，驱动无需手动管理 IRP 排队。
对象层次与引用计数：所有内核对象（WDFOBJECT）均支持父子关系、自动清理与引用跟踪。
中断同步与 DPC：框架提供 WDFINTERRUPT 对象，自动处理中断同步、DIRQL 与 DPC 调度。
即插即用友好：支持设备栈遍历、资源重新平衡、意外移除等场景。

1.2 KMDF 与传统 WDM 对比

WDM（Windows Driver Model）是 KMDF 出现之前的主流驱动模型，驱动开发者需要手动处理大量底层 IRP 和 PnP 逻辑。KMDF 在 WDM 之上构建了一层抽象，显著降低了开发复杂度与出错概率。

对比维度	传统 WDM	KMDF
开发工作量	需实现所有 IRP 分发例程（DispatchXxx）	仅需注册 EvtXxx 回调，框架自动分发
PnP 与电源管理	手动处理 IRP_MN_START_DEVICE、IRP_MN_STOP_DEVICE 等	框架自动响应状态变化，驱动只需实现 EvtDevicePrepareHardware 等
I/O 队列	需自行管理 IRP 排队、取消、同步	框架提供顺序、并行、手动队列，自动处理取消与同步
中断处理	直接注册 InterruptService 例程，需手动同步 DIRQL	WDFINTERRUPT 对象封装中断同步、DPC 与被动级回调
对象模型	无统一对象模型，依赖设备对象（DEVICE_OBJECT）	WDFOBJECT 层次结构，支持引用计数、父子关系、自动清理
错误隔离	驱动错误容易导致系统蓝屏	框架提供验证层（WDF Verifier），捕获常见错误
调试支持	依赖 WinDbg 手动分析	内置 !wdfkd 扩展，对象树、队列、中断状态一目了然

  迁移建议：新项目优先选择 KMDF；已有 WDM 驱动可通过 WDF 转换库逐步迁移，无需一次性重写全部代码。

1.3 KMDF 核心对象模型

KMDF 采用层次化对象模型，所有对象都继承自 WDFOBJECT 基类。每个对象拥有父对象、引用计数、上下文空间和回调注册表。对象树以 WDFDRIVER 为根，向下展开 WDFDEVICE、WDFQUEUE、WDFREQUEST、WDFINTERRUPT 等子对象。

核心对象一览

对象类型	句柄类型	主要用途	典型父对象
Driver	WDFDRIVER	驱动实例，管理设备对象与全局资源	无（根对象）
Device	WDFDEVICE	代表一个设备实例，包含 PnP 状态、电源策略	WDFDRIVER
Queue	WDFQUEUE	管理 I/O 请求的排队与分发	WDFDEVICE
Request	WDFREQUEST	封装一个 I/O 请求（IRP）	WDFQUEUE
Interrupt	WDFINTERRUPT	管理中断同步、DPC 与被动级回调	WDFDEVICE
DmaEnabler	WDFDMAENABLER	配置 DMA 适配器与通道	WDFDEVICE
Timer	WDFTIMER	定时器回调，支持周期性或一次性触发	WDFDEVICE
WorkItem	WDFWORKITEM	在系统工作线程中执行延迟任务	WDFDEVICE

对象生命周期与上下文

每个 KMDF 对象在创建时可通过 WDF_OBJECT_ATTRIBUTES 结构指定上下文大小和清理回调。框架在对象销毁时自动释放上下文内存，无需驱动手动释放。

// 示例：创建 WDFDEVICE 并分配上下文
WDF_OBJECT_ATTRIBUTES attributes;
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, MY_DEVICE_CONTEXT);

WDFDEVICE device;
NTSTATUS status = WdfDeviceCreate(&pDeviceInit, &attributes, &device);
if (!NT_SUCCESS(status)) {
    return status;
}

// 获取上下文指针
MY_DEVICE_CONTEXT *pContext = MyDeviceGetContext(device);
pContext->DeviceState = DEVICE_STATE_INITIALIZED;

注意：KMDF 对象上下文必须在创建时分配，创建后无法动态扩展。如果需要在运行时分配可变大小数据，应使用 WDFMEMORY 对象或单独分配的非分页池。

对象上下文宏

KMDF 提供一组宏来简化上下文的声明与访问，推荐所有驱动使用 WDF_DECLARE_CONTEXT_TYPE 和 WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE 模式。

// 声明上下文类型
typedef struct _MY_DEVICE_CONTEXT {
    ULONG  DeviceState;
    WDFQUEUE DefaultQueue;
    WDFINTERRUPT Interrupt;
} MY_DEVICE_CONTEXT, *PMY_DEVICE_CONTEXT;

WDF_DECLARE_CONTEXT_TYPE(MY_DEVICE_CONTEXT);

// 获取上下文的 inline 函数
PMY_DEVICE_CONTEXT MyDeviceGetContext(WDFDEVICE Device) {
    return WdfObjectGetTypedContext(Device, MY_DEVICE_CONTEXT);
}

最佳实践：始终使用 WdfObjectGetTypedContext 而非 WdfObjectGetContext，前者在编译时进行类型检查，避免上下文类型错配导致的隐蔽 bug。

对象树遍历

KMDF 支持通过父子关系遍历对象树，这在调试和资源清理时非常有用。框架提供 WdfObjectGetParentObject 和 WdfObjectGetTypedContext 等 API 实现遍历。

// 从 WDFQUEUE 获取父设备
WDFDEVICE parentDevice = WdfObjectGetParentObject(queue);
PMY_DEVICE_CONTEXT ctx = MyDeviceGetContext(parentDevice);

// 遍历设备下的所有中断对象（示意）
WDFINTERRUPT interrupt;
WDF_OBJECT_ITERATOR iterator;
WdfObjectIteratorCreate(WdfDeviceGetInterruptCollection(device), &iterator);
while (WdfObjectIteratorGetNext(iterator, &interrupt)) {
    // 处理每个中断对象
}
WdfObjectIteratorDestroy(iterator);