Share via

Valori del Registro di sistema per il debug dei driver WDF

  • Articolo

Questo articolo descrive i valori del Registro di sistema che un driver WDF può impostare. Si applica ai driver kmDF e ai driver UMDF a partire da UMDF versione 2.

Se non diversamente specificato nelle sezioni seguenti, i valori del Registro di sistema seguenti si trovano sotto la sottochiave di Parameters\Wdf un driver.

  • Per un driver KMDF, questa sottochiave si trova in HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services, sotto il nome del servizio del driver.
  • Per un driver UMDF, questa sottochiave si trova in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services, sotto il nome del servizio del driver.

La sottochiave per il driver usa sempre il nome del servizio del driver, anche se il nome del file binario del driver differisce dal nome del servizio.

DbgBreakOnError

REG_DWORD

Se impostato su un valore diverso da zero, il framework si interrompe nel debugger quando un driver chiama WdfVerifierDbgBreakPoint. Se il valore VerifierOn è impostato, il framework si interrompe nel debugger anche se il valore DbgBreakOnError non esiste. Vedere l'esempio di codice nella sezione VerifierOn .

DbgPrintOn

REG_DWORD

  • Per un driver KMDF, impostare questo valore sotto la chiave del HKLM\SYSTEM\CurrentControlSet\Control\Wdf\Kmdf\Diagnostics Registro di sistema.
  • Per un driver UMDF, impostare questo valore nella chiave del HKLM\System\CurrentControlSet\Control\Wdf\Umdf\Diagnostics Registro di sistema.

Il driver potrebbe dover creare la sottochiave diagnostica facoltativa.

Se impostato su un valore diverso da zero, il caricatore del framework invia un'ampia gamma di messaggi al debugger del kernel durante il caricamento di un driver e l'associazione a una versione della libreria del framework o durante lo scaricamento di un driver.

DbgWaitForSignalTimeoutInSec

REG_DWORD, versioni del framework 1.11 e versioni successive

A partire da Windows 8, quando VerifierOn e DbgBreakOnError sono impostati su valori non zero, il driver può modificare il periodo di timeout predefinito per l'interruzione nel debugger impostando DbgWaitForSignalTimeoutInSec.

DebugModeBinaries

REG_MULTI_SZ, solo UMDF

Questo valore del Registro di sistema si trova in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

Questo valore specifica i nomi dei file binari driver da caricare in modalità di debug. Per abilitare la modalità di debug per i file binari driver X.DLL, Y.DLL e Z.DLL, ad esempio, questo valore verrà impostato su X.DLL\0Y.DLL\0Z.DLL\0\0.

DebugModeFlags

REG_DWORD, solo UMDF

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

Valore Descrizione
0x01 Abilitare la modalità di debug. Questa impostazione disattiva la funzionalità di riavvio automatico descritta in Uso del pool di dispositivi nei driver UMDF.
0x02 Disabilitare il pool di dispositivi. Per altre informazioni sul pool di dispositivi, vedere Uso del pool di dispositivi nei driver UMDF.
0x04 Disabilitare i timeout.

Quando si usa l'opzione F5 in Microsoft Visual Studio, tutti e tre i flag vengono impostati per il driver distribuito.

EnhancedVerifierOptions

REG_DWORD, versioni del framework 1.9 e versioni successive

Questo valore contiene una bitmap. Ogni bit rappresenta un'opzione di verifica aggiuntiva che gli utenti possono abilitare impostando il bit.

Valori bit:

0x1: se impostato, il verificatore verifica se ognuna delle funzioni di callback dell'evento del driver esegue le operazioni seguenti:

  • Restituisce allo stesso IRQL in corrispondenza del quale è stato chiamato. Se i valori sono diversi, si verifica un controllo di bug WDF_VIOLATION con un codice di errore di 0xE.

  • Prima di tornare, chiude tutte le aree critiche immesse. Se la funzione di callback restituisce all'interno di un'area critica immessa, si verifica un controllo di bug WDF_VIOLATION con un codice di errore di 0xF .

0x10000: se impostato e se il driver ha abilitato lo stato di avanzamento garantito per una coda di I/O, il framework simula una situazione di memoria ridotta per ognuna delle richieste di I/O della coda.

0x20000: se impostato e se il driver ha abilitato lo stato di avanzamento garantito per una coda di I/O, il framework simula una situazione di memoria ridotta per alcune richieste di I/O selezionate in modo casuale.

ForceLogsInMiniDump

REG_DWORD

Impostare su un valore diverso da zero per causare che il framework includa informazioni dal relativo logger di eventi nei file di dump di arresto anomalo.

