📚 课程目录第4章第一个驱动程序

4、第一个驱动程序：编写最简单的KMDF驱动框架、DriverEntry和DriverUnload例程、编译、安装、加载与卸载驱动、查看调试输出

从零开始编写一个可加载、可卸载、可观察调试输出的KMDF（Kernel-Mode Driver Framework）驱动，是Windows驱动开发入门的第一道门槛。很多初学者在掌握了C语言和Windows内核基础概念后，仍然会被“驱动工程结构如何搭建”“为什么我的驱动无法加载”“调试输出去哪里看”等问题卡住。本章将围绕一个最小可运行的KMDF驱动，完整拆解驱动框架的骨架、DriverEntry与DriverUnload的职责、编译环境配置、INF安装文件编写、驱动的加载与卸载操作，以及如何通过调试器或工具捕获驱动输出。通过本章的学习，你将建立起对Windows驱动开发全流程的直观认知，为后续处理IRP、IOCTL、即插即用事件等复杂主题打下坚实基础。

上图展示了KMDF最小驱动从入口到卸载的完整生命周期。DriverEntry是驱动被加载时内核调用的第一个函数，它负责创建WDFDRIVER对象并注册卸载回调；WDFDRIVER对象是框架驱动的根句柄，所有后续的设备对象、队列对象都挂接在其下；当驱动被停止或系统关闭时，框架会调用注册的EvtDriverUnload回调执行清理。编译、安装、加载、调试输出则构成了驱动开发的外围工程链路。下面我们逐一深入。

4.1 核心原理：KMDF驱动的最小骨架

KMDF（Kernel-Mode Driver Framework）是微软提供的内核模式驱动框架，它封装了WDM（Windows Driver Model）中大量重复性的即插即用、电源管理、IO请求处理逻辑。一个最小的KMDF驱动，本质上只需要两个函数：DriverEntry（入口点）和EvtDriverUnload（卸载回调）。但要注意，KMDF驱动并不直接导出DriverUnload符号，而是通过WdfDriverCreate注册一个EvtDriverUnload回调函数，由框架在合适的时机调用。

DriverEntry的签名固定为：

NTSTATUS
DriverEntry(
    _In_ PDRIVER_OBJECT  DriverObject,
    _In_ PUNICODE_STRING RegistryPath
)

其中DriverObject是内核为每个驱动创建的驱动对象，RegistryPath指向驱动在注册表中的服务键路径。在KMDF中，DriverEntry的核心任务只有两件：调用WdfDriverCreate创建框架驱动对象，以及（可选）注册卸载回调。WdfDriverCreate的原型如下：

NTSTATUS WdfDriverCreate(
    _In_  PDRIVER_OBJECT        DriverObject,
    _In_  PCUNICODE_STRING      RegistryPath,
    _In_  PWDF_DRIVER_CONFIG    DriverConfig,
    _In_  PWDF_OBJECT_ATTRIBUTES DriverAttributes,
    _Out_ WDFDRIVER*            Driver
);

WDF_DRIVER_CONFIG结构体通过WDF_DRIVER_CONFIG_INIT宏初始化，其中可以指定EvtDriverUnload回调。如果不需要卸载清理，也可以不注册，但强烈建议注册以释放任何手动分配的资源。

关键点：KMDF驱动不直接处理IRP（IO请求包），而是通过框架提供的EvtIo*回调来处理。因此最小驱动甚至可以不实现任何设备控制回调，仅作为“空壳”驱动验证加载链路。

4.2 操作流程：编写、编译、安装、加载与卸载

下面我们通过一个完整的实操流程，从零创建一个名为“FirstKmdf”的最小驱动。

4.2.1 编写驱动源码

在Visual Studio中创建“Kernel Mode Driver, Empty (KMDF)”项目，然后添加一个C文件，输入以下代码：

#include <ntddk.h>
#include <wdf.h>

DRIVER_INITIALIZE DriverEntry;
EVT_WDF_DRIVER_UNLOAD FirstKmdf_EvtDriverUnload;

