Verwenden der WPP-Softwareablaufverfolgung in UMDF-Treibern

Artikel
03/08/2023

Mit der WPP-Softwareablaufverfolgung können Sie Ablaufverfolgungsmeldungen hinzufügen, mit denen Sie Ihren Treiber debuggen können. Darüber hinaus stellt die Ereignisprotokollierung des Frameworks Hunderte von Ablaufverfolgungsmeldungen bereit, die Sie anzeigen können.

Sie können Ablaufverfolgungsmeldungen mithilfe von TraceView oder Tracelog anzeigen. Sie können auch Ablaufverfolgungsmeldungen an einen Kerneldebugger senden.

Hinzufügen von Ablaufverfolgungsmeldungen zu Ihrem Treiber

Um Ablaufverfolgungsmeldungen zu Ihrem frameworkbasierten Treiber hinzuzufügen, müssen Sie:

Fügen Sie eine #include-Direktive zu jeder Der Quelldateien Ihres Treibers hinzu, die eines der WPP-Makros enthält. Diese Direktive muss eine TMH-Datei (Trace Message Header) identifizieren. Der Dateiname muss das Format <driver-source-file-name.tmh> aufweisen.

Wenn Ihr Treiber beispielsweise aus zwei Quelldateien namens MyDriver1.c und MyDriver2.c besteht, muss MyDriver1.c Folgendes enthalten:

#include "MyDriver1.tmh"

und MyDriver2.c müssen Folgendes enthalten:

#include "MyDriver2.tmh"

Wenn Sie Ihren Treiber in Microsoft Visual Studio erstellen, generiert der WPP-Präprozessor die TMH-Dateien.
Definieren Sie ein WPP_CONTROL_GUIDS-Makro in einer Headerdatei. Dieses Makro definiert eine GUID und Ablaufverfolgungsflags für die Ablaufverfolgungsmeldungen Ihres Treibers. (Für jeden UMDF-basierten Beispieltreiber des WDK enthält die Headerdatei Internal.h dieses Makro.)
Fügen Sie ein WPP_INIT_TRACING Makro in die DllMain-Routine Ihres Treibers ein. Dieses Makro aktiviert die Softwareablaufverfolgung in Ihrem Treiber. (Für jeden UMDF-basierten Beispieltreiber des WDK enthält die DllSup.h-Headerdatei dieses Makro.)
Fügen Sie ein WPP_CLEANUP-Makro in die DllMain-Routine Ihres Treibers ein. Dieses Makro deaktiviert die Softwareablaufverfolgung in Ihrem Treiber. (Für jeden UMDF-basierten Beispieltreiber des WDK enthält die DllSup.h-Headerdatei dieses Makro.)
Verwenden Sie das DoTraceMessage-Makro oder eine angepasste Version des Makros in Ihrem Treiber, um Ablaufverfolgungsmeldungen zu erstellen. (Für jeden UMDF-basierten Beispieltreiber des WDK enthält die Headerdatei Internal.h ein angepasstes Makro.)
Öffnen Sie die Eigenschaftenseiten für Ihr Treiberprojekt. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf das Treiberprojekt, und wählen Sie Eigenschaften aus. Wählen Sie auf den Eigenschaftenseiten für den Treiber konfigurationseigenschaften und dann Wpp aus. Legen Sie im Menü Allgemeindie Option WPP-Ablaufverfolgung ausführen auf Ja fest. Im Menü Dateioptionen sollten Sie auch die WPP-Vorlagendatei des Frameworks angeben, z. B.:
```
{km-WdfDefault.tpl}*.tmh
```

Weitere Informationen zum Hinzufügen von Ablaufverfolgungsmeldungen zu Ihrem Treiber finden Sie unter Hinzufügen von WPP-Makros zu einem Treiber.

Beispieltreiber, die WPP-Softwareablaufverfolgung verwenden

Alle UMDF-basierten Beispieltreiber im WDK stellen DllSup.h-, Internal.h- und Sources-Dateien bereit, die die WPP-Softwareablaufverfolgung ermöglichen. Die meisten dieser Beispieltreiber verwenden auch ein angepasstes Makro, um Ablaufverfolgungsmeldungen zu erstellen.

Anzeigen der Ablaufverfolgungsmeldungen ihres Treibers

Wenn Sie Ihrem Treiber Ablaufverfolgungsmeldungen hinzugefügt haben, ist der Treiber ein Ablaufverfolgungsanbieter. Sie können einen Ablaufverfolgungscontroller wie Tracelog verwenden, um eine Ablaufverfolgungssitzung zu steuern und ein Ablaufverfolgungsprotokoll zu erstellen. Sie können einen Ablaufverfolgungsconsumer verwenden, z. B. Tracefmt, um die Nachrichten anzuzeigen.

