Verwenden des Inflight Trace Recorder (IFR) in KMDF- und UMDF 2-Treibern
Ab Windows 10 können Sie Ihren KMDF- oder UMDF-Treiber so erstellen, dass er zusätzliche Treiberdebuginformationen über die Vorverarbeitung der Windows-Softwareablaufverfolgung erhält. Dieses Feature, das als Inflight Trace Recorder (IFR) bezeichnet wird, ist ab KMDF-Version 1.15 und UMDF-Version 2.15 verfügbar.
Inflight Trace Recorder ist eine Erweiterung der WPP-Softwareablaufverfolgung. Im Gegensatz zur WPP-Ablaufverfolgung funktioniert der Inflight Trace Recorder weiterhin ohne angefügten Ablaufverfolgungs-Consumer. Das Framework schreibt Nachrichten in einen Kreispuffer, und Ihr Treiber kann auch eigene Nachrichten hinzufügen. Jeder Treiber verfügt über ein eigenes Protokoll, sodass mehrere Geräte, die einem Treiber zugeordnet sind, ein einzelnes Protokoll gemeinsam nutzen.
Wenn Sie den IFR in Ihrer Treiberbinärdatei aktivieren, ist der IFR vorhanden und wird während der Lebensdauer Ihres Treibers ausgeführt. Sie müssen keine explizite Ablaufverfolgungssammlungssitzung starten.
Die Protokolle werden im nicht ausgelagerten Speicher gespeichert, sodass sie nach einem Systemabsturz wiederhergestellt werden können. Darüber hinaus sind Inflight Trace Recorder-Protokolle in Minidump-Dateien enthalten, außer wenn der verantwortliche Treiber nicht festgelegt ist oder wenn der Absturz ein Hosttimeout war.
Aktivieren des Inflight Trace Recorders und Senden von Nachrichten von Ihrem Treiber
Führen Sie in Microsoft Visual Studio die folgenden Schritte aus:
Öffnen Sie die Eigenschaftenseiten für Ihr Treiberprojekt. Klicken Sie mit der rechten Maustaste auf das Treiberprojekt in Projektmappen-Explorer, und wählen Sie Eigenschaften aus. Wählen Sie auf den Eigenschaftenseiten für den Treiber konfigurationseigenschaften und dann Wpp-Ablaufverfolgung aus. Legen Sie im Menü Allgemeindie Option WPP-Ablaufverfolgung ausführen auf Ja fest.
Navigieren Sie zu Eigenschaften-Wpp-Ablaufverfolgungsfunktion>> und Makrooptionen, und wählen Sie WPP-Recorder aktivieren aus.
Legen Sie im selben Menü Konfigurationsdaten überprüfen auf die Datei fest, die Ihre Ablaufverfolgungsinformationen enthält, z. B. Trace.h.
Fügen Sie in jeder Quelldatei, die ein WPP-Makro aufruft, eine #include-Direktive hinzu, die eine TMH-Datei (Trace Message Header) identifiziert. 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 Visual Studio erstellen, generiert der WPP-Präprozessor den . 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.
Das Osrusbfx2-Treiberbeispiel definiert eine einzelne Steuerelement-GUID und sieben Ablaufverfolgungsflags in der Headerdatei Trace.h, wie im folgenden Beispiel gezeigt:
#define WPP_CONTROL_GUIDS \ WPP_DEFINE_CONTROL_GUID(OsrUsbFxTraceGuid, \ (d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \ WPP_DEFINE_BIT(DBG_INIT) /* bit 0 = 0x00000001 */ \ WPP_DEFINE_BIT(DBG_PNP) /* bit 1 = 0x00000002 */ \ WPP_DEFINE_BIT(DBG_POWER) /* bit 2 = 0x00000004 */ \ WPP_DEFINE_BIT(DBG_WMI) /* bit 3 = 0x00000008 */ \ WPP_DEFINE_BIT(DBG_CREATE_CLOSE) /* bit 4 = 0x00000010 */ \ WPP_DEFINE_BIT(DBG_IOCTL) /* bit 5 = 0x00000020 */ \ WPP_DEFINE_BIT(DBG_WRITE) /* bit 6 = 0x00000040 */ \ WPP_DEFINE_BIT(DBG_READ) /* bit 7 = 0x00000080 */ \ )In diesem Beispiel:
- OsrUsbFxTraceGuid ist der Anzeigename für die {d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB}-GUID.
- Die Ablaufverfolgungsflags werden verwendet, um zwischen Ablaufverfolgungsmeldungen zu unterscheiden, die generiert werden, wenn der Treiber verschiedene Arten von E/A-Anforderungen verarbeitet.
Ihr Treiber (sowohl KMDF als auch UMDF 2) muss WPP_INIT_TRACING für Kernel-Mode Drivers mit dem Treiberobjekt und einem Registrierungspfad aufrufen, in der Regel von DriverEntry:
WPP_INIT_TRACING( DriverObject, RegistryPath );Um die Ablaufverfolgung zu deaktivieren, rufen sowohl KMDF- als auch UMDF 2-Treiber WPP_CLEANUP für Kernel-Mode Treiber von EvtCleanupCallback oder EvtDriverUnload auf:
WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));Das makro WPP_CLEANUP nimmt einen Parameter vom Typ PDRIVER_OBJECT an. Wenn also DriverEntry ihres Treibers fehlschlägt, können Sie den Aufruf von WdfDriverWdmGetDriverObject überspringen und stattdessen WPP_CLEANUP mit einem Zeiger auf das WDM-Treiberobjekt aufrufen.
Da UMDF-Treiber die Kernelmodussignaturen dieser Makros zum Initialisieren und Bereinigen der Ablaufverfolgung verwenden, sehen die Aufrufe für KMDF und UMDF identisch aus.
Verwenden Sie das DoTraceMessage-Makro oder eine angepasste Version des Makros in Ihrem Treiber, um Ablaufverfolgungsmeldungen zu erstellen.
Das folgende Beispiel zeigt, wie der Osrusbfx2-Treiber seine TraceEvents-Funktion in einem Teil des Codes verwendet, der für die Verarbeitung von Leseanforderungen bestimmt ist:
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) { TraceEvents(TRACE_LEVEL_ERROR, DBG_READ, "Transfer exceeds %d\n", TEST_BOARD_TRANSFER_BUFFER_SIZE); status = STATUS_INVALID_PARAMETER; }Der Aufruf von TraceEvents generiert eine Ablaufverfolgungsmeldung , wenn der Ablaufverfolgungscontroller die TRACE_LEVEL_ERROR Ebene und das DBG_READ Ablaufverfolgungsflag aktiviert. Die Nachricht enthält den Wert der vom Treiber definierten konstanten TEST_BOARD_TRANSFER_BUFFER_SIZE.
Um die Größe des kreisförmigen Puffers zu ändern, den das Treiberprotokoll verwendet, ändern Sie den Registrierungswert LogPages am folgenden Registrierungsspeicherort:
SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<YourDriver>\Parameters\Wdf
<HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\YourDriver>\Parameters\Wdf
Dies ist ein Wert vom Typ REG_DWORD , der die Größe des zugeordneten Protokollpuffers in Seiten enthält. Gültige Werte liegen zwischen 0x1 und 0x10.
Für einen KMDF-Treiber
- Laden Sie die RCDRKD-Befehle, indem Sie .load rcdrkd.dll in den Debugger eingeben.
- Verwenden Sie die Erweiterung !wdfkd.wdfldr , um Informationen zum Treiber anzuzeigen, die derzeit dynamisch an Windows Driver Frameworks (WDF) gebunden sind.
- Verwenden Sie !rcdrkd.rcdrlogdump und !rcdrkd.rcdrcrashdump , um Meldungen anzuzeigen, die der Treiber bereitstellt.
- Verwenden Sie !wdfkd.wdflogdump oder !wdfkd.wdfcrashdump , um nachrichten anzuzeigen, die das Framework bereitstellt.
Livedebuggen eines UMDF-Treibers
Verwenden Sie die Erweiterung !wdfkd.wdfldr , um Informationen zu den Treibern anzuzeigen, die derzeit dynamisch an WDF gebunden sind. Suchen Sie Ihren Benutzermodustreiber. Geben Sie den zugeordneten Hostprozess ein.
Geben Sie !wdfkd.wdflogdump<YourDriverName.dll><Flag ein> , wobei <Flag> ist:
- 0x1 – Zusammengeführte Framework- und Treiberprotokolle
- 0x2 – Treiberprotokolle
- 0x3 – Frameworkprotokolle
Wenn für den angegebenen Treiber kein Treiberprotokoll vorhanden ist, zeigt die Erweiterung nur das Frameworkprotokoll an.
Anzeigen von Inflight Trace Recorder-Protokollen nach einem Absturz des UMDF-Treibers
Wählen Sie in WinDbg Datei-Absturzabbild> öffnen aus, und geben Sie die Minidumpdatei an, die Sie debuggen möchten.
Geben Sie !wdfkd.wdfcrashdump <YourDriverName.dll><Prozess-ID des Treiberhosts><Option> ein, wobei <Option> wie folgt lautet:
- 0x1 – Zusammengeführte Framework- und Treiberprotokolle
- 0x2 – Treiberprotokolle
- 0x3 – Frameworkprotokolle
Wenn Sie keinen Treiber angeben, zeigt !wdfcrashdump Informationen für alle Treiber an. Wenn Sie keinen Hostprozess angeben und es nur einen gibt, verwendet die Erweiterung den einzelnen Hostprozess. Wenn Sie keinen Hostprozess angeben und es mehrere gibt, listet die Erweiterung die aktiven Hostprozesse auf.
Wenn die im Minidump gespeicherten Protokollinformationen nicht mit dem eingegebenen Namen übereinstimmen, enthält der Minidump nicht die Protokolle des Treibers.
Wenn Kein Debugger verbunden ist, können Sie weiterhin auf die Treiber- und Frameworkprotokolle zugreifen. Weitere Informationen finden Sie unter Video: Zugreifen auf IFR-Treiberprotokolle ohne Debugger.
Weitere Informationen zum Hinzufügen von Ablaufverfolgungsmeldungen zu Ihrem Treiber finden Sie unter Hinzufügen von WPP-Makros zu einem Treiber.
Verwandte Artikel
Aktivieren des Debuggens eines UMDF-Treibers
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für