使用框架的事件记录器

  • 项目

WDF 包含一个内部跟踪记录器，有时称为框架的 未完成记录器 (IFR) 。 WDF 记录器创建一个跟踪日志，其中包含每个 WDF 驱动程序的最近事件历史记录。 跟踪日志通过框架跟踪 I/O 请求数据包的进度， (IRP) ，并通过驱动程序跟踪相应的请求。 每个 Kernel-Mode 驱动程序框架 (KMDF) 和 User-Mode 驱动程序框架 (UMDF) 驱动程序都有自己的日志。

始终启用 WDF 记录器。 对于每个跟踪日志，记录器将事件记录存储在循环内存缓冲区中。 （可选）可以启用详细级别，这会导致事件记录器记录有助于调试驱动程序的其他信息，例如进入或退出内部代码路径的条目。 默认情况下，缓冲区的大小为一个内存页，并且详细级别处于关闭状态。 可以通过在 WdfVerifier 应用程序中调整这些值来更改缓冲区的大小和详细程度。 请注意，启用详细可能会降低系统性能。

可以在交互式调试期间使用 WDF 调试器扩展来查看和保存 WDF 日志。 在调试会话期间查看 WDF 日志：

  1. 加载正确的符号。 可以使用 .symfix+ 调试器命令将 Microsoft 公共符号存储追加到现有符号路径。 公共符号存储包括 WDF 二进制文件的符号。 你可能还希望为驱动程序符号加载符号。

    有关如何获取窗口符号以及如何设置调试器的符号路径的其他信息，请参阅 随 Windows 调试 包一起提供的文档。

  2. 将 Wdfkd.dll 扩展库 加载到调试器中。 如果使用内核调试器，可以使用 .load 命令执行此操作。 若要加载正确版本的 Wdfkd.dll 需要指定 DLL 的完全限定路径。 例如，可以在基于 x86 的调试器主机上使用以下路径：

    .load "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\winext\wdfkd.dll"

    然后，可以使用 ！chain 命令显示所有已加载的扩展来确认是否已加载该扩展。

    有关框架调试器扩展的详细信息，请使用 ！wdfhelp 扩展。 有关内核调试器的详细信息，请参阅 随 Windows 调试 包一起提供的文档。

  3. 如果驱动程序使用框架版本 1.11 或更高版本，并且使用的是 Windows 8 或更高版本中的内核调试器，则可以跳过此步骤。

    如果驱动程序使用的框架版本早于 1.11，请使用 ！wdftmffile 或 ！wdfsearchpath 指定特定于平台的跟踪消息格式 (.tmf) 文件，或 .tmf 文件的路径。 .tmf 文件位于 WDK 中特定于平台的子目录中。

    由于 .tmf 文件特定于版本，因此必须指定一个 .tmf 文件，该文件对应于当前正在运行的框架运行时库的版本。 例如，如果 KMDF 版本 1.9 在主机上运行：

    !wdftmffile c:\WinDDK\<version>\tools\tracing\x86\wdf01009.tmf

    还可以通过设置 TRACE_FORMAT_SEARCH_PATH 环境变量来设置搜索路径。 ！wdftmffile 命令优先于环境变量设置的搜索路径。

    若要验证框架版本号，可以从内核调试器运行 ！wdfldr 调试器扩展命令。

  4. 使用 ！wdflogdump 扩展显示事件记录器记录。 例如，WinDbg 命令窗口的以下屏幕截图显示了 ！wdflogdump 输出的典型示例：

    WinDbg 命令窗口中 ！wdflogdump 扩展输出的屏幕截图。

框架日志中的每一行前面都有一个称为 跟踪消息前缀的字符串。 跟踪记录器将此前缀追加到写入日志的每个消息。 默认情况下，前缀包含一组标准数据元素，但你可以更改默认元素以满足特定要求。 可以通过设置 TRACE_FORMAT_PREFIX 环境变量或使用 ！wdfsettraceprefix 调试器扩展命令来更改 WDF 驱动程序的前缀字符串。

若要设置环境变量，请使用类似于下面的命令：

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

此命令将跟踪消息前缀设置为以下内容：

SourceFile_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime

还可以使用 ！wdflogsave 扩展命令将事件记录器记录保存在可以使用 TraceView 查看的事件跟踪日志 (.etl) 文件中。

有时可以在故障转储上使用 ！wdfcrashdump 调试器扩展，在系统 bug 检查后显示日志信息。 仅当框架可以确定驱动程序导致 bug 检查或已设置驱动程序的 ForceLogsInMiniDump 注册表值时，故障转储中才提供日志信息。

如果在出现 bug 检查时附加了调试器，则可以使用 ！wdfcrashdump 立即查看日志信息，也可以通过加载内存转储文件来查看信息。 由于小型内存转储文件的大小限制，导致崩溃的驱动程序的日志可能不会显示在转储中。

框架可以确定特定驱动程序是否导致以下 bug 检查代码：

从 UMDF 版本 2 开始，UMDF 将 UMDF 跟踪日志 (或 UMDF IFR) 存储在内核非分页内存中。 框架为每个驱动程序主机分配一个 IFR， (Wudfhost) 实例。

有关调试器扩展命令的详细信息，请参阅 基于框架的驱动程序的调试器扩展。