WDF模型驱动程序开发

WDF驱动程序开发
1. 引言
设备驱动程序是硬件设备连接到计算机系统的软件接口，任何设备都必须有相应的驱动程序才能在计算机系统上正常工作。设备驱动程序的优劣直接关系到整个系统的性能和稳定性，因此，设计和开发稳定高效的驱动程序具有重要意义。

WDF(Windows Driver Foundation)是微软提出的下一代全新的驱动程序模型，它是在WDM(windows Driver Model)的基础上发展而来的，支持面向对象、事件驱动的驱动程序开发，提供了比WDM更高层次抽象的高度灵活、可扩展、可诊断的驱动程序框架。WDF框架管理了大多数与操作系统相关的交互，实现了公共的驱动程序功能（如电源管理、PnP支持），隔离了设备驱动程序与操作系统内核，降低了驱动程序对内核的影响。

WDF提供了两个框架：KMDF(内核模式驱动程序框架)和UMDF（用户模式驱动程序框架）。本文只介绍KMDF的设计与实现。
 
2. WDF对象模型

KMDF框架支持面向对象、事件驱动的驱动程序模型。它定义了一系列的对象用来表示设备、驱动、中断等，每个对象有对应的属性、方法和事件。驱动程序利用这些方法创建对象、设置属性和响应事件。

框架定义的主要对象有：

WDFDRIVER对象，对应于WDM中的DRIVER_OBJECT。描述驱动在内存中的实例，包括加载的位置、有关的属性和所管理的设备。

WDFDEVICE对象，对应于WDM中的DEVICE_OBJECT。描述由驱动程序管理的单个设备实例，设备可以是命名的也可以是未命名的。用户模式程序可以通过设备接口或设备名称访问设备。WDFDEVICE对象具有丰富的属性，如pnp和电源管理相关的事件处理回调函数(callbacks)。

WDFREQUEST对象，对应于WDM中的IRP，表示一个I/O请求。

WDFQUEUE对象：每个WDFQUEUE对象和一个WDFDEVICE对象关联，描述一个特殊的I/O请求队列。它具有一系列的事件处理回调函数，当I/O请求进入队列时，框架将自动调用驱动程序中对应的callback。

WDFINTERRUPT对象：表示设备中断。驱动程序可以通过WDFINTERRUPT对象的中断使能和禁止事件处理callbacks使能或禁止设备中断；通过ISR和DPCforISR例程处理设备中断。

WDF的对象模型是层次化的模型。WDFDRIVER对象是根对象，其他对象都是它的子对象。对于大多数对象，驱动程序在创建他们的时候可以指定父对象，如果没有指定，则框架默认其父对象为WDFDRIVER对象。

WDF大大简化了WDM中的pnp和电源管理的开发。WDF框架为设备停止、设备删除、电源状态切换等pnp和电源管理事件提供了适合的缺省行为，驱动程序本身不再纠缠于复杂的pnp和电源管理事件处理。此外，WDF还集成了请求队列的支持，一个设备可以有多个请求队列，每个请求队列可以有一种模式。最简单的是 WdfIoQueueDispatchSerial模式，在这种模式下，请求队列将请求串行化后再处理；而WdfIoQueueDispatchParallel模式则自动在每个请求到来时调用相应的回调函数；最后WdfIoQueueDispatchManual模式允许驱动程序手工分发请求，类似于WDM的工作方式。

在WDM驱动程序中，I/O请求的取消是一个复杂难以理解的过程，开发人员必须有对内核深刻的理解才能正确处理I/O请求的取消。WDF框架支持内建的I/O请求取消处理，使得驱动程序处理取消I/O请求的工作大大简化。
 
3. WDF设备驱动程序的结构

与WDM驱动程序一样，WDF驱动程序得标准入口函数是DriverEntry。与WDM不同，WDF的DriverEntry只负责创建和初始化WDFDRIVER对象，告诉WDF框架处理增加新设备连接的回调函数。

NTSTATUS  DriverEntry(PDRIVER_OBJECT DriverObj, PUNICODE_STRING RegistryPath)
{
    NTSTATUS code;
    WDF_DRIVER_CONFIG config;
    WDFDRIVER hDriver;
    // 初始化驱动配置结构，指定设备添加事件callback
    WDF_DRIVER_CONFIG_INIT_NO_CONSTRAINTS(&config, MyEvtDeviceAdd);
    // 创建WDFDRIVER对象
    code = WdfDriverCreate(DriverObj,
        RegistryPath,
        WDF_NO_OBJECT_ATTRIBUTES,
        &config,   // 指向config结构的指针
        NULL);
    return(code);
}

    每当有新设备连接到系统时，WDF框架自动调用EvtDeviceAdd设备添加callback。该回调函数初始化pnp和电源管理相关结构，设置相应的事件处理callbacks，然后创建WDFDEVICE对象和符号连接，初始化请求队列、中断处理等相关结构，设置相应的回调函数。

