Registerwaarden voor foutopsporing van WDF-stuurprogramma's

In dit artikel worden de registerwaarden beschreven die door een WDF-stuurprogramma kunnen worden ingesteld. Dit geldt voor KMDF-stuurprogramma's en UMDF-stuurprogramma's die beginnen met UMDF versie 2.

Tenzij anders is opgegeven in de onderstaande secties, bevinden de volgende registerwaarden zich onder de subsleutel van Parameters\Wdf een stuurprogramma.

• Voor een KMDF-stuurprogramma bevindt deze subsleutel zich onder HKEY_LOCAL_MACHINE\System\CurrentControlSet\Servicesde servicenaam van het stuurprogramma.
• Voor een UMDF-stuurprogramma bevindt deze subsleutel zich onder HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Servicesde servicenaam van het stuurprogramma.

De subsleutel voor het stuurprogramma gebruikt altijd de servicenaam van het stuurprogramma, zelfs als de bestandsnaam van het binaire stuurprogramma verschilt van de servicenaam.

DbgBreakOnError

REG_DWORD

If set to a nonzero value, the framework breaks into the debugger when a driver calls WdfVerifierDbgBreakPoint. (If the VerifierOn value is set, the framework breaks into the debugger even if the DbgBreakOnError value does not exist.) See the code example in the VerifierOn section.

DbgPrintOn

REG_DWORD

• Voor een KMDF-stuurprogramma stelt u deze waarde in onder de HKLM\SYSTEM\CurrentControlSet\Control\Wdf\Kmdf\Diagnostics registersleutel.
• Voor een UMDF-stuurprogramma stelt u deze waarde in onder de HKLM\System\CurrentControlSet\Control\Wdf\Umdf\Diagnostics registersleutel.

The driver might need to create the optional Diagnostics subkey.

Als dit is ingesteld op een niet-nulwaarde, verzendt het frameworkslaadprogramma verschillende berichten naar het kernelfoutopsporingsprogramma terwijl het een stuurprogramma laadt en deze aan een versie van de frameworkbibliotheek koppelt, of wanneer een stuurprogramma wordt verwijderd.

DbgWaitForSignalTimeoutInSec

REG_DWORD, frameworkversie 1.11 en hoger

Starting in Windows 8, when VerifierOn and DbgBreakOnError are set to nonzero values, the driver can change the default timeout period for breaking into the debugger by setting DbgWaitForSignalTimeoutInSec.

DebugModeBinaries

REG_MULTI_SZ, UMDF-only

Deze registerwaarde bevindt zich in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

Met deze waarde worden de namen opgegeven van de binaire stuurprogrammabestanden die moeten worden geladen in de foutopsporingsmodus. Als u de foutopsporingsmodus wilt inschakelen voor binaire stuurprogrammabestanden X.DLL, Y.DLL en Z.DLL, wordt deze waarde bijvoorbeeld ingesteld X.DLL\0Y.DLL\0Z.DLL\0\0op .

DebugModeFlags

REG_DWORD, UMDF-only

Deze registerwaarde bevindt zich in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

Wanneer u de F5-optie in Microsoft Visual Studio gebruikt, worden alle drie de vlaggen ingesteld voor het geïmplementeerde stuurprogramma.

EnhancedVerifierOptions

REG_DWORD, frameworkversie 1.9 en hoger

Deze waarde bevat een bitmap. Elke bit vertegenwoordigt een extra verifier-optie die gebruikers kunnen inschakelen door de bit in te stellen.

Bit values:

0x1: If set, the verifier checks whether each of the driver's event callback functions does the following:

• Keert terug naar dezelfde IRQL waarop het is aangeroepen. If the values are different, a WDF_VIOLATION bug check occurs with an error code of 0xE.

• Before returning, exits all critical regions that it enters. If the callback function returns within a critical region that it entered, a WDF_VIOLATION bug check occurs with an error code of 0xF.

0x10000: If set, and if the driver has enabled guaranteed forward progress for an I/O queue, the framework simulates a low-memory situation for each of the queue's I/O requests.

0x20000: If set, and if the driver has enabled guaranteed forward progress for an I/O queue, the framework simulates a low-memory situation for some randomly selected I/O requests.

ForceLogsInMiniDump

REG_DWORD

Ingesteld op een niet-nulwaarde om ervoor te zorgen dat het framework informatie van de gebeurtenislogboekregistratie in crashdumpbestanden opneemt.

HostFailKdDebugBreak

REG_DWORD, UMDF-only

