Inflight Trace Recorder (IFR) zum Protokollieren von Ablaufverfolgungen

Artikel
02/07/2024

Inflight Trace Recorder (IFR) ist eine Ablaufverfolgungsfunktion, mit der ein Ablaufverfolgungsanbieter, z. B. ein Kernelmodustreiber oder ein UMDF-Treiber, eine Reihe von In-Memory-Zirkelpuffern erstellen kann, in denen die neuesten Protokollmeldungen beibehalten werden. Die Protokollmeldungen können mithilfe eines Debuggers angezeigt werden.

IFR basiert auf der WPP-Softwareablaufverfolgung. Der Hauptvorteil von IFR gegenüber WPP besteht darin, dass es automatisch aktiviert wird und Sie keine Ablaufverfolgungssitzungen im Voraus starten müssen.

Anwendungsbereich:

Mindestbetriebssystem: Windows 8 für KMDF- und WDM-Treiberentwickler
Mindestbetriebssystem: Windows 10 für UMDF-Treiberentwickler (2.15)

Aktivieren des Inflight-Ablaufverfolgungsrekorders in Visual Studio

Führen Sie zunächst die Schritte unter Hinzufügen der WPP-Softwareablaufverfolgung zu einem Windows-Treiber aus.

Wählen Sie als Nächstes auf der Eigenschaftenseite Project unter Konfigurationseigenschaften-WPP-Ablaufverfolgungsfunktion>> und Makrooptionen-Inflight-Ablaufverfolgungsaufzeichnung> aktivieren die Option Ja aus.

Schließlich gibt es nur für UMDF einen zusätzlichen Schritt: Fügen Sie unter WPP-Ablaufverfolgungsfunktion> und Makrooptionen-Präprozessordefinitionen> hinzuWPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Aktivieren des Inflight Trace Recorders über die Befehlszeile

Wenn Sie die .vcxproj-Datei manuell bearbeiten, legen Sie die folgenden Einträge fest:

Für einen KMDF- oder WDM-Treiber:

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

Für einen UMDF-Treiber:

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

Konfigurieren von Inflight Trace Recorder-Parametern

Sie können den IFR konfigurieren, indem Sie die folgenden optionalen Registrierungseinträge unter dem Parameterschlüssel des Treibers festlegen.

Verwenden Sie die folgenden Registrierungseinträge:

LogPages: REG_DWORD

Legen Sie auf die Anzahl der Seiten fest, die das Standardprotokoll speichern sollen. Der Standardwert ist 1.

VerboseOn: REG_DWORD

Die Standardeinstellung null bewirkt, dass der IFR Fehler, Warnungen und Informationsereignisse protokolliert. Legen Sie diese Einstellung auf eins fest, um dem Protokoll eine ausführliche Ausgabe hinzuzufügen.

WppRecorder_UseTimeStamp: REG_DWORD (ab WDK-Build 22557 verfügbar)

Treiber legen diesen Eintrag auf einen fest, um Zeitstempel zu Protokolleinträgen hinzuzufügen, die dann mit !rcdrkd.rcdrlogdump oder !wdfkd.wdflogdump angezeigt werden können.

WppRecorder_PreciseTimeStamp: REG_DWORD (ab WDK-Build 22557 verfügbar)

Wenn Sie genauere Zeitstempel wünschen, fügen Sie zusätzlich zu WppRecorder_UseTimeStampWppRecorder_PreciseTimeStamp mit der oben gezeigten Syntax hinzu.

Beispiele

Fügen Sie in den folgenden Beispielen die Zeilen zwischen den Anfangs- und Endkommentaren hinzu, um die Anzahl der Protokollseiten auf zwei festzulegen und Zeitstempel zu aktivieren.

Für einen Kernelmodustreiber:

[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

Für einen UMDF-Treiber:

[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

Senden von Ablaufverfolgungsmeldungen an das Standardprotokoll

Befolgen Sie die Anweisungen unter Hinzufügen der WPP-Softwareablaufverfolgung zu einem Windows-Treiber. Beispiel:

Rufen Sie in DriverEntry auf WPP_INIT_TRACING(DriverObject, RegistryPath).
Rufen Sie in EvtDriverUnload auf WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)).

Jetzt kann der Treiber die Ablaufverfolgungsfunktion bei Bedarf aufrufen. Beispiel: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

Weitere Informationen finden Sie unter WPP_INIT_TRACING und WPP_CLEANUP.

Senden von Ablaufverfolgungsmeldungen an ein benutzerdefiniertes Protokoll

Dies gilt nur für Kernelmodustreiber (KMDF oder WDM).

Für die meisten Treiber ist das einzelne Standardprotokoll gut genug. In einigen Szenarien ist es jedoch hilfreich, separate Protokollpuffer für unterschiedliche Entitäten zu verwenden.

Wenn Sie beispielsweise einen Bustreiber schreiben, möchten Sie möglicherweise, dass jedes untergeordnete Gerät über einen eigenen Puffer verfügt. Anschließend können Sie den Debugger verwenden, um nur das Protokoll für ein bestimmtes untergeordnetes Gerät abzuspeichern.

Um benutzerdefinierte Protokolle einzurichten, muss der Treiber enthalten <WppRecorder.h>. Rufen Sie dann die folgenden APIs auf:

WppRecorderLogErstellen , um mehr als einen Protokollpuffer zu erstellen
WppRecorderLogDelete vor dem Aufrufen von WPP_CLEANUP.
WppRecorderLogSetIdentifier zum Festlegen eines Zeichenfolgenbezeichners für ein bestimmtes Aufzeichnungsprotokoll (optional)
WppRecorderConfigure zum Deaktivieren des Standardprotokolls (optional)

Der Treiber muss auch ein neues Ablaufverfolgungsmakro definieren, das das Protokollhandle als ersten Parameter verwendet. Ein Beispiel finden Sie im Toaster-Beispieltreiber.

Hinzufügen von Zeitstempelinformationen zu einem benutzerdefinierten Protokoll

Wenn Ihr Treiber WppRecorderLogCreate aufruft, um zusätzliche Protokollhandles zu erstellen, ist es möglich, Zeitstempel für einige Protokollhandles zu aktivieren, andere jedoch nicht.

Dazu müssen Sie dem Treibercode für jedes Protokollhandle, das Zeitstempel verwenden soll, eine einzelne Zeile hinzufügen. Ein Codebeispiel finden Sie unter WppRecorderLogCreate.

Hinweis

Diese Funktionalität ist ab WDK-Build 22557 verfügbar. Informationen zum Ziel einer bestimmten Version finden Sie unter Erstellen von Treibern für verschiedene Versionen von Windows.

Anzeigen von Ablaufverfolgungsmeldungen im Debugger

Verwenden Sie für KMDF- und UMDF-Treiber wie gewohnt !wdfkd.wdflogdump . Sie druckt sowohl das IFR-Frameworkprotokoll als auch das Treiber-IFR-Protokoll aus.

Verwenden Sie für WDM-Treiber !rcdrkd.rcdrloglist und !rcdrkd.rcdrlogdump.

Freigeben über