2. KMDF 对象模型：WDF对象层次结构、WDF对象句柄、对象上下文空间、对象生命周期管理

KMDF 的核心设计哲学是“对象化”。它将内核资源（设备、队列、中断、DMA 适配器等）抽象为 WDF 对象，通过统一的句柄、上下文和生命周期管理机制，大幅降低驱动开发的复杂度和错误率。本章深入剖析 WDF 对象模型的四大支柱：层次结构、句柄、上下文空间与生命周期。

2.1 WDF 对象层次结构

WDF 对象以树状层次组织，每个对象都有一个父对象。父对象的生命周期决定了子对象的生命周期——当父对象被销毁时，所有子对象自动被清理。这种设计消除了传统 WDM 驱动中繁琐的手动资源释放逻辑。

2.1.1 主要 WDF 对象类型与层级关系

2.1.2 层次结构 SVG 图

2.2 WDF 对象句柄

WDF 不直接暴露对象指针，而是通过 句柄（Handle） 引用所有对象。句柄是一个不透明类型，例如 WDFDEVICE、WDFQUEUE、WDFINTERRUPT。驱动代码只能通过句柄调用框架提供的 API，不能直接解引用或访问内部结构。

2.2.1 句柄的设计优势

• 类型安全： 每个句柄类型在编译时即被检查，防止将队列句柄误传给中断 API。
• 间接层： 框架可以在句柄背后执行引用计数、调试跟踪、对象验证，而无需驱动参与。
• 调试友好： 在 WinDbg 中，!wdfhandle 命令可以显示句柄对应的对象类型、状态、上下文和引用计数。

2.2.2 句柄的获取与使用

句柄通常在对象创建时通过输出参数获得，或通过父对象查询子对象句柄。典型模式如下：

WDFDEVICE device;
WDF_OBJECT_ATTRIBUTES attributes;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

// 创建设备对象，句柄存储在 device 中
status = WdfDeviceCreate(&deviceInit, &attributes, &device);

// 使用句柄创建队列
WDFQUEUE queue;
WDF_IO_QUEUE_CONFIG queueConfig;
WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(&queueConfig, WdfIoQueueDispatchParallel);
status = WdfIoQueueCreate(device, &queueConfig, WDF_NO_OBJECT_ATTRIBUTES, &queue);

// 使用句柄创建中断
WDFINTERRUPT interrupt;
WDF_INTERRUPT_CONFIG interruptConfig;
WDF_INTERRUPT_CONFIG_INIT(&interruptConfig, MyEvtInterruptIsr, MyEvtInterruptDpc);
status = WdfInterruptCreate(device, &interruptConfig, WDF_NO_OBJECT_ATTRIBUTES, &interrupt);

2.3 对象上下文空间

每个 WDF 对象都可以关联一个 上下文空间（Context Space），这是驱动为对象分配的私有数据区域。上下文空间的大小和类型在对象创建时通过 WDF_OBJECT_ATTRIBUTES 指定，框架自动分配并清零。

2.3.1 上下文空间的定义与分配

使用 WDF_DECLARE_CONTEXT_TYPE 宏声明上下文结构体，然后在创建对象时关联：

// 定义设备上下文结构体
typedef struct _DEVICE_CONTEXT {
    WDFQUEUE     DefaultQueue;
    WDFINTERRUPT Interrupt;
    WDFDMAENABLER DmaEnabler;
    ULONG        DeviceFlags;
} DEVICE_CONTEXT, *PDEVICE_CONTEXT;

// 声明上下文类型（生成 Get/Set 辅助函数）
WDF_DECLARE_CONTEXT_TYPE(DEVICE_CONTEXT);

// 创建设备时关联上下文
WDF_OBJECT_ATTRIBUTES attributes;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ContextSizeOverride = sizeof(DEVICE_CONTEXT);
attributes.EvtCleanupCallback = MyDeviceCleanup;  // 可选清理回调

WDFDEVICE device;
status = WdfDeviceCreate(&deviceInit, &attributes, &device);

// 获取上下文指针
PDEVICE_CONTEXT devContext = GetDeviceContext(device);
devContext->DeviceFlags = 0x01;

2.3.2 上下文空间的生命周期与访问

2.4 对象生命周期管理

WDF 对象的生命周期由 引用计数 和 父子关系 共同控制。框架自动管理大部分生命周期，但驱动在特定场景下需要主动干预。

2.4.1 生命周期状态机

2.4.2 引用计数与父子关系

框架为每个对象维护内部引用计数。以下情况会增加引用：

• 对象被创建时，父对象持有 1 个引用。
• 驱动调用 WdfObjectReference 显式增加引用（例如将对象指针传递给工作项）。
• 框架内部（如 I/O 队列持有请求对象的引用）自动增加。

引用计数归零时，框架依次调用 EvtCleanupCallback 和 EvtDestroyCallback，然后释放对象内存。

2.4.3 驱动主动干预的场景

2.4.4 生命周期管理代码示例

// 在 EvtCleanupCallback 中释放手动分配的资源
VOID MyDeviceCleanup(WDFOBJECT Object) {
    PDEVICE_CONTEXT devContext = GetDeviceContext(Object);
    
    // 释放手动分配的自旋锁
    if (devContext->Lock) {
        KeReleaseSpinLock(devContext->Lock, devContext->OldIrql);
        ExFreePoolWithTag(devContext->Lock, 'LCKD');
        devContext->Lock = NULL;
    }
    
    // 注意：不要在此处调用 WdfObjectDelete，框架会自动处理子对象
}

// 在异步操作中安全使用对象
VOID MyAsyncWorkItem(_In_ WDFWORKITEM WorkItem) {
    PWORKITEM_CONTEXT workCtx = GetWorkItemContext(WorkItem);
    WDFDEVICE device = workCtx->Device;
    
    // 执行异步操作...
    
    // 操作完成后释放设备引用
    WdfObjectDereference(device);
    WdfObjectDelete(WorkItem);  // 工作项自身清理
}

2.5 本章小结

• 层次结构： WDF 对象以树状组织，父对象控制子对象生命周期，自动清理避免泄漏。
• 句柄： 不透明类型提供类型安全和调试能力，驱动通过句柄与框架交互。
• 上下文空间： 每个对象可关联私有数据，通过 WDF_DECLARE_CONTEXT_TYPE 声明，框架自动管理内存。
• 生命周期： 引用计数 + 父子关系驱动状态机，驱动在 EvtCleanupCallback 中释放手动资源，框架负责最终销毁。