通过

用于记录跟踪的飞行中追踪记录器（IFR）

飞行中跟踪记录器（IFR） 是一项追踪功能，允许跟踪提供程序（如内核模式驱动程序或 UMDF 驱动程序）创建一组内存中的循环缓冲区，用以保留最新的日志消息。 可以使用调试器查看日志消息。

IFR 基于 WPP 软件跟踪构建。 IFR 对 WPP 的主要好处是自动启用，无需提前启动跟踪会话。

适用于：

  • 最低 OS：适用于 KMDF 和 WDM 驱动程序开发人员的 Windows 8
  • 最低操作系统：适用于 UMDF 2.15 的 Windows 10 驱动程序开发人员

如何在 Visual Studio 中启用 Inflight 跟踪记录器

首先，按照 将 WPP 软件跟踪添加到 Windows 驱动程序中的步骤进行操作。

接下来，在“项目”属性页的 “配置属性->WPP 跟踪->函数和宏选项->启用内存中跟踪记录器”下，选择“是”。

最后，仅对于 UMDF，还需要一步：在 WPP Tracing>函数和宏选项->预处理器定义下，添加 WPP_MACRO_USE_KM_VERSION_FOR_UM=1。

如何从命令行启用 Inflight 跟踪记录器

如果手动编辑.vcxproj文件，请设置以下条目：

对于 KMDF 或 WDM 驱动程序：

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppKernelMode>true</WppKernelMode>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        ...
    </ClCompile>

对于 UMDF 驱动程序：

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        <WppPreprocessorDefinitions>WPP_MACRO_USE_KM_VERSION_FOR_UM=1</WppPreprocessorDefinitions>
        ...
    </ClCompile>

如何配置 Inflight 跟踪记录器参数

可以通过在驱动程序 的参数键下设置以下可选注册表项来配置 IFR。

使用以下注册表项：

LogPages：REG_DWORD

设置为存储默认日志的页数。 默认值为 1。

VerboseOn：REG_DWORD

默认值为零会导致 IFR 记录错误、警告和信息性事件。 设置为一个，用于向日志添加详细输出。

WppRecorder_UseTimeStamp：REG_DWORD （从 WDK 内部版本 22557 开始提供）

驱动程序将此条目设置为一个，以将时间戳添加到日志条目，然后使用 ！rcdrkd.rcdrlogdump 或 ！wdfkd.wdflogdump 查看这些条目。

WppRecorder_PreciseTimeStamp：REG_DWORD （从 WDK 内部版本 22557 开始提供）

如果想要更精确的时间戳，除了 WppRecorder_UseTimeStamp，还使用上面所示的相同语法添加 WppRecorder_PreciseTimeStamp 。

例子

在以下示例中，添加开始和结束注释之间的行，以将日志页数设置为两个并打开时间戳。

对于内核模式驱动程序：

[IfrSample_Service_Inst] 
DisplayName    = %IfrSample.SvcDesc%
ServiceType    = 1               ; SERVICE_KERNEL_DRIVER
StartType      = 3               ; SERVICE_DEMAND_START
ErrorControl   = 1               ; SERVICE_ERROR_NORMAL
ServiceBinary  = %12%\IfrSample.sys
; =============== START
AddReg = IfrSample_Service_Inst.AddReg
 
[IfrSample_Service_Inst.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

[Strings]
REG_DWORD = 0x00010001

对于 UMDF 驱动程序：

[IfrSampleUm_Install] 
UmdfLibraryVersion=$UMDFVERSION$
ServiceBinary=%13%\IfrSampleUm.dll
; =============== START
AddReg=IfrSampleUm_Install.AddReg
 
[IfrSampleUm_Install.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

如何将跟踪消息发送到默认日志

按照 将 WPP 软件跟踪添加到 Windows 驱动程序中的说明进行操作。 例如：

  • 在 DriverEntry 中，调用 WPP_INIT_TRACING(DriverObject, RegistryPath)。
  • 在 EvtDriverUnload 中，调用 WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver))。

现在，驱动程序可以根据需要免费调用跟踪函数。 例如：TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

有关详细信息，请参阅 WPP_INIT_TRACING 和 WPP_CLEANUP。

如何将跟踪消息发送到自定义日志

这仅适用于内核模式驱动程序（KMDF 或 WDM）。

对于大多数驱动程序，单个默认日志足够好。 但是，在某些情况下，为不同的实体提供单独的日志缓冲区会很有帮助。

例如，编写总线驱动程序时，你可能希望每个子设备都有自己的缓冲区。 然后，可以使用调试器仅导出特定子设备的日志。

若要设置自定义日志，驱动程序必须包含 <WppRecorder.h>。 然后调用以下 API：

驱动程序还需要定义一个新的跟踪宏，该宏将日志句柄作为第一个参数。 有关示例，请参阅 烤箱示例驱动程序。

如何将时间戳信息添加到自定义日志

如果驱动程序调用 WppRecorderLogCreate 来创建其他日志句柄，则可能会为某些日志句柄启用时间戳，但不能为其他日志句柄启用时间戳。

为此，需要为应使用时间戳的每个日志句柄向驱动程序代码添加一行。 有关代码示例，请参阅 WppRecorderLogCreate。

注释

此功能从 WDK 内部版本 22557 开始可用。 有关面向特定版本的信息，请参阅 为不同版本的 Windows 生成驱动程序。

如何在调试器中查看跟踪消息

对于 KMDF 和 UMDF 驱动程序，请像往常一样使用 ！wdfkd.wdflogdump 。 它将输出框架 IFR 日志和驱动程序 IFR 日志。

对于 WDM 驱动程序，请使用 ！rcdrkd.rcdrloglist 和 ！rcdrkd.rcdrlogdump。