Deze registerwaarde bevindt zich in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF.

Als deze waarde niet nul is en er een kernelfoutopsporingsprogramma is verbonden met de machine, breekt de reflector het kernelfoutopsporingsprogramma in voordat het hostproces wordt beëindigd. HostFailKdDebugBreak is disabled by default in Windows 7 and earlier operating systems. Starting in Windows 8, HostFailKdDebugBreak is enabled by default.

De reflector activeert ook het kernelfoutopsporingsprogramma bij een onverwachte beëindiging van het hostproces (bijvoorbeeld veroorzaakt door een niet-UMDF-component of door een niet-verwerkte uitzondering). Als er meerdere apparaatstacks zijn gebundeld in het hostproces dat wordt beëindigd, onderbreekt de reflector meerdere keren het foutopsporingsprogramma, eenmaal voor elke apparaatstack die in het hostproces is geladen.

HostProcessDbgBreakOnDriverLoad (driver-specific)

REG_DWORD, UMDF-only, works with any UMDF 1.x/2.x driver running on a target computer with UMDF version 2.31 or later

Deze registerwaarde bevindt zich in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<service name>\Parameters\Wdf.

Deze waarde is alleen van invloed op het opgegeven UMDF-stuurprogramma.

Bevat een vertragingswaarde in seconden. Zorgt ervoor dat WUDFHost probeert verbinding te maken met een foutopsporingsprogramma voor het opgegeven aantal seconden nadat het stuurprogramma is geladen.

Tijdens de opgegeven vertragingsperiode zoekt het hostproces elke seconde naar het foutopsporingsprogramma in de gebruikersmodus en breekt het in als er een verbonden is. Als er binnen deze periode geen foutopsporingsprogramma voor de gebruikersmodus is gekoppeld en de hoge bit is ingesteld (0x80000000), probeert het framework één poging om in te breken in het foutopsporingsprogramma voor de kernelmodus. See the section on HostProcessDbgBreakOnStart above for examples.

Als u wijzigingen wilt aanbrengen in UMDF-registerwaarden, moet u de computer opnieuw opstarten.

HostProcessDbgBreakOnDriverLoad (global)

REG_DWORD, UMDF-only

Deze registerwaarde bevindt zich in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. U kunt deze instellen met behulp van het WDF Verifier-hulpprogramma (WdfVerifier.exe) in de WDK. Deze waarde is van invloed op alle UMDF-stuurprogramma's op het systeem.

Bevat een vertragingswaarde in seconden. Zorgt ervoor dat WUDFHost het opgegeven aantal seconden vertraagt nadat het stuurprogramma is geladen. The behavior for HostProcessDbgBreakOnDriverLoad is otherwise the same as that described for HostProcessDbgBreakOnStart.

Specifying HostProcessDbgBreakOnStart or HostProcessDbgBreakOnDriverLoad causes the framework to disable other UMDF timeouts (for example, Plug and Play operations). Dit betekent dat als uw stuurprogramma overmatige time-outs veroorzaakt, het gebruik van deze waarden ertoe kan leiden dat uw stuurprogramma een fatale crash op de doelcomputer veroorzaakt.

HostProcessDbgBreakOnStart

REG_DWORD, UMDF-only

Deze registerwaarde bevindt zich in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. U kunt deze instellen met behulp van het WDF Verifier-hulpprogramma (WdfVerifier.exe) in de WDK. Deze waarde is van invloed op alle UMDF-stuurprogramma's op het systeem.

Bevat een vertragingswaarde in seconden. Tijdens de opgegeven vertragingsperiode zoekt het hostproces elke seconde naar het foutopsporingsprogramma in de gebruikersmodus en breekt het in als er een verbonden is. If a user-mode debugger is not attached within this period and the high bit in HostProcessDbgBreakOnStart is set (0x80000000), the framework makes a single attempt to break into the kernel-mode debugger. For example:

U kunt deze registerwaarde ook instellen met behulp van het WDF Verifier-hulpprogramma (WdfVerifier.exe) dat is opgenomen in de WDK.

LogPages

REG_DWORD

Ingesteld op het aantal geheugenpagina's dat het framework toewijst aan de gebeurtenislogboekregistratie. Als de waarde niet is gedefinieerd, wordt in het framework een standaardwaarde van één pagina gebruikt. De maximumwaarde die u kunt instellen is 16 voor computers met een geheugenpagina van 4 kilobyte (x86- en amd64-processors) en 8 voor computers met geheugenpagina's van 8 kilobyte (ia64-processors). (The operating system might not write the log contents to a crash dump file if a large number of pages is specified.) Use the AddService directive and the AddReg directive to set this value in your INF file, as follows:

[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 sommige gevallen zijn frameworkobjecten onjuist gekoppeld aan een bovenliggende structuur en worden ze niet verwijderd na gebruik. You can use ObjectLeakDetectionLimit and ObjectsForLeakDetection to specify a maximum number of objects and what should happen when this threshold is exceeded.

REG_DWORD

Specifies the maximum number of objects of the types described in the ObjectsForLeakDetection key. To control whether exceeding this threshold should cause a debug break or a bugcheck, set the DbgBreakOnError key. The limit scales with the number of devices installed, so if the driver creates three WDFDEVICE objects, the limit is three times the value specified in ObjectLeakDetectionLimit.

ObjectsForLeakDetection

REG_MULTI_SZ

Use with ObjectLeakDetectionLimit. Lijst alle typenamen ter verificatie. U kunt bijvoorbeeld opgeven WDFDMATRANSACTION WDFDEVICE. Gebruik * als tekenreeks om alle handletypen op te geven. Als de sleutel ObjectsForLeakDetection niet is opgegeven, is het standaardinstelling om WDFREQUEST, WDFWORKITEM, WDFKEY, WDFSTRING, WDFOBJECT en WDFDEVICE te bewaken.

Als u WDFREQUEST opgeeft, telt de verifier alleen WDFREQUEST-objecten die door het stuurprogramma worden gemaakt. Deze functie biedt momenteel geen ondersteuning voor het bijhouden van het WDFMEMORY-objecttype.

TrackHandles

REG_MULTI_SZ

If set to a list of one or more type names of framework object handles, and if VerifierOn is set, the framework tracks references to all object handles that match the specified handle types. Als de handletypenlijst bijvoorbeeld bestaat uit de string "WDFREQUEST WDFQUEUE", houdt het framework verwijzingen bij naar alle aanvraag- en wachtrijobjecten. Als de lijst een sterretje (*) bevat, houdt het framework alle objectgrepen bij.

VerboseOn

REG_DWORD

If set to a nonzero value, the framework's event logger records additional information that can help you debug your driver, such as entries into or exits from internal code paths. U moet deze waarde alleen instellen terwijl u uw stuurprogramma ontwikkelt. See the code example in VerifierOn.

VerifierAllocateFailCount

REG_DWORD

If set to a value n, and if VerifierOn is set, the framework fails every attempt to allocate memory for the driver's objects after the nth allocation. Deze fout helpt u uw stuurprogramma's omgang met laag-geheugenomstandigheden te testen. For example, if you set VerifierAllocateFailCount to 2, every memory allocation after the second allocation will fail. The default value for VerifierAllocateFailCount is 0xffffffff. After setting VerifierAllocateFailCount, you can turn it off by setting it to (DWORD) -1 or removing the value altogether.

Houd er rekening mee dat de verifier zowel de toewijzingen telt die door uw stuurprogramma worden aangevraagd als de toewijzingen die door het framework namens uw stuurprogramma worden aangevraagd. Houd er ook rekening mee dat het aantal toewijzingen dat voor uw stuurprogramma kan optreden, kan veranderen van de ene versie van het framework naar de volgende.

VerifierOn

REG_DWORD

Set to a nonzero value to enable KMDF Verifier, which extensively validates a driver's state and function parameters. You should set VerifierOn and DbgBreakOnError when you are developing your driver. Use the AddService directive and the AddReg directive to set these values in the Services section of the INF file, for example:

[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, frameworkversie 1.9 en hoger

Als dit is ingesteld op een niet-nulwaarde en als het stuurprogramma is gebouwd met een versie van het framework dat ouder is dan de huidige versie, bevat de verifier van het framework tests die zijn toegevoegd nadat het stuurprogramma is gebouwd. Als deze waarde niet bestaat of is ingesteld op nul, bevat de verificator van het framework alleen de tests die bestonden toen het stuurprogramma werd gebouwd.

For example, if your driver was built with version 1.7 of the framework, and if version 1.9 of the framework is installed on the computer, setting VerifyDownLevel to nonzero causes the verifier to include tests that were added to version 1.9 of the verifier when your driver runs.

VerifyOn

REG_DWORD

Set to a nonzero value to enable the WDFVERIFY macro that is defined in Wdfassert.h, or set to zero to disable the macro. Als de VerifierOn-waarde is ingesteld, wordt VerifyOn impliciet ingesteld op niet-nul.