NTSTATUS
DriverEntry(
    _In_ PDRIVER_OBJECT  DriverObject,
    _In_ PUNICODE_STRING RegistryPath
)
{
    WDF_DRIVER_CONFIG config;
    NTSTATUS status;

    DbgPrint("FirstKmdf: DriverEntry called.\n");

    WDF_DRIVER_CONFIG_INIT(&config, FirstKmdf_EvtDriverUnload);

    status = WdfDriverCreate(DriverObject,
                             RegistryPath,
                             &config,
                             WDF_NO_OBJECT_ATTRIBUTES,
                             WDF_NO_HANDLE);
    if (!NT_SUCCESS(status)) {
        DbgPrint("FirstKmdf: WdfDriverCreate failed 0x%x\n", status);
        return status;
    }

    DbgPrint("FirstKmdf: Driver loaded successfully.\n");
    return STATUS_SUCCESS;
}

VOID
FirstKmdf_EvtDriverUnload(
    _In_ WDFDRIVER Driver
)
{
    UNREFERENCED_PARAMETER(Driver);
    DbgPrint("FirstKmdf: Driver unload called.\n");
}

这段代码展示了最小驱动的全部逻辑。注意WDF_NO_HANDLE表示我们不关心返回的驱动句柄，但实际项目中通常需要保存该句柄供后续使用。

4.2.2 编译配置

编译前需要确保安装了正确的WDK（Windows Driver Kit）版本，并在项目属性中设置：

目标平台：选择“Desktop”或“Universal”，根据目标系统决定。
目标操作系统版本：选择Windows 10/11对应版本。
平台工具集：选择“Visual Studio 2022 (v143)”或对应版本。
链接器输入：确保包含WdfDriverEntry.lib（KMDF库的导入库）。

编译成功后，会生成FirstKmdf.sys文件，同时项目会自动生成一个FirstKmdf.inf文件（如果项目模板包含INF）。对于最小驱动，INF文件是必需的，因为Windows需要INF来安装驱动服务。

4.2.3 编写INF文件

INF文件是驱动安装的“配方”。一个最小KMDF驱动的INF文件如下：

[Version]
Signature   = "$WINDOWS NT$"
Class       = "System"
ClassGuid   = {4d36e97d-e325-11ce-bfc1-08002be10318}
Provider    = %ProviderName%
DriverVer   = 06/01/2024,1.0.0.0
CatalogFile = FirstKmdf.cat

[DestinationDirs]
DefaultDestDir = 12

[DefaultInstall]
CopyFiles = FirstKmdf.CopyFiles

[FirstKmdf.CopyFiles]
FirstKmdf.sys = 0x10

[DefaultInstall.Services]
AddService = FirstKmdf,0x00000002,FirstKmdf.ServiceInstall

[FirstKmdf.ServiceInstall]
DisplayName   = %ServiceName%
ServiceType   = 1
StartType     = 3
ErrorControl  = 1
ServiceBinary = %12%\FirstKmdf.sys

[Strings]
ProviderName = "MyCompany"
ServiceName  = "FirstKmdf"

这个INF文件将驱动安装为“系统类”服务，启动类型为“按需启动”（StartType=3），即手动加载。注意ServiceBinary指向%12%（即系统驱动目录%SystemRoot%\System32\drivers）。

4.2.4 安装驱动

安装驱动有两种常用方式：使用devcon工具或通过设备管理器。对于非PNP驱动（即没有硬件ID的驱动），推荐使用devcon：

devcon install FirstKmdf.inf Root\FirstKmdf

该命令会在“根枚举”下创建一个虚拟设备节点，并加载驱动。如果安装成功，可以在设备管理器的“系统设备”下看到“FirstKmdf”设备。

4.2.5 加载与卸载驱动

安装后，驱动服务已经创建，但尚未启动。使用sc命令控制服务：

sc start FirstKmdf
sc stop FirstKmdf
sc delete FirstKmdf

当执行sc start时，内核会加载FirstKmdf.sys并调用DriverEntry；执行sc stop时，框架会调用EvtDriverUnload回调，然后卸载驱动。注意：如果驱动创建了设备对象，停止服务前需要先删除设备或使用devcon remove。

经验提示：在开发调试阶段，建议将INF中的StartType设为3（手动），避免系统启动时自动加载导致无法更新驱动文件。每次重新编译后，需要先停止服务、替换sys文件、再启动服务。

