Condividi tramite

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 nella sottochiave di un driver Parameters\Wdf.

  • 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 è diverso 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. Consultate l'esempio di codice nella sezione VerifierOn.

DbgPrintOn

REG_DWORD

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

Potrebbe essere necessario creare la sottochiave facoltativa Diagnostica.

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 framework o durante lo scaricamento di un driver.

DbgWaitForSignalTimeoutInSec

REG_DWORD, framework 1.11 e versioni successive

A partire da Windows 8, quando VerifierOn e DbgBreakOnError sono impostati su valori diversi da 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 del driver da caricare in modalità di debug. Per abilitare la modalità di debug per i file binari del 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 per UMDF

Questo valore del Registro di sistema si trova 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 timeout.

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

OpzioniAvanzateDiVerifica

REG_DWORD, framework versione 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 dei bit:

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

  • Restituisce allo stesso livello IRQL a cui è 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, esce da tutte le aree critiche a cui entra. Se la funzione di callback restituisce all'interno di un'area critica immessa, viene generato un controllo di bug WDF_VIOLATION con un codice di errore di 0xF.

0x10000: se impostato e se il driver ha abilitato avanzamento di avanzamento garantito per una coda di I/O, il framework simula una situazione di memoria insufficiente 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 insufficiente per alcune richieste di I/O selezionate in modo casuale.

ForceLogsInMiniDump

REG_DWORD

Imposta su un valore diverso da zero affinché il framework includa informazioni dal proprio event logger nei crash dump.

HostFailKdDebugBreak

REG_DWORD, solo UMDF

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

Se questo valore è diverso da zero e un debugger del kernel è connesso al computer, il riflettore interrompe il processo 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 riflettore attiva anche il 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 raggruppati nel processo host che viene terminato, il riflettore si interrompe nel debugger più volte, 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

Questo valore del Registro di sistema si trova 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 il caricamento del driver.

Durante il periodo di ritardo specificato, il processo host cerca il debugger in modalità utente una volta al secondo e si interrompe se ne è connesso uno. 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. Per degli esempi, vedere la sezione HostProcessDbgBreakOnStart precedente.

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

HostProcessDbgBreakOnDriverLoad (globale)

REG_DWORD, solo UMDF

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

Contiene un valore di ritardo in secondi. Fa sì che WUDFHost ritardi il numero specificato di secondi dopo il caricamento del driver. Il comportamento per HostProcessDbgBreakOnDriverLoad è altrimenti uguale a quello descritto per HostProcessDbgBreakOnStart.

Se si specifica HostProcessDbgBreakOnStart o HostProcessDbgBreakOnDriverLoad il framework disabilita altri timeout di UMDF, ad esempio le operazioni Plug and Play. Ciò significa che se il driver causa timeout eccessivi, l'uso di questi valori potrebbe comportare un crash fatale sul dispositivo di destinazione.

HostProcessDbgBreakOnStart

REG_DWORD, UMDF soltanto

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

Contiene un valore di ritardo in secondi. Durante il periodo di ritardo specificato, il processo host cerca il debugger in modalità utente una volta al secondo e si interrompe se ne è connesso uno. Se un debugger in modalità utente non è collegato entro questo periodo e il bit alto in HostProcessDbgBreakOnStart è impostato (0x80000000), il framework esegue un singolo tentativo di passare al debugger in modalità kernel. Per 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

Imposta il numero di pagine di memoria assegnate dal framework al logger degli 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 è 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 sono associati in modo errato e non vengono eliminati dopo l'uso. È possibile usare objectLeakDetectionLimit e ObjectsForLeakDetection per specificare un numero massimo di oggetti e cosa deve accadere quando questa soglia viene superata.

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.

OggettiPerIlRilevamentoPerdite

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 verificatore 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 contenente uno o più nomi di tipi di handle di oggetti framework, e se è impostato VerifierOn, il framework tiene traccia dei riferimenti a tutti gli handle di oggetti che corrispondono ai tipi di handle specificati. Ad esempio, se l'elenco dei tipi di handle comprende la stringa "WDFREQUEST WDFQUEUE", il framework tiene traccia dei riferimenti a tutti gli oggetti di richiesta e agli oggetti di coda. Se l'elenco contiene un asterisco ("*"), il framework tiene traccia di tutti gli handle di oggetti.

VerboseOn

REG_DWORD

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

ConteggioFallimentoAllocazioneVerificatore

REG_DWORD

Se è impostato su un valore ne se VerifierOn è impostato, il framework fallisce ogni tentativo di allocare memoria per gli oggetti del driver dopo la n allocazione. Questo errore consente di testare la gestione del driver in 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 potrebbero 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 durante lo sviluppo del 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, impostando VerifyDownLevel su diverso da zero, il verificatore include 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.