Comment activer le débogage d’un pilote UMDF

Vous pouvez utiliser les configurations suivantes pour déboguer un pilote du User-Mode Driver Framework (UMDF) pendant le développement. Toutes les configurations impliquent deux ordinateurs, un hôte et une cible.

• Copiez manuellement le pilote sur l'appareil cible. Effectuez un débogage en mode utilisateur sur la cible. Dans ce scénario, vous vous attachez manuellement à une instance du processus hôte du pilote s'exécutant sur la cible.
• Copiez manuellement le pilote sur la cible, puis effectuez le débogage en mode noyau à partir de l’hôte.

Nous vous recommandons d’effectuer tous les tests et développement de pilotes UMDF avec un débogueur de noyau attaché.

Meilleures pratiques

Nous vous recommandons d’effectuer tous les tests de pilotes UMDF avec un débogueur de noyau connecté.

Les paramètres suivants sont recommandés. Vous pouvez définir ces paramètres manuellement ou utiliser l’outil WDF Verifier Control Application (WDFVerifier.exe) dans le WDK pour afficher ou modifier ces paramètres.

• Activer le vérificateur d’application sur WUDFHost.exe:

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

  Si des exceptions se produisent, Application Verifier envoie des messages de diagnostic au débogueur et s’arrête.

• Si vous utilisez une session de débogage en mode noyau, définissez HostFailKdDebugBreak afin que le réflecteur se décompose dans le débogueur en mode noyau avant de terminer le processus hôte du pilote. Ce paramètre est activé par défaut à partir de Windows 8.

• Désactivez le regroupement en définissant UmdfHostProcessSharing sur ProcessSharingDisabled. Pour plus d’informations, consultez Spécification des directives WDF dans les fichiers INF.

• Par défaut, lorsqu’un appareil UMDF échoue, le framework tente de le redémarrer jusqu’à cinq fois. Vous pouvez désactiver le redémarrage automatique en définissant DebugModeFlags sur 0x01. Pour plus d’informations, consultez Valeurs de Registre pour le débogage des pilotes WDF.

• Redémarrez votre ordinateur.

• Pour le débogage des problèmes de pilote UMDF, consultez Déterminer pourquoi le réflecteur a arrêté le processus hôte et le pilote UMDF se bloque

Utilisation de WinDbg pour attacher manuellement (débogage en mode utilisateur)

Sur l’ordinateur cible, vous pouvez attacher manuellement WinDbg à l’instance de WUDFHost qui héberge le pilote. Lorsque vous attachez, vous vous connectez au débogueur et vous pouvez définir des points d’arrêt dans votre pilote.

Étant donné que l’initialisation du pilote se produit peu après le chargement de WUDFHost, vous n'avez pas le temps de vous y attacher manuellement afin de déboguer le code d'initialisation. Au lieu de cela, définissez une valeur de Registre pour que le processus hôte attende un certain nombre de secondes au moment de l’initialisation de l’hôte ou du temps de chargement du pilote. Ce délai vous donne le temps d’attacher WinDbg à l’instance correcte du processus WUDFHost.

Suivez ces étapes :

1. Dans le Registre sur l’ordinateur cible, définissez HostProcessDbgBreakOnStart ou HostProcessDbgBreakOnDriverLoad sur un certain nombre de secondes et redémarrez.
2. Sur l’ordinateur cible, ouvrez WinDbg en tant qu’administrateur.
3. Dans le menu Fichier , choisissez Attacher au processus. Sélectionnez Par exécutable et recherchez tous les processus nommés WUDFHost.exe (il se peut qu’il n’y en ait aucun). S’il existe des processus nommés WUDFHost.exe, notez leurs identificateurs de processus pour référence ultérieure.
4. Dans Le Gestionnaire de périphériques, activez le pilote.
5. Répétez l’étape 2 et recherchez une nouvelle instance de WUDFHost.exe. Si vous ne voyez pas une nouvelle instance de WUDFHost.exe, sélectionnez Annuler et choisissez Attacher au processus de nouveau. Lorsque vous trouvez la nouvelle instance de WUDFHost.exe, sélectionnez-la, puis sélectionnez OK.

Si le regroupement d’appareils est en cours d’utilisation et que vous définissez la valeur de Registre HostProcessDbgBreakOnDriverLoad, vous pourriez observer des interruptions du débogueur causées par le chargement d'autres pilotes. Vous pouvez désactiver le regroupement d’appareils à l’aide du mode de débogage UMDF.

Pour utiliser le mode débogage, utilisez l’option F5 dans Visual Studio ou définissez les valeurs DebugModeFlags et DebugModeBinaries dans le Registre.

Pour plus d’informations sur les valeurs de Registre UMDF, consultez Valeurs de Registre pour le débogage des pilotes WDF (KMDF et UMDF).

Utilisation de WinDbg pour déboguer à distance à partir d’une machine hôte (débogage en mode noyau)

À partir d’un hôte distant, établissez une session de débogage en mode noyau. Définissez ensuite le processus actuel sur l’instance de Wudfhost qui héberge votre pilote. Si vous déboguez à partir d’un débogueur de noyau distant, définissez HostProcessDbgBreakOnDriverStart ou HostProcessDbgBreakOnDriverLoad sur 0x80000000 pour indiquer qu'il n'y a pas de délai d’expiration, mais pour entrer dans le débogueur du noyau.

Procédez comme suit :

1. Désactivez le regroupement. Activez DebugModeFlags et répertoriez votre pilote dans DebugModeBinaries.

2. Si votre pilote utilise UMDF 1.11 ou version ultérieure, HostFailKdDebugBreak est activé par défaut. Ignorez cette étape.

   Si votre pilote utilise UMDF 1.9 ou version antérieure, définissez HostFailKdDebugBreak sur 1.

3. Si vous déboguez des problèmes liés aux délais d’expiration, désactivez HostProcessDbgBreakOnDriverStart et HostProcessDbgBreakOnDriverLoad. (Lorsque HostProcessDbgBreakOnDriverStart ou HostProcessDbgBreakOnDriverLoad n’est pas égal à zéro, le framework désactive les timeouts afin que le reflector ne termine pas l'hôte lorsqu'un débogueur mode utilisateur est relié au processus hôte.) Si vous devez déboguer le code d’initialisation du pilote, au lieu d’utiliser ces deux valeurs, essayez d’émettre la commande suivante dans WinDbg avant que votre pilote ne se charge : sxe ld :MyDriver.dll (interruption lors du chargement du module)

4. Redémarrez si vous avez apporté des modifications au Registre.

5. Selon les sélections que vous avez effectuées au cours des étapes précédentes, votre débogueur de noyau distant s’interrompt lorsque le pilote charge ou décharge sur la cible.