Valeurs de Registre pour le débogage des pilotes WDF

Cet article décrit les valeurs de Registre qu’un pilote WDF peut définir. Il s’applique aux pilotes KMDF et aux pilotes UMDF à partir d’UMDF version 2.

Sauf indication contraire dans les sections ci-dessous, les valeurs de Registre suivantes se trouvent sous la sous-clé d’un Parameters\Wdf pilote.

• Pour un pilote KMDF, cette sous-clé se trouve dans HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services, sous le nom de service du pilote.
• Pour un pilote UMDF, cette sous-clé se trouve dans HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services, sous le nom de service du pilote.

La sous-clé du pilote utilise toujours le nom de service du pilote, même si le nom de fichier du fichier binaire du pilote diffère du nom du service.

DbgBreakOnError

REG_DWORD

S’il est défini sur une valeur différente de zéro, l’infrastructure s’interrompt dans le débogueur lorsqu’un pilote appelle WdfVerifierDbgBreakPoint. (Si la valeur VerifierOn est définie, l’infrastructure s’interrompt dans le débogueur même si la valeur DbgBreakOnError n’existe pas.) Consultez l’exemple de code dans la section VerifierOn .

DbgPrintOn

REG_DWORD

• Pour un pilote KMDF, définissez cette valeur sous la clé de HKLM\SYSTEM\CurrentControlSet\Control\Wdf\Kmdf\Diagnostics Registre.
• Pour un pilote UMDF, définissez cette valeur sous la clé de HKLM\System\CurrentControlSet\Control\Wdf\Umdf\Diagnostics Registre.

Le pilote peut avoir besoin de créer la sous-clé Diagnostics facultative.

S’il est défini sur une valeur différente de zéro, le chargeur de l’infrastructure envoie divers messages au débogueur de noyau pendant qu’il charge un pilote et le lie à une version de la bibliothèque d’infrastructure, ou pendant le déchargement d’un pilote.

DbgWaitForSignalTimeoutInSec

REG_DWORD, framework versions 1.11 et ultérieures

À compter de Windows 8, lorsque VerifierOn et DbgBreakOnError sont définis sur des valeurs différentes de zéro, le pilote peut modifier le délai d’expiration par défaut pour le débogueur en définissant DbgWaitForSignalTimeoutInSec.

DebugModeBinaries

REG_MULTI_SZ, UMDF uniquement

Cette valeur de Registre se trouve dans HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

Cette valeur spécifie les noms des fichiers binaires de pilotes à charger en mode débogage. Pour activer le mode de débogage pour les fichiers binaires de pilotes X.DLL, Y.DLL et Z.DLL, par exemple, cette valeur est définie sur X.DLL\0Y.DLL\0Z.DLL\0\0.

DebugModeFlags

REG_DWORD, UMDF uniquement

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

Lorsque vous utilisez l’option F5 dans Microsoft Visual Studio, les trois indicateurs sont définis pour le pilote déployé.

EnhancedVerifierOptions

REG_DWORD, framework versions 1.9 et ultérieures

Cette valeur contient une bitmap. Chaque bit représente une option de vérificateur supplémentaire que les utilisateurs peuvent activer en définissant le bit.

Valeurs de bits :

0x1 : si elle est définie, le vérificateur vérifie si chacune des fonctions de rappel d’événements du pilote effectue les opérations suivantes :

• Retourne à l’IRQL auquel il a été appelé. Si les valeurs sont différentes, une vérification des bogues WDF_VIOLATION se produit avec un code d’erreur de 0xE.

• Avant de retourner, quitte toutes les régions critiques qu’il entre. Si la fonction de rappel retourne dans une région critique qu’elle a entrée, une vérification des bogues WDF_VIOLATION se produit avec un code d’erreur de 0xF.

0x10000 : s’il est défini et si le pilote a activé la progression d’avance garantie pour une file d’E/S, l’infrastructure simule une situation de faible mémoire pour chacune des demandes d’E/S de la file d’attente.

0x20000 : s’il est défini et si le pilote a activé la progression vers l’avant garantie pour une file d’attente d’E/S, l’infrastructure simule une situation de faible mémoire pour certaines demandes d’E/S sélectionnées aléatoirement.

ForceLogsInMiniDump

REG_DWORD

Définissez sur une valeur différente de zéro pour que l’infrastructure inclue les informations de son enregistreur d’événements dans les fichiers de vidage sur incident.

HostFailKdDebugBreak

REG_DWORD, UMDF-only

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

