Verwenden des Inflight Trace Recorder (IFR) in KMDF- und UMDF 2-Treibern
Ab Windows 10 können Sie Ihren KMDF- oder UMDF-Treiber erstellen, sodass zusätzliche Treiberdebugginginformationen über die Vorverarbeitung der Windows-Softwareablaufverfolgung erhalten. 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 angeschlossenen Trace-Consumer. Das Framework schreibt Nachrichten in einen Zirkelpuffer, 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 freigeben.
Wenn Sie den IFR in Ihrer Treiber-Binä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 die Protokolle der Inflight-Ablaufverfolgungsaufzeichnung in Minidumpdateien enthalten, außer wenn der verantwortliche Treiber nicht bestimmt ist oder wenn der Absturz ein Hosttimeout war.
Aktivieren des Inflight Trace Recorder und Senden von Nachrichten von Ihrem Fahrer
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 die Wpp-Ablaufverfolgung aus. Legen Sie im Menü "Allgemein" "WPP-Ablaufverfolgung ausführen" auf "Ja" fest.
Navigieren Sie zu "Properties-Wpp> Tracing-Function"> und "Makrooptionen" , und wählen Sie "WPP Recorder aktivieren" aus.
Legen Sie im selben Menü Scankonfigurationsdaten 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 über ein Format von <driver-source-file-name.tmh> verfügen.
Wenn Ihr Treiber beispielsweise aus zwei Quelldateien besteht, " MyDriver1.c " und "MyDriver2.c" , muss "MyDriver1.c " Folgendes enthalten:
#include "MyDriver1.tmh"
und MyDriver2.c muss 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 Ablaufverfolgungskennzeichnungen für die Ablaufverfolgungsmeldungen Ihres Treibers.
Das Osrusbfx2-Treiberbeispiel definiert eine einzelne Steuerelement-GUID und sieben Ablaufverfolgungskennzeichnungen 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 GUID "{d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB}".
- Die Ablaufverfolgungskennzeichnungen werden verwendet, um zwischen Ablaufverfolgungsmeldungen zu unterscheiden, die generiert werden, wenn der Treiber verschiedene Arten von E/A-Anforderungen verarbeitet.
Ihr Treiber (KMDF und UMDF 2) muss WPP_INIT_TRACING für Kernelmodustreiber 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 Kernelmodustreiber von EvtCleanupCallback oder EvtDriverUnload auf:
WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));Das WPP_CLEANUP Makro verwendet einen Parameter vom Typ PDRIVER_OBJECT. Wenn der DriverEntry-Fehler des 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 zum Behandeln von Leseanforderungen gewidmet 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 Ablaufverfolgungskennzeichnung aktiviert. Die Nachricht enthält den Wert der vom Treiber definierten Konstanten TEST_BOARD_TRANSFER_BUFFER_SIZE.
Um die Größe des vom Treiberprotokoll verwendeten Zirkelpuffers zu ändern, ä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 auf Seiten enthält. Gültige Werte liegen zwischen 0x1 und 0x10.
Für einen KMDF-Treiber
- Laden Sie die RCDRKD-Befehle, indem Sie im Debugger ".load" rcdrkd.dll eingeben.
- Verwenden Sie die Erweiterung "!wdfkd.wdfldr ", um Informationen zu dem Treiber anzuzeigen, der derzeit dynamisch an Windows Driver Frameworks (WDF) gebunden ist.
- Verwenden Sie "!rcdrkd.rcdrlogdump" und "!rcdrkd.rcdrcrashdump", um Nachrichten anzuzeigen, die der Treiber bereitstellt.
- Verwenden Sie "!wdfkd.wdflogdump" oder "!wdfkd.wdfcrashdump", um Nachrichten anzuzeigen, die das Framework bereitstellt.
Livedebugging 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>>" lautet:
- 0x1 – Zusammengeführtes 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-Ablaufverfolgungsaufzeichnungsprotokollen nach dem Absturz eines UMDF-Treibers
Wählen Sie in WinDbg Datei öffnen> Absturzabbild aus, und geben Sie die Minidumpdatei an, die Sie debuggen möchten.
Geben Sie !wdfkd.wdfcrashdump <YourDriverName.dll><Prozess-ID der Treiberhostoption><> ein, wobei <Option> folgendes ist:
- 0x1 – Zusammengeführtes 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 mehrere vorhanden sind, werden in der Erweiterung die aktiven Hostprozesse aufgelistet.
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. Informationen dazu finden Sie im 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
So aktivieren Sie das Debuggen eines UMDF-Treibers