WDFSTATUS  MyEvtDeviceAdd(WDFDRIVER Driver, PWDFDEVICE_INIT DeviceInit)
{
    WDFSTATUS status = STATUS_SUCCESS;
    WDF_PNPPOWER_EVENT_CALLBACKS pnpPowerCallbacks;
    WDF_OBJECT_ATTRIBUTES objAttributes;
    WDFDEVICE device;
    PMY_DEVICE_CONTEXT devContext;
    WDF_IO_QUEUE_CONFIG ioCallbacks;
    WDF_INTERRUPT_CONFIG interruptConfig;
    // 初始化pnpPowerCallbacks ，设置与PnP和电源管理相关的事件回调函数
    WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
    pnpPowerCallbacks.EvtDevicePrepareHardware = MyEvtPrepareHardware;
    pnpPowerCallbacks.EvtDeviceReleaseHardware = MyEvtReleaseHardware;
    pnpPowerCallbacks.EvtDeviceD0Entry= MyEvtDeviceD0Entry;
    pnpPowerCallbacks.EvtDeviceD0Exit = MyEvtDeviceD0Exit;
    WdfDeviceInitSetPnpPowerEventCallbacks(DeviceInit, pnpPowerCallbacks);
    // 创建设备对象，初始化相关的属性
    WDF_OBJECT_ATTRIBUTES_INIT(&objAttributes);
    WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(&objAttributes,
        MY_DEVICE_CONTEXT);
    // 命名设备
    status = WdfDeviceInitUpdateName(DeviceInit, L"\\device\\WDFDEMO");
    if (!NT_SUCCESS(status))     return(status);
    status = WdfDeviceCreate(&DeviceInit, &objAttributes, &device);
    if ( !NT_SUCCESS(status))     return(status);
    devContext = MyGetContextFromDevice(device);
    devContext->WdfDevice = device;
    // 创建符号连接
    status = WdfDeviceCreateSymbolicLink(device, L"\\DosDevices\\WDFDEMO");
    if (!NT_SUCCESS(status))     return(status);
    // 创建和初始化请求队列
    WDF_IO_QUEUE_CONFIG_INIT(&ioCallbacks, WdfIoQueueDispatchSerial,
        WDF_NO_EVENT_CALLBACK,  WDF_NO_EVENT_CALLBACK);
    ioCallbacks.EvtIoDeviceControl = MyEvtDeviceControlIoctl;
    status = WdfDeviceCreateDefaultQueue(device,&ioCallbacks,
        WDF_NO_OBJECT_ATTRIBUTES,NULL);
    if (!NT_SUCCESS(status))    return(status);
    // 创建和初始化中断对象,MyIsr和MyDpc分别是中断服务例程和DPC例程
    WDF_INTERRUPT_CONFIG_INIT(&interruptConfig, FALSE,  MyIsr, MyDpc);
    interruptConfig.EvtInterruptEnable  = MyEvtInterruptEnable;//中断使能
    interruptConfig.EvtInterruptDisable = MyEvtInterruptDisable;//中断禁止
    status = WdfInterruptCreate(device, &interruptConfig,&objAttributes,
        &devContext->WdfInterrupt);
    return(status);
}

WDF驱动程序下一步的工作就是编写各事件处理回调函数，当相应事件发生时，WDF框架会自动调用指定的回调函数进行处理。其中EvtDevicePrepareHardware回调函数在分配资源的时候被调用，框架将分配给设备的资源传递给回调函数，回调函数保存需要的资源，将共享内存映射到内核虚拟地址空间。与此对应的是EvtDeviceReleaseHardware回调函数，每当设备释放所占用的资源时，框架都将调用它。

EvtDeviceD0Entry 和 EvtDeviceD0Exit事件callbacks则分别在设备即将进入和离开D0电源状态时调用。EvtIoDeviceControl、EvtIoRead、EvtIoWrite等回调函数分别用来处理DeviceControl、Read、Write I/O请求。

当框架获得一个I/O请求时，它首先确定该请求应该放入哪个请求队列。如果驱动程序没有提供指定的队列，WDF框架默认将请求放入缺省请求队列会自动调用对应的回调函数。然后，框架寻找处理该请求的回调函数，如果驱动程序提供了相应的callback，则调用它处理请求。对于没有指定回调函数的I/O请求，WDF调用EvtIoStart回调函数处理。如果EvtIoStart callback也不存在，框架将返回STATUS_NOT_SUPPORTED。

设备中断的管理由EvtInterruptEnable callback、EvtInterruptDisable callback、中断服务例程(ISR)和DpcForISr例程实现。WDF框架在调用EvtDeviceD0Entry callback和注册ISR后，通过调用EvtInterruptEnable回调函数使能设备中断；而EvtInterruptDisable回调函数则在设备离开D0状态，EvtDeviceD0Exit callback调用前获得调用，完成禁止设备中断的工作。此外，中断服务例程和DpcForIsr例程具体完成中断服务的功能，与WDM驱动程序相似。