4.3 查看调试输出

驱动中的DbgPrint输出不会显示在控制台，需要通过调试器或工具捕获。最常用的两种方式：

4.3.1 使用WinDbg调试器

WinDbg是Windows内核调试的标准工具。连接内核调试会话后，使用ed nt!Kd_DEFAULT_MASK 0xffffffff开启所有调试输出，然后执行g继续运行。当驱动加载时，WinDbg的“Debug Output”窗口会显示DbgPrint的内容。

4.3.2 使用DbgView工具

DbgView（DebugView）是Sysinternals出品的轻量级调试输出捕获工具。以管理员身份运行DbgView，勾选“Capture Kernel”菜单，即可捕获内核模式的DbgPrint输出。DbgView不需要连接调试器，非常适合快速验证驱动输出。

风险警告：DbgPrint在Release构建中默认被编译掉（除非定义DBG=1）。如果使用Release配置编译，需要确保项目属性中“C/C++ → Preprocessor → Preprocessor Definitions”包含DBG=1，否则看不到任何输出。

4.4 案例拆解：一次完整的驱动加载与排障

下面通过一个实际案例，展示从编译到调试输出的完整闭环，以及常见的排障过程。

场景：某学员在Windows 11 22H2系统上编译了上述FirstKmdf驱动，使用devcon install安装后，执行sc start FirstKmdf返回错误“系统找不到指定的文件”。

分析过程：

首先检查FirstKmdf.sys是否存在于C:\Windows\System32\drivers目录。发现文件不存在，说明INF中的CopyFiles指令没有生效。
检查INF文件中的DestinationDirs段，发现DefaultDestDir = 12，而12对应的正是%SystemRoot%\System32\drivers，理论上正确。
进一步检查发现，devcon install命令执行时没有使用管理员权限，导致文件复制被拒绝。重新以管理员身份运行命令提示符，再次执行安装，文件成功复制。
再次执行sc start FirstKmdf，返回成功。使用DbgView捕获到输出：FirstKmdf: DriverEntry called.和FirstKmdf: Driver loaded successfully.
执行sc stop FirstKmdf，DbgView显示FirstKmdf: Driver unload called.，驱动正常卸载。

结果对比：修复前驱动无法加载，修复后加载、卸载均正常，调试输出完整。此案例说明，驱动安装失败时，优先检查文件是否复制到位、服务路径是否正确、是否以管理员权限操作。

复盘要点：驱动开发中90%的“加载失败”问题并非代码逻辑错误，而是文件路径、权限、INF配置或签名问题。遇到错误时，先检查系统事件查看器（Event Viewer）中的“System”日志，其中会记录驱动加载失败的具体原因。

4.5 常见误区与总结

初学者在编写第一个KMDF驱动时，常犯以下错误：

误区	后果	正确做法
忘记调用WdfDriverCreate	驱动加载后立即崩溃或无法创建设备	DriverEntry中必须调用WdfDriverCreate
在DriverUnload中释放框架管理的对象	双重释放导致蓝屏	框架对象由框架自动清理，只需释放手动分配的资源
使用Release配置编译但未定义DBG	DbgPrint无输出	在Release中定义DBG=1或使用WPP跟踪
INF中StartType设为0（自动启动）	驱动在系统启动时加载，更新困难	开发阶段使用StartType=3
忽略签名要求	64位系统默认拒绝加载未签名驱动	开启测试签名模式或使用WHQL签名

总结本章，编写第一个KMDF驱动的核心步骤可以归纳为：写代码 → 编译 → 写INF → 安装 → 加载 → 调试。DriverEntry负责初始化框架驱动对象，EvtDriverUnload负责清理，DbgPrint是观察驱动行为的“眼睛”。掌握这一最小闭环后，后续添加设备对象、IO队列、电源管理等功能时，只需在现有骨架上逐步扩展即可。

重要提醒：在64位Windows系统上，所有内核驱动必须经过数字签名才能加载。开发调试阶段，可以在管理员命令提示符中执行bcdedit /set testsigning on开启测试签名模式，然后重启系统。切勿在生产环境关闭签名强制。