Si cette valeur est différente de zéro et qu’un débogueur de noyau est connecté à l’ordinateur, le réflecteur s’interrompt dans le débogueur de noyau avant de mettre fin au processus hôte. HostFailKdDebugBreak est désactivé par défaut dans Windows 7 et les systèmes d’exploitation antérieurs. À compter de Windows 8, HostFailKdDebugBreak est activé par défaut.

Le réflecteur s’interrompt également dans le débogueur du noyau en cas d’arrêt inattendu du processus hôte (par exemple, par un composant non-UMDF ou en raison d’une exception non prise en charge). Si plusieurs piles d’appareils sont regroupées dans le processus hôte en cours d’arrêt, le réflecteur s’interrompt dans le débogueur plusieurs fois, une fois pour chaque pile d’appareils chargée dans le processus hôte.

HostProcessDbgBreakOnDriverLoad (spécifique au pilote)

REG_DWORD, UMDF uniquement, fonctionne avec n’importe quel pilote UMDF 1.x/2.x exécuté sur un ordinateur cible avec UMDF version 2.31 ou ultérieure

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

Cette valeur affecte uniquement le pilote UMDF spécifié.

Contient une valeur de délai en secondes. Provoque WUDFHost à essayer de se connecter à un débogueur pendant le nombre de secondes spécifié après le chargement du pilote.

Pendant la période de retard spécifiée, le processus hôte recherche le débogueur en mode utilisateur une fois par seconde et s’interrompt s’il est connecté. Si un débogueur en mode utilisateur n’est pas attaché au cours de cette période et que le bit élevé dans est défini (0x80000000), l’infrastructure effectue une seule tentative d’entrée dans le débogueur en mode noyau. Pour obtenir des exemples, consultez la section sur HostProcessDbgBreakOnStart ci-dessus.

Pour que les modifications apportées aux valeurs de Registre UMDF prennent effet, vous devez redémarrer l’ordinateur.

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}. Vous pouvez le définir à l’aide de l’outil vérificateur WDF (WdfVerifier.exe) dans le WDK. Cette valeur affecte tous les pilotes UMDF sur le système.

Contains a delay value in seconds. WuDFHost retarde le nombre de secondes spécifié après le chargement du pilote. Le comportement de HostProcessDbgBreakOnDriverLoad est sinon le même que celui décrit pour HostProcessDbgBreakOnStart.

La spécification de HostProcessDbgBreakOnStart ou HostProcessDbgBreakOnDriverLoad entraîne la désactivation d’autres délais d’attente UMDF (par exemple, les opérations Plug-and-Play). Cela signifie que si votre pilote provoque des délais d’attente excessifs, l’utilisation de ces valeurs peut entraîner un accident fatal sur la cible.

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. Si un débogueur en mode utilisateur n’est pas attaché au cours de cette période et que le bit élevé dans HostProcessDbgBreakOnStart est défini (0x80000000), l’infrastructure effectue une seule tentative d’entrée dans le débogueur en mode noyau. Par exemple :

Vous pouvez également définir cette valeur de Registre à l’aide de l’outil vérificateur WDF (WdfVerifier.exe) inclus dans le WDK.

LogPages

REG_DWORD

Définissez le nombre de pages de mémoire que l’infrastructure affecte à son journal d’événements. Si la valeur n’est pas définie, l’infrastructure utilise une valeur par défaut d’une page. La valeur maximale que vous pouvez définir est 16 pour les ordinateurs qui ont des pages de mémoire de 4 kilooctets (processeurs x86 et amd64) et 8 pour les ordinateurs qui ont des pages de mémoire de 8 kilooctets (processeurs ia64). (Le système d’exploitation risque de ne pas écrire le contenu du journal dans un fichier de vidage sur incident si un grand nombre de pages est spécifié.) Utilisez les directives AddService et AddReg pour définir cette valeur dans votre fichier INF, comme suit :

