用于记录跟踪的 inflight 跟踪记录器 (IFR)

项目
02/06/2024

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

IFR 基于 WPP 软件跟踪构建。与 WPP 不同，IFR 的主要优点是它会自动打开，无需提前启动跟踪会话。

适用于：

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

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

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

接下来，在“项目属性”页的 “配置属性”->“WPP Trace-Function>”和“宏选项”->“启用飞行跟踪记录器”下，选择“ 是”。

最后，仅对于 UMDF，还有一个额外的步骤：在 WPP 跟踪函数>和宏选项预>处理器定义下，添加 WPP_MACRO_USE_KM_VERSION_FOR_UM=1。

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

如果手动编辑.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>

如何配置机上跟踪记录器参数

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

使用以下注册表项：

LogPages：REG_DWORD

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

VerboseOn：REG_DWORD

默认设置为零会导致 IFR 记录错误、警告和信息性事件。设置为 1 以将详细输出添加到日志。

WppRecorder_UseTimeStamp：从 WDK 内部版本 22557) 开始提供REG_DWORD (

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

WppRecorder_PreciseTimeStamp：从 WDK 内部版本 22557) 开始提供REG_DWORD (

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

示例

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

对于内核模式驱动程序：

[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 以创建多个日志缓冲区
调用 WPP_CLEANUP 之前，WppRecorderLogDelete。
WppRecorderLogSetIdentifier 为给定记录器日志设置字符串标识符 (可选)
WppRecorderConfigure 禁用默认日志 (可选)

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

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

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

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

注意

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

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

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

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