Registrierungswerte zum Debuggen von WDF-Treibern
In diesem Artikel werden die Registrierungswerte beschrieben, die ein WDF-Treiber festlegen kann. Sie gilt für KMDF-Treiber und UMDF-Treiber ab UMDF-Version 2.
Sofern in den folgenden Abschnitten nicht anders angegeben, befinden sich die folgenden Registrierungswerte unter dem Unterschlüssel eines Treibers Parameters\Wdf .
- Für einen KMDF-Treiber befindet sich dieser Unterschlüssel in
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Servicesunter dem Dienstnamen des Treibers. - Für einen UMDF-Treiber befindet sich dieser Unterschlüssel unter
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Servicesdem Dienstnamen des Treibers.
Der Unterschlüssel für den Treiber verwendet immer den Dienstnamen des Treibers, auch wenn sich der Dateiname der Treiber-Binärdatei vom Dienstnamen unterscheidet.
DbgBreakOnError
REG_DWORD
Wenn auf einen Wert ohne Wert festgelegt ist, wird das Framework in den Debugger unterteilt, wenn ein Treiber WdfVerifierDbgBreakPoint aufruft. (Wenn der VerifierOn-Wert festgelegt ist, wird das Framework in den Debugger unterteilt, auch wenn der DbgBreakOnError-Wert nicht vorhanden ist.) Weitere Informationen finden Sie im Codebeispiel im Abschnitt VerifierOn .
DbgPrintOn
REG_DWORD
- Legen Sie für einen KMDF-Treiber diesen Wert unter dem
HKLM\SYSTEM\CurrentControlSet\Control\Wdf\Kmdf\DiagnosticsRegistrierungsschlüssel fest. - Legen Sie für einen UMDF-Treiber diesen Wert unter dem
HKLM\System\CurrentControlSet\Control\Wdf\Umdf\DiagnosticsRegistrierungsschlüssel fest.
Möglicherweise muss der Treiber den optionalen Unterschlüssel Diagnose erstellen.
Wenn dieser Wert auf einen Wert ohne Zero festgelegt ist, sendet das Ladeprogramm des Frameworks eine Vielzahl von Nachrichten an den Kerneldebugger, während er einen Treiber lädt und ihn an eine Version der Frameworkbibliothek bindet oder während er einen Treiber entladen.
DbgWaitForSignalTimeoutInSec
REG_DWORD, Frameworkversionen 1.11 und höher
Ab Windows 8, wenn VerifierOn und DbgBreakOnError auf nonzero-Werte festgelegt sind, kann der Treiber den Standardtimeoutzeitraum für das Durchbrechen in den Debugger ändern, indem er DbgWaitForSignalTimeoutInSec festlegt.
DebugModeBinaries
REG_MULTI_SZ, nur UMDF
Dieser Registrierungswert befindet sich in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.
Dieser Wert gibt die Namen der Treiberbinärdateien an, die im Debugmodus geladen werden sollen. Um den Debugmodus für Treiberbinärdateien X.DLL, Y.DLL und Z.DLL zu aktivieren, wird dieser Wert beispielsweise auf X.DLL\0Y.DLL\0Z.DLL\0\0festgelegt.
DebugModeFlags
REG_DWORD, nur UMDF
This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.
| Wert | BESCHREIBUNG |
|---|---|
| 0x01 | Aktivieren Sie den Debugmodus. Diese Einstellung deaktiviert die unter Verwenden von Gerätepooling in UMDF-Treibern beschriebene Funktion des automatischen Neustarts. |
| 0x02 | Deaktivieren Sie das Gerätepooling. Weitere Informationen zum Gerätepooling finden Sie unter Verwenden von Gerätepooling in UMDF-Treibern. |
| 0x04 | Deaktivieren Sie Timeouts. |
Wenn Sie die Option F5 in Microsoft Visual Studio verwenden, werden alle drei Flags für den bereitgestellten Treiber festgelegt.
EnhancedVerifierOptions
REG_DWORD, Frameworkversionen 1.9 und höher
Dieser Wert enthält eine Bitmap. Jedes Bit stellt eine zusätzliche Überprüfungsoption dar, die Benutzer durch Festlegen des Bits aktivieren können.
Bitwerte:
0x1: Wenn festgelegt, überprüft der Prüfer, ob jede Ereignisrückruffunktion des Treibers die folgenden Funktionen ausführt:
Gibt bei derselben IRQL zurück, bei der sie aufgerufen wurde. Wenn sich die Werte unterscheiden, erfolgt eine WDF_VIOLATION Fehlerüberprüfung mit einem Fehlercode von 0xE.
Vor der Rückgabe werden alle kritischen Regionen beendet, in die sie eintritt. Wenn die Rückruffunktion in einem kritischen Bereich zurückgibt, den sie eingegeben hat, erfolgt eine WDF_VIOLATION Fehlerüberprüfung mit dem Fehlercode 0xF.
0x10000: Wenn festgelegt ist und der Treiber den garantierten Vorwärtsfortschritt für eine E/A-Warteschlange aktiviert hat, simuliert das Framework eine Situation mit wenig Arbeitsspeicher für jede E/A-Anforderung der Warteschlange.
0x20000: Wenn festgelegt und der Treiber den garantierten Vorwärtsfortschritt für eine E/A-Warteschlange aktiviert hat, simuliert das Framework eine Situation mit wenig Arbeitsspeicher für einige zufällig ausgewählte E/A-Anforderungen.
ForceLogsInMiniDump
REG_DWORD
Legen Sie auf einen wert ohne Wert fest, damit das Framework Informationen aus seiner Ereignisprotokollierung in Absturzabbilddateien einschließt.
HostFailKdDebugBreak
REG_DWORD, UMDF-only
This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF.
Wenn dieser Wert ungleich Null ist und ein Kerneldebugger mit dem Computer verbunden ist, wird der Reflektor in den Kerneldebugger eingegliedert, bevor der Hostprozess beendet wird. HostFailKdDebugBreak ist in Windows 7 und früheren Betriebssystemen standardmäßig deaktiviert. Ab Windows 8 ist HostFailKdDebugBreak standardmäßig aktiviert.
Der Reflektor bricht auch in den Kerneldebugger ein, wenn es zu einer unerwarteten Beendigung des Hostprozesses kommt (z. B. durch eine Nicht-UMDF-Komponente oder aufgrund einer nicht behandelten Ausnahme). Wenn mehrere Gerätestapel im Hostprozess zusammengefasst sind, der beendet wird, bricht der Reflektor mehrmals in den Debugger ein, einmal für jeden Gerätestapel, der im Hostprozess geladen wird.
HostProcessDbgBreakOnDriverLoad (treiberspezifisch)
REG_DWORD, nur UMDF, funktioniert mit jedem UMDF 1.x/2.x-Treiber, der auf einem Zielcomputer mit UMDF-Version 2.31 oder höher ausgeführt wird.
This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<service name>\Parameters\Wdf.
Dieser Wert wirkt sich nur auf den angegebenen UMDF-Treiber aus.
Enthält einen Verzögerungswert in Sekunden. Bewirkt, dass WUDFHost versucht, eine Verbindung mit einem Debugger für die angegebene Anzahl von Sekunden nach dem Laden des Treibers herzustellen.
Während des angegebenen Verzögerungszeitraums sucht der Hostprozess einmal pro Sekunde nach dem Benutzermodusdebugger und bricht ein, wenn er verbunden ist. Wenn innerhalb dieses Zeitraums kein Debugger im Benutzermodus angefügt ist und das high bit in festgelegt ist (0x80000000), unternimmt das Framework einen einzelnen Versuch, in den Kernelmodusdebugger einzubrechen. Beispiele finden Sie im Abschnitt zu HostProcessDbgBreakOnStart oben.
Damit Änderungen an UMDF-Registrierungswerten wirksam werden, müssen Sie den Computer neu starten.
HostProcessDbgBreakOnDriverLoad (global)
REG_DWORD, UMDF-only
This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. Sie können es festlegen, indem Sie das WDF-Überprüfungstool (WdfVerifier.exe) im WDK verwenden. Dieser Wert wirkt sich auf alle UMDF-Treiber im System aus.
Contains a delay value in seconds. Bewirkt, dass WUDFHost die angegebene Anzahl von Sekunden verzögert, nachdem der Treiber geladen wurde. Das Verhalten für HostProcessDbgBreakOnDriverLoad entspricht andernfalls dem für HostProcessDbgBreakOnStart beschriebenen Verhalten.
Die Angabe von HostProcessDbgBreakOnStart oder HostProcessDbgBreakOnDriverLoad führt dazu, dass das Framework andere UMDF-Timeouts (z. B. Plug & Play-Vorgänge) deaktiviert. Wenn Ihr Treiber zu übermäßigen Timeouts führt, kann die Verwendung dieser Werte dazu führen, dass Ihr Treiber einen tödlichen Absturz auf dem Ziel verursacht.
HostProcessDbgBreakOnStart
REG_DWORD, UMDF-only
This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. You can set it by using the WDF Verifier tool (WdfVerifier.exe) in the WDK. This value affects all UMDF drivers on the system.
Contains a delay value in seconds. During the specified delay period, the host process looks for the user-mode debugger once a second and breaks in if one is connected. Wenn innerhalb dieses Zeitraums kein Debugger im Benutzermodus angefügt ist und das high bit in HostProcessDbgBreakOnStart festgelegt ist (0x80000000), unternimmt das Framework einen einzelnen Versuch, in den Kernelmodusdebugger einzubrechen. Beispiel:
| Wert | Ergebnis |
|---|---|
| 0x00000004 | Das Framework versucht, einmal pro Sekunde eine Verbindung mit dem Benutzermodusdebugger für 4 Sekunden herzustellen. Das Framework versucht nie, eine Verbindung mit dem Kernelmodusdebugger herzustellen. |
| 0x80000000 | Das Framework unternimmt einen einzigen Versuch, eine Verbindung mit dem Benutzermodusdebugger herzustellen. Wenn der Debugger im Benutzermodus nicht angefügt ist, versucht das Framework, eine Verbindung mit dem Kernelmodusdebugger herzustellen. |
| 0x80000004 | Das Framework versucht, einmal pro Sekunde eine Verbindung mit dem Benutzermodusdebugger für 4 Sekunden herzustellen. Wenn der Benutzermodusdebugger nicht innerhalb von 4 Sekunden angefügt ist, versucht das Framework, eine Verbindung mit dem Kernelmodusdebugger herzustellen. |
Sie können diesen Registrierungswert auch mit dem WDF-Überprüfungstool (WdfVerifier.exe) festlegen, das im WDK enthalten ist.
LogPages
REG_DWORD
Legen Sie auf die Anzahl der Speicherseiten fest, die das Framework seiner Ereignisprotokollierung zuweist. Wenn der Wert nicht definiert ist, verwendet das Framework den Standardwert einer Seite. Der maximale Wert, den Sie festlegen können, ist 16 für Computer mit Arbeitsspeicherseiten mit einer Größe von 4 KB (x86- und amd64-Prozessoren) und 8 für Computer mit Arbeitsspeicherseiten von 8 KB (ia64-Prozessoren). (Das Betriebssystem schreibt den Protokollinhalt möglicherweise nicht in eine Absturzabbilddatei, wenn eine große Anzahl von Seiten angegeben ist.) Verwenden Sie die AddService-Direktive und die AddReg-Anweisung , um diesen Wert wie folgt in Ihrer INF-Datei festzulegen:
[xxx.NT.Services]
AddService = yyy, 2, zzz.AddService
[zzz.AddService]
DisplayName = %aaa\bbb%
ServiceType = 1
StartType = 3
ErrorControl = 1
ServiceBinary = %12%\ddd.SYS
AddReg = eee.AddReg
[eee.AddReg]
HKR, Parameters\Wdf, LogPages, 0x00010001, 3 ; KMDF IFR size
ObjectLeakDetectionLimit
In einigen Fällen werden Frameworkobjekte fälschlicherweise in übergeordneten Klammern zusammengefasst und nach der Verwendung nicht gelöscht. Sie können ObjectLeakDetectionLimit und ObjectsForLeakDetection verwenden, um eine maximale Anzahl von Objekten anzugeben und anzugeben, was passieren soll, wenn dieser Schwellenwert überschritten wird.
REG_DWORD
Gibt die maximale Anzahl von Objekten der Typen an, die im ObjectsForLeakDetection-Schlüssel beschrieben sind. Legen Sie den DbgBreakOnError-Schlüssel fest, um zu steuern, ob das Überschreiten dieses Schwellenwerts zu einem Debugunterbrechung oder einer Fehlerüberprüfung führen soll. Der Grenzwert wird mit der Anzahl der installierten Geräte skaliert. Wenn der Treiber also drei WDFDEVICE-Objekte erstellt, beträgt der Grenzwert das Dreifache des in ObjectLeakDetectionLimit angegebenen Werts.
ObjectsForLeakDetection
REG_MULTI_SZ
Verwenden Sie mit ObjectLeakDetectionLimit. Listet jeden zu überprüfenden Typnamen auf. Sie können z.B. WDFDMATRANSACTION WDFDEVICE angeben. Um alle Handle-Typen anzugeben, verwenden Sie * als Zeichenfolge. Wenn der Schlüssel ObjectsForLeakDetection nicht angegeben ist, wird standardmäßig WDFREQUEST, WDFWORKITEM, WDFKEY, WDFSTRING, WDFOBJECT und WDFDEVICE überwacht.
Wenn Sie WDFREQUEST angeben, zählt der Prüfer nur WDFREQUEST-Objekte, die der Treiber erstellt. Dieses Feature unterstützt derzeit nicht die Nachverfolgung des WDFMEMORY-Objekttyps.
TrackHandles
REG_MULTI_SZ
Wenn sie auf eine Liste mit mindestens einem Typnamen von Frameworkobjekthandles festgelegt ist und VerifierOn festgelegt ist, verfolgt das Framework Verweise auf alle Objekthandles nach, die den angegebenen Handle-Typen entsprechen. Wenn die Handletypliste beispielsweise aus der Zeichenfolge "WDFREQUEST WDFQUEUE" besteht, verfolgt das Framework Verweise auf alle Anforderungsobjekte und Warteschlangenobjekte nach. Wenn die Liste ein Sternchen ("*") enthält, verfolgt das Framework alle Objekthandles nach.
VerboseOn
REG_DWORD
Wenn sie auf einen Wert ohne Zero festgelegt ist, zeichnet die Ereignisprotokollierung des Frameworks zusätzliche Informationen auf, die Ihnen beim Debuggen Ihres Treibers helfen können, z. B. Einträge in interne Codepfade oder Ausgänge aus internen Codepfaden. Sie sollten diesen Wert nur während der Entwicklung Des Treibers festlegen. Sehen Sie sich das Codebeispiel in VerifierOn an.
VerifierAllocateFailCount
REG_DWORD
Wenn auf den Wert n festgelegt ist und VerifierOn festgelegt ist, schlägt das Framework nach der n-ten Zuordnung bei jedem Versuch fehl, Arbeitsspeicher für die Objekte des Treibers zuzuweisen. Dieser Fehler hilft Ihnen dabei, die Behandlung von Speichermangels durch Ihren Treiber zu testen. Wenn Sie beispielsweise VerifierAllocateFailCount auf 2 festlegen, schlägt jede Speicherzuordnung nach der zweiten Zuordnung fehl. Der Standardwert für VerifierAllocateFailCount ist 0xffffffff. Nachdem Sie VerifierAllocateFailCount festgelegt haben, können Sie es deaktivieren, indem Sie es auf (DWORD) -1 festlegen oder den Wert ganz entfernen.
Beachten Sie, dass die Überprüfung sowohl die Zuordnungen zählt, die Ihr Treiber anfordert, als auch die Zuordnungen, die das Framework im Namen Ihres Treibers anfordert. Beachten Sie außerdem, dass sich die Anzahl der Zuordnungen, die für Ihren Treiber auftreten können, von einer Version des Frameworks zur nächsten ändern kann.
VerifierOn
REG_DWORD
Legen Sie zum Aktivieren des KMDF-Prüfers einen wert ohne Wert fest, der den Zustand und die Funktionsparameter eines Treibers umfassend überprüft. Sie sollten VerifierOn und DbgBreakOnError festlegen, wenn Sie Ihren Treiber entwickeln. Verwenden Sie die AddService-Direktive und die AddReg-Anweisung , um diese Werte im Abschnitt Services der INF-Datei festzulegen, z. B.:
[xxx_Inst.NT.Services]
AddService = xxx,%SPSVCINST_ASSOCSERVICE%,xxx_Service_Inst
[xxx_Service_Inst]
ServiceType = %SERVICE_KERNEL_DRIVER%
StartType = %SERVICE_BOOT_START%
ErrorControl = %SERVICE_ERROR_NORMAL%
LoadOrderGroup = "Base"
ServiceBinary = %12%\xxx.sys
AddReg = KMDFVerifierAddReg
[KMDFVerifierAddReg]
HKR, Parameters\Wdf,VerifierOn,0x00010001,1
HKR, Parameters\Wdf,VerboseOn,0x00010001,1
HKR, Parameters\Wdf,DbgBreakOnError,0x00010001,1
VerifyDownLevel
REG_DWORD, Frameworkversionen 1.9 und höher
Wenn der Treiber auf einen Wert ohne Zero festgelegt ist und der Treiber mit einer Version des Frameworks erstellt wurde, die älter als die aktuelle Version ist, enthält die Überprüfung des Frameworks Tests, die nach dem Erstellen des Treibers hinzugefügt wurden. Wenn dieser Wert nicht vorhanden ist oder auf Null festgelegt ist, enthält die Überprüfung des Frameworks nur die Tests, die beim Erstellen des Treibers vorhanden waren.
Wenn Ihr Treiber beispielsweise mit Version 1.7 des Frameworks erstellt wurde und Version 1.9 des Frameworks auf dem Computer installiert ist, führt das Festlegen von VerifyDownLevel auf nonzero dazu, dass die Überprüfung Tests enthält, die der Version 1.9 der Überprüfung hinzugefügt wurden, wenn Ihr Treiber ausgeführt wird.
VerifyOn
REG_DWORD
Legen Sie den Wert nonzero fest, um das in Wdfassert.h definierte WDFVERIFY-Makro zu aktivieren, oder legen Sie auf null fest, um das Makro zu deaktivieren. Wenn der VerifierOn-Wert festgelegt ist, wird VerifyOn implizit auf nonzero festgelegt.