Inflight Trace Recorder (IFR) für die Protokollierung von Traces

Inflight Trace Recorder (IFR) ist ein Ablaufverfolgungsfeature, mit dem ein Ablaufverfolgungsanbieter, z. B. ein Kernelmodustreiber oder ein UMDF-Treiber, einen Satz von Speicherkreispuffern erstellen kann, in denen die neuesten Protokollmeldungen erhalten bleiben. Die Protokollmeldungen können mithilfe eines Debuggers angezeigt werden.

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

Gilt für:

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

So aktivieren Sie den Inflight Trace Recorder in Visual Studio

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

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

Schließlich gibt es für UMDF nur einen zusätzlichen Schritt: Fügen Sie WPP_MACRO_USE_KM_VERSION_FOR_UM=1unter WPP Tracing-Function> und Macro Options-Preprocessor> Definitions hinzu.

Aktivieren des Inflight Trace Recorders von der 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 Parametern für den Inflight Trace Recorder

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 die Anzahl der Seiten fest, um das Standardprotokoll zu speichern. Der Standardwert ist 1.

VerboseOn: REG_DWORD

Die Standardeinstellung null bewirkt, dass der IFR Fehler, Warnungen und Informationsereignisse protokolliert. Setzen Sie den Wert auf eins, 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 mithilfe von !rcdrkd.rcdrlogdump oder !wdfkd.wdflogdump angezeigt werden können.

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

Wenn Sie zusätzlich zu WppRecorder_UseTimeStamp genauere Zeitstempel wünschen, fügen Sie WppRecorder_PreciseTimeStamp mit derselben 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

So senden Sie Ablaufverfolgungsnachrichten an das Standardprotokoll

Folgen Sie den Anweisungen zum Hinzufügen der WPP-Softwareablaufverfolgung zu einem Windows-Treiber. Beispiel:

• Rufen Sie innerhalb von DriverEntry die Funktion WPP_INIT_TRACING(DriverObject, RegistryPath) auf.
• Rufen Sie in EvtDriverUnload auf WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)).

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

Weitere Informationen finden Sie unter WPP_INIT_TRACING und WPP_CLEANUP.

So senden Sie Ablaufverfolgungsnachrichten an ein benutzerdefiniertes Protokoll

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

Bei den meisten Treibern 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 auszugeben.

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

• WppRecorderLogCreate zum Erstellen mehrerer Protokollpuffer
• 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 Trace-Makro 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, aber nicht für andere zu aktivieren.

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

So zeigen Sie Ablaufverfolgungsmeldungen im Debugger an

Verwenden Sie für KMDF- und UMDF-Treiber wie gewohnt !wdfkd.wdflogdump . Es wird sowohl das IFR-Rahmenprotokoll als auch das Treiber-IFR-Protokoll ausdrucken.

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