在 UMDF 驱动程序中使用 WPP 软件跟踪

项目
03/08/2023

WPP 软件跟踪使你能够添加跟踪消息来帮助调试驱动程序。此外，框架的事件记录器还提供数百条可查看的跟踪消息。

可以使用 TraceView 或 Tracelog 查看跟踪消息。还可以将跟踪消息发送到内核调试器。

将跟踪消息添加到驱动程序

若要将跟踪消息添加到基于框架的驱动程序，必须：

将 #include 指令添加到包含任何 WPP 宏的每个驱动程序源文件。此指令必须 (TMH) 文件标识跟踪消息头。文件名的格式必须为 <driver-source-file-name.tmh>。

例如，如果驱动程序包含两个名为 MyDriver1.c 和 MyDriver2.c 的源文件，则 MyDriver1.c 必须包含：

#include "MyDriver1.tmh"

和 MyDriver2.c 必须包含：

#include "MyDriver2.tmh"

在 Microsoft Visual Studio 中生成驱动程序时，WPP 预处理器将生成 .tmh 文件。
在头文件中定义 WPP_CONTROL_GUIDS 宏。此宏为驱动程序的跟踪消息定义 GUID 和跟踪标志。 (对于每个 WDK 基于 UMDF 的示例驱动程序，Internal.h 头文件都包含此宏 )
在驱动程序的 DllMain 例程中包含 WPP_INIT_TRACING 宏。此宏激活驱动程序中的软件跟踪。 (对于每个 WDK 基于 UMDF 的示例驱动程序，DllSup.h 头文件都包含此宏.)
在驱动程序的 DllMain 例程中包含 WPP_CLEANUP 宏。此宏会停用驱动程序中的软件跟踪。 (对于每个 WDK 基于 UMDF 的示例驱动程序，DllSup.h 头文件都包含此宏.)
在驱动程序中使用 DoTraceMessage 宏或宏的自定义版本来创建跟踪消息。 (对于每个 WDK 基于 UMDF 的示例驱动程序，Internal.h 头文件都包含一个自定义的 macro.)
打开驱动程序项目的“属性页”。在“解决方案资源管理器”中右键单击驱动程序项目，并选择“属性” 。在驱动程序的“属性页”中，选择“ 配置属性”，然后选择 “Wpp”。在“ 常规 ”菜单下，将 “运行 WPP 跟踪 ”设置为“是”。在“ 文件选项” 菜单下，还应指定框架的 WPP 模板文件，例如：
```
{km-WdfDefault.tpl}*.tmh
```

有关向驱动程序添加跟踪消息的详细信息，请参阅将 WPP 宏添加到驱动程序。

使用 WPP 软件跟踪的示例驱动程序

WDK 中所有基于 UMDF 的示例驱动程序都提供启用 WPP 软件跟踪的 DllSup.h、Internal.h 和 Sources 文件。其中大多数示例驱动程序还使用自定义宏来创建跟踪消息。

查看驱动程序的跟踪消息

如果已将跟踪消息添加到驱动程序，则驱动程序是跟踪提供程序。可以使用跟踪控制器（如 Tracelog）来控制跟踪会话并创建跟踪日志。可以使用跟踪使用者（如 Tracefmt）查看消息。

有关如何使用软件跟踪工具的详细信息，请参阅软件跟踪工具调查。

查看 UMDF 跟踪日志

UMDF 日志文件位于中 %ProgramData%*\\Microsoft\\WDF。

可以使用 TraceView 或 Tracelog 查看 UMDF 日志文件。这两种工具都需要跟踪消息格式 (TMF) 设置跟踪日志消息格式的文件。 TMF 文件在 WDK 的 \tools\tracing 子目录下可用。 (TraceView 中，UMDF 显示为名称为“UMDF-Framework 跟踪”或“框架跟踪”的命名提供程序，具体取决于 UMDF 版本。)

使用 WDF 验证程序，可以将跟踪消息发送到 UMDF 跟踪日志和内核调试器。 (不应使用 Tracelog 中的 -kd 选项将跟踪消息发送到内核调试器，因为 Tracelog 可能会中断 UMDF.)

还可以使用 ！wmitrace 调试器扩展在调试器中查看跟踪消息：

在 WinDbg 中，附加到承载驱动程序的 WUDFHost 实例。有关详细信息，请参阅如何启用 UMDF 驱动程序的调试。
如果驱动程序使用版本 1.11 或更高版本，并且使用的是 Windows 8 或更高版本中的内核调试器，则可以跳过此步骤。如果驱动程序使用低于 1.11 的 UMDF 版本，请使用 ！wmitrace.tmffile 或 ！wmitrace.searchpath 指定特定于平台的跟踪消息格式 (.tmf) 文件或 .tmf 文件的路径。 .tmf 文件位于 WDK 中特定于平台的子目录中。
使用 ！wmitrace.logdump 命令显示跟踪缓冲区的内容：
```
!wmitrace.logdump WudfTrace
```

控制跟踪消息

可以使用 WDF 验证程序提供的用户界面或通过修改注册表值来控制 UMDF 跟踪消息。应尽可能使用 WDF 验证程序 接口，因为注册表值在 UMDF 的未来版本中可能会更改。此外，不应在 INF 文件或驱动程序代码中访问这些值。

目前，可以修改以下注册表值，这些值位于 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF 注册表项下：

LogEnable 值控制 UMDF 是否为驱动程序创建跟踪日志。如果此值设置为 1，则 UMDF 会创建跟踪日志。
LogLevel 值控制 UMDF 跟踪消息包含的信息量。 LogLevel 的默认值为 3，这会导致 UMDF 跟踪消息包含错误和警告消息。将此值设置为 7 以包含错误和警告消息以及非错误信息性消息。将其设置为 15 以包含 UMDF 能够提供的所有跟踪信息。
LogKd 值控制 UMDF 是否将跟踪消息发送到内核调试器。如果 LogKd 设置为 1，则 UMDF 会将其跟踪消息发送到内核调试器。
LogFlushPeriodSeconds 值指定跟踪消息写入跟踪日志的频率（以秒为单位）。
LogMinidumpType 值包含的标志指定微型转储文件（如果生成）将包含的信息类型。有关这些标志的详细信息，请参阅 MINIDUMP_TYPE 枚举。

你可能会在 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF 注册表项下找到更多注册表值。不应修改这些值。

通过