[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

Dans certains cas, les objets framework sont parentés de manière incorrecte et ne sont pas supprimés après utilisation. Vous pouvez utiliser ObjectLeakDetectionLimit et ObjectsForLeakDetection pour spécifier un nombre maximal d’objets et ce qui doit se produire lorsque ce seuil est dépassé.

REG_DWORD

Spécifie le nombre maximal d’objets des types décrits dans la clé ObjectsForLeakDetection . Pour déterminer si le dépassement de ce seuil doit entraîner un arrêt de débogage ou une vérification de bogue, définissez la clé DbgBreakOnError . La limite est mise à l’échelle avec le nombre d’appareils installés. Par conséquent, si le pilote crée trois objets WDFDEVICE, la limite est de trois fois la valeur spécifiée dans ObjectLeakDetectionLimit.

ObjectsForLeakDetection

REG_MULTI_SZ

Utilisez avec ObjectLeakDetectionLimit. Répertorie chaque nom de type à vérifier. Par exemple, vous pouvez spécifier WDFDMATRANSACTION WDFDEVICE. Pour spécifier tous les types de handle, utilisez * comme chaîne. Si la clé ObjectsForLeakDetection n’est pas spécifiée, la valeur par défaut consiste à surveiller WDFREQUEST, WDFWORKITEM, WDFKEY, WDFSTRING, WDFOBJECT et WDFDEVICE.

Si vous spécifiez WDFREQUEST, le vérificateur compte uniquement les objets WDFREQUEST créés par le pilote. Cette fonctionnalité ne prend actuellement pas en charge le suivi du type d’objet WDFMEMORY.

TrackHandles

REG_MULTI_SZ

S’il est défini sur une liste d’un ou plusieurs noms de types de handles d’objet framework et si VerifierOn est défini, l’infrastructure effectue le suivi des références à tous les handles d’objet qui correspondent aux types de handle spécifiés. Par exemple, si la liste de types de handle se compose de la chaîne « WDFREQUEST WDFQUEUE », l’infrastructure effectue le suivi des références à tous les objets de requête et objets de file d’attente. Si la liste contient un astérisque (« * »), l’infrastructure effectue le suivi de tous les handles d’objet.

VerboseOn

REG_DWORD

S’il est défini sur une valeur différente de zéro, l’enregistreur d’événements de l’infrastructure enregistre des informations supplémentaires qui peuvent vous aider à déboguer votre pilote, telles que les entrées ou les sorties de chemins de code internes. Vous devez définir cette valeur uniquement lorsque vous développez votre pilote. Consultez l’exemple de code dans VerifierOn.

VerifierAllocateFailCount

REG_DWORD

Si la valeur n est définie et si VerifierOn est définie, l’infrastructure échoue à chaque tentative d’allocation de mémoire pour les objets du pilote après la nième allocation. Cette défaillance vous aide à tester la gestion par votre pilote des conditions de mémoire faible. Par exemple, si vous définissez VerifierAllocateFailCount sur 2, chaque allocation de mémoire après la deuxième allocation échoue. La valeur par défaut de VerifierAllocateFailCount est 0xffffffff. Après avoir défini VerifierAllocateFailCount, vous pouvez le désactiver en le définissant sur (DWORD) -1 ou en supprimant complètement la valeur.

Notez que le vérificateur compte à la fois les allocations que votre pilote demande et les allocations que l’infrastructure demande au nom de votre pilote. Notez également que le nombre d’allocations qui peuvent se produire pour votre pilote peut changer d’une version de l’infrastructure à l’autre.

VerifierOn

REG_DWORD

Définissez une valeur différente de zéro pour activer le vérificateur KMDF, qui valide de manière approfondie l’état et les paramètres de fonction d’un pilote. Vous devez définir VerifierOn et DbgBreakOnError lorsque vous développez votre pilote. Utilisez les directives AddService et AddReg pour définir ces valeurs dans la section Services du fichier INF, par exemple :

[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 versions 1.9 et ultérieures

S’il est défini sur une valeur différente de zéro et si le pilote a été créé avec une version de l’infrastructure antérieure à la version actuelle, le vérificateur de l’infrastructure inclut des tests qui ont été ajoutés après la génération du pilote. Si cette valeur n’existe pas ou est définie sur zéro, le vérificateur de l’infrastructure inclut uniquement les tests qui existaient lors de la génération du pilote.

Par exemple, si votre pilote a été créé avec la version 1.7 de l’infrastructure et si la version 1.9 de l’infrastructure est installée sur l’ordinateur, si vous définissez VerifyDownLevel sur une valeur différente de zéro, le vérificateur doit inclure des tests qui ont été ajoutés à la version 1.9 du vérificateur lors de l’exécution de votre pilote.

VerifyOn

REG_DWORD

Définissez sur une valeur différente de zéro pour activer la macro WDFVERIFY définie dans Wdfassert.h, ou définissez sur zéro pour désactiver la macro. Si la valeur VerifyrOn est définie, VerifyOn est implicitement défini sur différent de zéro.