Weitere Informationen zur Verwendung der Softwareablaufverfolgungstools finden Sie unter Survey of Software Tracing Tools( Survey of Software Tracing Tools).

Anzeigen des UMDF-Ablaufverfolgungsprotokolls

Die UMDF-Protokolldatei befindet sich in %ProgramData%*\\Microsoft\\WDF.

Sie können die UMDF-Protokolldatei mit TraceView oder Tracelog anzeigen. Beide Tools erfordern TMF-Dateien (Trace Message Format), die die Nachrichten des Ablaufverfolgungsprotokolls formatieren. Die TMF-Dateien sind im WDK unter dem Unterverzeichnis \tools\tracing verfügbar. (In TraceView wird UMDF je nach UMDF-Version als benannter Anbieter mit dem Namen "UMDF-Framework Trace" oder "Framework Trace" angezeigt.)

Mit WDF Verifier können Sie Ablaufverfolgungsmeldungen sowohl an das UMDF-Ablaufverfolgungsprotokoll als auch an Ihren Kerneldebugger senden. (Sie sollten keine Ablaufverfolgungsmeldungen an Ihren Kerneldebugger senden, indem Sie die Option -kd in Tracelog verwenden, da Tracelog die Ablaufverfolgungsprotokollierung innerhalb von UMDF unterbrechen kann.)

Sie können auch die !wmitrace-Debuggererweiterung verwenden, um die Ablaufverfolgungsmeldungen im Debugger anzuzeigen:

Fügen Sie in WinDbg an die instance von WUDFHost an, die den Treiber hostet. Weitere Informationen finden Sie unter Aktivieren des Debuggens eines UMDF-Treibers.
Wenn Ihr Treiber Version 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 frühere Version von UMDF als 1.11 verwendet, verwenden Sie !wmitrace.tmffile oder !wmitrace.searchpath , um eine plattformspezifische Ablaufverfolgungsnachrichtenformatdatei (TMF) oder einen Pfad zu einer TMF-Datei anzugeben. Die TMF-Dateien befinden sich in plattformspezifischen Unterverzeichnissen im WDK.
Verwenden Sie den Befehl !wmitrace.logdump , um den Inhalt der Ablaufverfolgungspuffer anzuzeigen:
```
!wmitrace.logdump WudfTrace
```

Steuern von Ablaufverfolgungsmeldungen

Sie können UMDF-Ablaufverfolgungsmeldungen über die Benutzeroberfläche von WDF Verifier oder durch Ändern von Registrierungswerten steuern. Sie sollten nach Möglichkeit die WDF Verifier-Schnittstelle verwenden, da sich die Registrierungswerte in zukünftigen Versionen von UMDF ändern können. Darüber hinaus sollten Sie nicht auf diese Werte in INF-Dateien oder im Code Ihres Treibers zugreifen.

Derzeit können Sie die folgenden Registrierungswerte ändern, die sich unter dem Registrierungsschlüssel HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF befinden:

Der Wert LogEnable steuert, ob UMDF ein Ablaufverfolgungsprotokoll für Ihren Treiber erstellt. Wenn dieser Wert auf 1 festgelegt ist, erstellt UMDF ein Ablaufverfolgungsprotokoll.
Der Wert LogLevel steuert die Menge der Informationen, die UMDF-Ablaufverfolgungsmeldungen enthalten. Der Standardwert für LogLevel ist 3, wodurch UMDF-Ablaufverfolgungsmeldungen Fehler- und Warnmeldungen enthalten. Legen Sie diesen Wert auf 7 fest, um Fehlermeldungen und Warnmeldungen sowie Nicht-Fehler-Informationsmeldungen einzuschließen. Legen Sie ihn auf 15 fest, um alle Ablaufverfolgungsinformationen einzuschließen, die UMDF bereitstellen kann.
Der LogKd-Wert steuert, ob UMDF Ablaufverfolgungsmeldungen an Ihren Kerneldebugger sendet. Wenn LogKd auf 1 festgelegt ist, sendet UMDF die Ablaufverfolgungsmeldungen an Ihren Kerneldebugger.
Der Wert LogFlushPeriodSeconds gibt an, wie oft Ablaufverfolgungsmeldungen in Sekunden in das Ablaufverfolgungsprotokoll geschrieben werden.
Der Wert LogMinidumpType enthält Flags, die den Typ der Informationen angeben, die eine Minidumpdatei enthalten soll, wenn sie erstellt wird. Weitere Informationen zu diesen Flags finden Sie in der MINIDUMP_TYPE-Enumeration .

Weitere Registrierungswerte finden Sie unter dem Registrierungsschlüssel HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF . Sie sollten diese Werte nicht ändern.

Freigeben über