HostFailKdDebugBreak

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF.

Se questo valore non è zero e un debugger del kernel è connesso al computer, il reflectionor si interrompe nel debugger del kernel prima di terminare il processo host. HostFailKdDebugBreak è disabilitato per impostazione predefinita nei sistemi operativi Windows 7 e versioni precedenti. A partire da Windows 8, HostFailKdDebugBreak è abilitato per impostazione predefinita.

Il reflectionor si interrompe anche nel debugger del kernel se si verifica una terminazione imprevista del processo host, ad esempio da un componente non UMDF o a causa di un'eccezione non gestita. Se sono presenti più stack di dispositivi in pool nel processo host che viene terminato, il reflectionor si interrompe più volte nel debugger, una volta per ogni stack di dispositivi caricato nel processo host.

HostProcessDbgBreakOnDriverLoad (specifico del driver)

REG_DWORD, solo UMDF, funziona con qualsiasi driver UMDF 1.x/2.x in esecuzione in un computer di destinazione con UMDF versione 2.31 o successiva

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<service name>\Parameters\Wdf.

Questo valore influisce solo sul driver UMDF specificato.

Contiene un valore di ritardo in secondi. Fa sì che WUDFHost tenti di connettersi a un debugger per il numero specificato di secondi dopo che il driver è stato caricato.

Durante il periodo di ritardo specificato, il processo host cerca il debugger in modalità utente una volta al secondo e si interrompe se si è connessi. Se un debugger in modalità utente non è collegato entro questo periodo e il bit elevato in è impostato (0x80000000), il framework esegue un singolo tentativo di interruzione nel debugger in modalità kernel. Vedere la sezione su HostProcessDbgBreakOnStart sopra per esempi.

Per apportare modifiche ai valori del Registro di sistema UMDF, è necessario riavviare il computer.

HostProcessDbgBreakOnDriverLoad (globale)

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. È possibile impostarlo usando lo strumento di verifica WDF (WdfVerifier.exe) in WDK. Questo valore influisce su tutti i driver UMDF nel sistema.

Contains a delay value in seconds. Fa sì che WUDFHost ritardi il numero specificato di secondi dopo che il driver è stato caricato. Il comportamento per HostProcessDbgBreakOnDriverLoad è altrimenti uguale a quello descritto per HostProcessDbgBreakOnStart.

Se si specifica HostProcessDbgBreakOnStart o HostProcessDbgBreakOnDriverLoad, il framework disabilita altri timeout UMDF, ad esempio Plug and Play operazioni. Ciò significa che se il driver causa timeout eccessivo, l'uso di questi valori potrebbe causare un arresto anomalo irreversibile sulla destinazione.

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. Se un debugger in modalità utente non è collegato entro questo periodo e il bit elevato in HostProcessDbgBreakOnStart è impostato (0x80000000), il framework esegue un singolo tentativo di interruzione nel debugger in modalità kernel. Ad esempio:

valore Risultato
0x00000004 Il framework tenta di connettersi al debugger in modalità utente una volta al secondo per 4 secondi. Il framework non tenta mai di connettersi al debugger in modalità kernel.
0x80000000 Il framework esegue un singolo tentativo di connessione al debugger in modalità utente. Se il debugger in modalità utente non è collegato, il framework tenta di connettersi al debugger in modalità kernel.
0x80000004 Il framework tenta di connettersi al debugger in modalità utente una volta al secondo per 4 secondi. Se il debugger in modalità utente non è collegato entro 4 secondi, il framework tenta di connettersi al debugger in modalità kernel.

È anche possibile impostare questo valore del Registro di sistema usando lo strumento WDF Verifier (WdfVerifier.exe) incluso in WDK.

LogPages

REG_DWORD

Impostare sul numero di pagine di memoria assegnate dal framework al logger di eventi. Se il valore non è definito, il framework usa un valore predefinito di una pagina. Il valore massimo che è possibile impostare è 16 per i computer con pagine di memoria di 4 kilobyte (processori x86 e amd64) e 8 per i computer con pagine di memoria di 8 kilobyte (processori ia64). Il sistema operativo potrebbe non scrivere il contenuto del log in un file di dump di arresto anomalo del sistema se viene specificato un numero elevato di pagine. Usare la direttiva AddService e la direttiva AddReg per impostare questo valore nel file INF, come indicato di seguito:

