如何使用 KMDF 日志

Updated: June 19, 2007

内核模式驱动程序框架 (KMDF) 包括一个基于 Windows 软件跟踪预处理器 (WPP) 的内部跟踪记录程序。KMDF 记录程序为每个 KMDF 驱动程序创建一个包含最近的事件历史的跟踪日志。跟踪日志通过框架跟踪 I/O 请求包 (IRP) 的过程，通过驱动程序跟踪相应的请求。每个 KMDF 驱动程序都有其自己的日志。

您可以使用 WDF 调试器扩展在交互式调试期间查看和保存 KMDF 日志。您还可以让日志成为小型内存转储的一部分，从而可以在崩溃之后检查日志的内容。数据以二进制格式存储，所以它使故障转储文件增加的大小通常只有 10 至 20 KB。

在调试期间查看 KMDF 日志

要在调试会话期间查看 KMDF 日志：

如果您尚未加载 KMDF 调试器扩展，那么加载它。

为 KMDF TMF 文件设置搜索路径。
文件被命名为 Wdf版本号.tmf，位于 %wdk%\WDK版本号\tools\tracing\Architecture。要设置搜索路径，请运行 !wdftmffile 调试器扩展命令，后面紧跟包含 TMF 文件的文件夹路径。下面的例子为运行 32 位版本 Windows 的计算机设置 TMF 文件的搜索路径（WDF 版本 1.5，来自编译号为 6000 的 WDK）：

!wdftmffile%wdk%\6000\tools\tracing\i386\wdf01005.tmf \

您也可以通过设置 TRACE_FORMAT_SEARCH_PATH 环境变量来设置搜索路径。!wdftmffile 命令优于通过环境变量设置的搜索路径。

通过运行 !wdflogdump 调试器扩展命令（附加上您的驱动程序名称）在命令窗口中显示日志文件的内容。不要包含 .sys 扩展名。例如，要转储 Osrusbfx2 的 KMDF 日志，请运行下列命令：

!wdflogdump osrusbfx2

图 1 是 WinDbg 命令窗口的屏幕快照，显示 !wdflogdump 的输出的一个典型例子。

图 1. KMDF 日志

您可以按如下方式使用 !wdflogsave 命令将 KMDF 日志的内容保存到文件：

!wdflogsave [DriverName [FileName]]

使用驱动程序的名称替代 DriverName。名称不得包含 .sys 扩展名。替换 FileName 来指定日志文件的名称。不要包含 .etl 扩展名。如果忽略 FileName，那么日志被写到 DriverName.etl。

Top of page

在进行错误检查后获取日志信息

在系统进行错误检查后，有时您可以使用 !wdfcrashdump 命令来显示 KMDF 日志信息。只有在 KMDF 可以确定是您的驱动程序导致错误检查时或者如果您为驱动程序设置了 ForceLogsInMiniDump 注册表值时日志信息才可用。如果在错误检查发生时连接了调试器，那么您可以使用 !wdfcrashdump 调试器扩展来立即查看 KMDF 日志信息。否则，通过加载内存转储文件来查看信息。

KMDF 可以确定特定的驱动程序是否导致下列错误检查码：

代码	值
DRIVER_IRQL_NOT_LESS_OR_EQUAL	0xD1
IRQL_NOT_LESS_OR_EQUAL	0xA
KERNEL_APC_PENDING_DURING_EXIT	0x20
KERNEL_MODE_EXCEPTION_NOT_HANDLED	0x8E
KMODE_EXCEPTION_NOT_HANDLED	0x1E
PAGE_FAULT_IN_NONPAGED_AREA	0x50
SYSTEM_THREAD_EXCEPTION_NOT_HANDLED	0x7E

要将 KMDF 日志信息包含到系统的小型内存转储中，请使用 RegEdit 修改驱动程序设置，它被定义为驱动程序的 Parameters\Wdf 子项的值。驱动程序的项按照驱动程序来命名，Wdf 子项的完整路径是：

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
\驱动程序名称\Parameters\Wdf

要使得系统将 KMDF 日志信息包含在小型内存转储中，请将 Wdf 子项的 ForceLogsInMiniDump 值设置为一个非零值。

控制 KMDF 日志的内容

您可以控制 KMDF 日志的几个方面：

•	日志大小。
•	写到日志中的信息等级。
•	添加到写到日志中的消息的前缀字符串。

日志大小

可以通过设置驱动程序的 Parameters\Wdf 注册表子项的 LogPages 值来指定框架分配给日志程序的内存页数目。您可以将 LogPages 设置为一个 1 至 10 的值，这表示分配给日志程序的内存页的数目。如果不为 LogPages 指定任何值，那么 KMDF 使用默认值（一个内存页）。

注意：LogPages 值是一个请求，并不是必需的。因为小型故障转储文件的大小有所限制，所以如果日志太大，操作系统可能忽略 KMDF 日志数据。

信息等级

可以通过设置驱动程序的 Parameters\Wdf 注册表子项中的 VerboseOn 值来改变写入 KMDF 日志文件的信息量。VerboseOn 非零值会使框架在日志中记录详细的、开发人员等级的信息。您只应该在开发和调试驱动程序期间设置 VerboseOn，因为该设置会降低性能。

前缀字符串

KMDF 日志中的每行前面都有一个字符串，称为跟踪消息前缀。跟踪记录程序将这个前缀添加到写到日志中的每条消息前。默认情况下，前缀包括一个标准的数据元素集，但是您可以更改默认元素来满足您特定的要求。

前缀内容由一个格式字符串（与 printf 语句中使用的格式字符串有点相似）指定。跟踪前缀字符串的格式由 Windows 跟踪工具定义，在“跟踪消息前缀”（在 Windows Driver Kit (WDK) 的“驱动程序开发工具”部分中）中阐述。

可以设置 TRACE_FORMAT_PREFIX 环境变量或使用 !wdfsettraceprefix 调试器扩展命令更改 KMDF 驱动程序的前缀字符串。设置 TRACE_FORMAT_PREFIX 允许您控制 ETW 捕获的标准信息（例如行、函数名、模块名等）的格式。前缀内容由一个格式字符串（与 printf 语句中使用的格式字符串相似）指定。关于如何构建格式字符串的详细信息，请参见“跟踪消息前缀”（在 WDK 中）。

可以设置 TRACE_FORMAT_PREFIX 环境变量或使用 !wdfsettraceprefix 调试器扩展命令更改 KMDF 驱动程序的前缀字符串。

要设置环境变量，请使用如下所示的命令：

Set TRACE_FORMAT_PREFIX=%2!s!:%!FUNC!:%8!04x!.%3!04x!:%4!s!:

这个命令将跟踪消息前缀设置为如下形式：

源文件_行号:函数名:进程 ID.线程 ID:系统时间

要在调试期间设置格式字符串，请使用 !wdfsettraceprefix 调试器扩展：

!wdfkd.wdfsettraceprefix 前缀字符串

下面的例子设置与前面的环境变量相同的字符串：

!wdfkd.wdfsettraceprefix %2!s!:%!FUNC!:%8!04x!.%3!04x!:%4!s!:

您应该做什么？

•	使用 KMDF 日志帮助查找 KMDF 驱动程序中的错误。
•	如果您的驱动程序导致了错误检查，那么启用 ForceLogsInMiniDumps 注册表设置将 KMDF 日志信息包含在故障转储中。使用 !wdfcrashdump 调试器扩展显示日志信息。
•	使用最新的 WDK 发布版中提供的调试器扩展。