Verwenden der Ereignisprotokollierung des Frameworks

  • Artikel

WDF enthält eine interne Ablaufverfolgungsprotokollierung, die manchmal auch als In-Flight Recorder (IFR) des Frameworks bezeichnet wird. Die WDF-Protokollierung erstellt ein Ablaufverfolgungsprotokoll, das einen aktuellen Ereignisverlauf für jeden WDF-Treiber enthält. Die Ablaufverfolgungsprotokolle verfolgen den Fortschritt von E/A-Anforderungspaketen (IRPs) über das Framework und die entsprechenden Anforderungen über einen Treiber. Jeder Kernel-Mode Driver Framework (KMDF) und User-Mode Driver Framework (UMDF) Treiber verfügt über ein eigenes Protokoll.

Die WDF-Protokollierung ist immer aktiviert. Für jedes Ablaufverfolgungsprotokoll speichert die Protokollierung Ereignisdatensätze in einem kreisförmigen Speicherpuffer. Optional können Sie Ausführlichkeit aktivieren, was dazu führt, dass die Ereignisprotokollierung zusätzliche Informationen aufgibt, die Ihnen beim Debuggen Des Treibers helfen können, z. B. Einträge in oder Ausgänge aus internen Codepfaden. Standardmäßig beträgt die Größe des Puffers eine Speicherseite, und die Ausführlichkeit ist deaktiviert. Sie können die Größe und Ausführlichkeit des Puffers ändern, indem Sie diese Werte in der WdfVerifier-Anwendung anpassen. Beachten Sie, dass das Aktivieren von Ausführlichkeit die Systemleistung beeinträchtigen kann.

Sie können WDF-Debuggererweiterungen verwenden, um das WDF-Protokoll während des interaktiven Debuggens anzuzeigen und zu speichern. So zeigen Sie das WDF-Protokoll während einer Debugsitzung an:

  1. Laden Sie die richtigen Symbole. Sie können den Debuggerbefehl .symfix+ verwenden, um den öffentlichen Microsoft-Symbolspeicher an Ihren vorhandenen Symbolpfad anzufügen. Der öffentliche Symbolspeicher enthält Symbole für die WDF-Binärdateien. Möglicherweise möchten Sie auch Symbole für Ihre Treibersymbole laden.

    Weitere Informationen zum Abrufen von Fenstersymbolen und zum Festlegen des Symbolpfads des Debuggers finden Sie in der Dokumentation, die mit dem Windows-Debugpaket bereitgestellt wird.

  2. Laden Sie die Wdfkd.dll-Erweiterungsbibliothek in Ihren Debugger. Wenn Sie den Kerneldebugger verwenden, können Sie dazu den Befehl .load verwenden. Um die richtige Version von Wdfkd.dll müssen Sie den vollqualifizierten Pfad zur DLL angeben. Beispielsweise würden Sie den folgenden Pfad auf einem x86-basierten Debuggerhostcomputer verwenden:

    .load "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\winext\wdfkd.dll"

    Sie können dann bestätigen, dass die Erweiterung geladen wurde, indem Sie den Befehl !chain verwenden, um alle geladenen Erweiterungen anzuzeigen.

    Weitere Informationen zur Frameworkdebuggererweiterung finden Sie mithilfe der Erweiterung !wdfhelp . Weitere Informationen zum Kerneldebugger finden Sie in der Dokumentation, die mit dem Windows-Debugpaket bereitgestellt wird.

  3. Wenn Ihr Treiber Frameworkversion 1.11 oder höher verwendet und Sie den Kerneldebugger von Windows 8 oder höher verwenden, können Sie diesen Schritt überspringen.

    Wenn Ihr Treiber eine Frameworkversion verwendet, die älter als 1.11 ist, verwenden Sie !wdftmffile oder !wdfsearchpath , um eine plattformspezifische Ablaufverfolgungsnachrichtenformatdatei (TMF) oder einen Pfad zu einer TMF-Datei anzugeben. Die TMF-Dateien befinden sich in plattformspezifischen Unterverzeichnissen im WDK.

    Da TMF-Dateien versionsspezifisch sind, müssen Sie eine TMF-Datei angeben, die der Version der derzeit ausgeführten Laufzeitbibliothek des Frameworks entspricht. Beispiel: Wenn KMDF-Version 1.9 auf dem Hostcomputer ausgeführt wird:

    !wdftmffile c:\WinDDK\<version>\tools\tracing\x86\wdf01009.tmf

    Sie können den Suchpfad auch festlegen, indem Sie die Umgebungsvariable TRACE_FORMAT_SEARCH_PATH festlegen. Der Befehl !wdftmffile hat Vorrang vor dem Suchpfad, der von der Umgebungsvariablen festgelegt wird.

    Um die Versionsnummer des Frameworks zu überprüfen, können Sie den Befehl !wdfldr debugger extension über den Kerneldebugger ausführen.

  4. Verwenden Sie die Erweiterung !wdflogdump , um die Datensätze der Ereignisprotokollierung anzuzeigen. Der folgende Screenshot eines WinDbg-Befehlsfensters zeigt beispielsweise ein typisches Beispiel für die Ausgabe von !wdflogdump:

    Screenshot der Ausgabe der Erweiterung