[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 alcuni casi, gli oggetti framework non sono padre e non vengono eliminati dopo l'uso. È possibile usare ObjectLeakDetectionLimit e ObjectsForLeakDetection per specificare un numero massimo di oggetti e cosa deve accadere quando viene superata questa soglia.

REG_DWORD

Specifica il numero massimo di oggetti dei tipi descritti nella chiave ObjectsForLeakDetection . Per controllare se il superamento di questa soglia deve causare un'interruzione di debug o un controllo di bug, impostare la chiave DbgBreakOnError . Il limite viene ridimensionato con il numero di dispositivi installati, quindi se il driver crea tre oggetti WDFDEVICE, il limite è tre volte il valore specificato in ObjectLeakDetectionLimit.

ObjectsForLeakDetection

REG_MULTI_SZ

Usare con ObjectLeakDetectionLimit. Elenca ogni nome di tipo da verificare. Ad esempio è possibile specificare WDFDMATRANSACTION WDFDEVICE. Per specificare tutti i tipi di handle, usare * come stringa. Se la chiave ObjectsForLeakDetection non è specificata, l'impostazione predefinita consiste nel monitorare WDFREQUEST, WDFWORKITEM, WDFKEY, WDFSTRING, WDFOBJECT e WDFDEVICE.

Se si specifica WDFREQUEST, il verifier conta solo gli oggetti WDFREQUEST creati dal driver. Questa funzionalità attualmente non supporta il rilevamento del tipo di oggetto WDFMEMORY.

TrackHandles

REG_MULTI_SZ

Se impostato su un elenco di uno o più nomi di tipi di handle di oggetto framework e se VerifierOn è impostato, il framework tiene traccia dei riferimenti a tutti gli handle di oggetto corrispondenti ai tipi di handle specificati. Ad esempio, se l'elenco dei tipi di handle è costituito dalla stringa "WDFREQUEST WDFQUEUE", il framework tiene traccia dei riferimenti a tutti gli oggetti della richiesta e agli oggetti coda. Se l'elenco contiene un asterisco ("*"), il framework tiene traccia di tutti gli handle di oggetto.

VerboseOn

REG_DWORD

Se impostato su un valore diverso da zero, il logger di eventi del framework registra informazioni aggiuntive che consentono di eseguire il debug del driver, ad esempio le voci in o esce dai percorsi di codice interni. È consigliabile impostare questo valore solo durante lo sviluppo del driver. Vedere l'esempio di codice in VerifierOn.

VerifierAllocateFailCount

REG_DWORD

Se è impostato su un valore n e se VerifierOn è impostato, il framework non riesce ogni tentativo di allocare memoria per gli oggetti del driver dopo l'nesima allocazione. Questo errore consente di testare la gestione del driver di condizioni di memoria insufficiente. Ad esempio, se si imposta VerifierAllocateFailCount su 2, ogni allocazione di memoria dopo la seconda allocazione avrà esito negativo. Il valore predefinito per VerifierAllocateFailCount è 0xffffffff. Dopo aver impostato VerifierAllocateFailCount, è possibile disattivarlo impostandolo su (DWORD) -1 o rimuovendo completamente il valore.

Si noti che il verificatore conta sia le allocazioni richieste dal driver che le allocazioni richieste dal framework per conto del driver. Si noti anche che il numero di allocazioni che possono verificarsi per il driver può passare da una versione del framework alla successiva.

VerifierOn

REG_DWORD

Impostare su un valore diverso da zero per abilitare KMDF Verifier, che convalida ampiamente lo stato e i parametri di funzione di un driver. È consigliabile impostare VerifierOn e DbgBreakOnError quando si sviluppa il driver. Usare la direttiva AddService e la direttiva AddReg per impostare questi valori nella sezione Servizi del file INF, ad esempio:

[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, framework versione 1.9 e successive

Se è impostato su un valore diverso da zero e se il driver è stato compilato con una versione del framework precedente alla versione corrente, il verificatore del framework include i test aggiunti dopo la compilazione del driver. Se questo valore non esiste o è impostato su zero, il verificatore del framework include solo i test esistenti al momento della compilazione del driver.

Ad esempio, se il driver è stato compilato con la versione 1.7 del framework e se la versione 1.9 del framework è installata nel computer, l'impostazione di VerifyDownLevel su diverso da zero fa sì che il verifier includa i test aggiunti alla versione 1.9 del verificatore durante l'esecuzione del driver.

VerifyOn

REG_DWORD

Impostare su un valore diverso da zero per abilitare la macro WDFVERIFY definita in Wdfassert.h oppure impostare su zero per disabilitare la macro. Se il valore VerifierOn è impostato, VerifyOn viene impostato in modo implicito su diverso da zero.