Utilisation du vérificateur UMDF

L’infrastructure fournit des fonctionnalités de vérification intégrées que vous pouvez utiliser pour tester un pilote UMDF (User-Mode Driver Framework) en cours d’exécution. Cette fonctionnalité, parfois appelée vérificateur UMDF, valide largement l’état de votre pilote et les arguments que le pilote passe aux méthodes d’objet framework. Vous pouvez utiliser le vérificateur UMDF lui-même ou avec l’outil de vérification d’application à usage général (AppVerif.exe).

Le vérificateur UMDF vérifie l’acquisition de verrous et les hiérarchies, vérifie l’annulation et l’utilisation correctes des E/S et de la file d’attente, et garantit que le pilote et l’infrastructure suivent les contrats documentés.

Le vérificateur UMDF provoque des échecs dans le code du pilote UMDF pour vérifier le processus hôte. Toutefois, une vérification des bogues UMDF n’entraîne pas l’affichage d’un écran de texte bleu avec des informations sur l’erreur. Au lieu de cela, une vérification des bogues UMDF :

• Crée un fichier de vidage de mémoire et enregistre le fichier dans le répertoire du fichier journal de l’ordinateur (par exemple, %windir%\System32\LogFiles\WUDF\Xxx.dmp).

  Remarque À partir de UMDF 2.15, le répertoire du journal est %ProgramData%\Microsoft\WDF.

• Crée un rapport d’erreur pour Microsoft (opt-in).

• Saute dans le débogueur s’il est attaché à l’ordinateur.

• Met fin au processus hôte et désactive l’appareil.

À compter de UMDF 2.0, le vérificateur UMDF émet des points d’arrêt dans certains cas et provoque un contrôle de bogue UMDF dans d’autres. Ce comportement est similaire à celui du vérificateur KMDF.

Nous vous recommandons vivement d’effectuer tous les tests et développement de votre pilote après avoir activé Application Verifier (AppVerif.exe) sur WUDFHost.exe. Utilisez la commande suivante, attachez un débogueur, puis redémarrez.

AppVerif -enable Heaps Exceptions Handles Locks Memory TLS Leak -for WudfHost.exe

À compter de la version 2.0 de UMDF, si vous exécutez Application Verifier sur le processus hôte du pilote (Wudfhost), le vérificateur UMDF est automatiquement activé pour tous les pilotes UMDF 2.0 de cet hôte, ainsi que tous les pilotes UMDF 2.0 dans les processus d’hôte de pilotes futurs.

Dans UMDF 1.11 et versions antérieures, le vérificateur du framework est toujours activé et vous ne pouvez pas le désactiver.

Activation et désactivation du vérificateur UMDF

Vous pouvez activer manuellement le vérificateur UMDF en définissant VerifierOn sur une valeur différente de zéro dans la sous-clé Parameters\Wdf du sous-clé HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<driver name> registry key.

Notez que l’existence d’une valeur VerifierOn , même définie sur zéro, remplace la liaison avec Application Verifier. Par conséquent, nous vous recommandons de supprimer la valeur si vous ne la forcez pas, plutôt que de la définir sur zéro.

Pour déterminer si le vérificateur UMDF est activé, définissez un point d’arrêt à un emplacement après que votre pilote appelle WdfDriverCreate et utilisez la commande d’extension du débogueur !wdfdriverinfo :

!wdfkd.wdfdriverinfo <votre nom **** >de pilote 0x1

Pour plus d’informations sur les commandes d’extension du débogueur, consultez Extensions de débogueur pour les pilotes basés sur Framework.

Contrôle du comportement du vérificateur

Vous pouvez contrôler le comportement du vérificateur UMDF en modifiant des valeurs dans le Registre. Vous pouvez également utiliser l’application de contrôle WDF Verifier pour définir ces valeurs.

Les valeurs de Registre suivantes peuvent être utilisées avec UMDF 1.pilotes x , ainsi que les pilotes UMDF 2.0 et versions ultérieures.

VerifyDownLevel (REG_DWORD)
Si VerifyDownLevel est défini sur une valeur différente de zéro et si le pilote a été généré 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 du framework inclut uniquement les tests qui existaient lors de la génération du pilote.

Par exemple, si votre pilote a été généré avec la version 1.7 de l’infrastructure et si la version 1.9 de l’infrastructure est installée sur l’ordinateur, la définition de VerifyDownLevel sur non zéro entraîne l’ajout du vérificateur aux tests ajoutés à la version 1.9 du vérificateur lors de l’exécution de votre pilote.

Cette valeur se trouve dans la sous-clé Parameters\Wdf de la clé de Registre HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\DriverName .

TrackObjects (REG_DWORD)
Si TrackObjects est défini sur une valeur différente de zéro, l’infrastructure entre dans le débogueur lorsque le pilote est déchargé, si des objets basés sur l’infrastructure ont fui (pas été supprimés).

Pendant les tests réguliers, vous devez activer TrackObjects et non TrackRefCounts. Si le vérificateur signale que le pilote fuit des objets d’infrastructure, utilisez l’application de contrôle pour activer l’option de vérificateur TrackRefCounts .

Cette valeur se trouve dans la sous-clé DefaultHostProcessGuid de l’HKEY_LOCAL_MACHINE \SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services , où DefaultHostProcessGuid est une valeur que vous pouvez trouver dans la sous-clé HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF .

TrackRefCounts (REG_DWORD)
Si TrackRefCounts est défini sur une valeur différente de zéro, l’infrastructure conserve le nombre de références à chaque objet basé sur le framework. Vous pouvez utiliser l’extension de débogueur !wudfrefhist pour afficher les modifications du nombre de références d’un objet.

La définition de TrackRefCounts sur une valeur différente de zéro dégrade les performances du pilote. Vous devez donc conserver la valeur à zéro, sauf si vous déboguez un bogue de suppression d’objet.

Cette valeur se trouve dans la sous-clé DefaultHostProcessGuid de l’HKEY_LOCAL_MACHINE \SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services , où DefaultHostProcessGuid est une valeur que vous pouvez trouver dans la sous-clé HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF .

Outre les valeurs de Registre répertoriées ci-dessus, les pilotes UMDF 2.0 et versions ultérieures peuvent également utiliser la plupart des valeurs de Registre répertoriées dans Utilisation du vérificateur KMDF.