Jeder Zeile im Frameworkprotokoll wird eine Zeichenfolge vorangestellt, die als Präfix für Ablaufverfolgungsnachrichten bezeichnet wird. Die Ablaufverfolgungsprotokollierung stellt dieses Präfix jeder Nachricht voran, die in das Protokoll geschrieben wird. Standardmäßig enthält das Präfix einen Standardsatz von Datenelementen, aber Sie können die Standardelemente entsprechend Ihren spezifischen Anforderungen ändern. Sie können die Präfixzeichenfolge für einen WDF-Treiber ändern, indem Sie die TRACE_FORMAT_PREFIX Umgebungsvariable festlegen oder den Befehl !wdfsettraceprefix für die Debuggererweiterung verwenden.

Verwenden Sie einen Befehl ähnlich dem folgenden, um die Umgebungsvariable festzulegen:

Set TRACE_FORMAT_PREFIX=%2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:

Dieser Befehl legt das Präfix der Ablaufverfolgungsnachricht auf Folgendes fest:

SourceFile_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime

Sie können auch den Erweiterungsbefehl !wdflogsave verwenden, um die Datensätze der Ereignisprotokollierung in einer Etl-Datei (Ereignisablaufverfolgungsprotokoll) zu speichern, die Sie mithilfe von TraceView anzeigen können.

Manchmal können Sie die Debuggererweiterung !wdfcrashdump in einem Absturzabbild verwenden, um Protokollinformationen nach den Systemfehlerüberprüfungen anzuzeigen. Die Protokollinformationen sind im Absturzabbild nur verfügbar, wenn das Framework feststellen kann, dass Ihr Treiber die Fehlerprüfung verursacht hat, oder wenn Sie den Registrierungswert ForceLogsInMiniDump für den Treiber festgelegt haben.

Wenn bei der Fehlerüberprüfung ein Debugger angefügt wird, können Sie entweder !wdfcrashdump verwenden, um die Protokollinformationen sofort anzuzeigen, oder Sie können die Informationen anzeigen, indem Sie die Speicherabbilddatei laden. Aufgrund der Größenbeschränkungen einer kleinen Speicherabbilddatei wird das Protokoll für den Treiber, der den Absturz verursacht hat, möglicherweise nicht im Speicherabbild angezeigt.

Das Framework kann bestimmen, ob ein bestimmter Treiber die folgenden Fehlerprüfungscodes verursacht hat:

Ab UMDF Version 2 speichert UMDF das UMDF-Ablaufverfolgungsprotokoll (oder UMDF IFR) im kernelfreien Speicher. Das Framework weist einen IFR pro Treiberhost (Wudfhost) instance zu.

Weitere Informationen zu den Debuggererweiterungsbefehlen finden Sie unter Debuggererweiterungen für Framework-basierte Treiber.