Comment activer le débogage d’un pilote UMDF

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

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

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

Meilleures pratiques

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

Voici les paramètres recommandés. Vous pouvez les définir manuellement ou utiliser l’outil WDF Verifier Control Application (WDFVerifier.exe) dans wdK pour afficher ou modifier ces paramètres.

• Activez Application Verifier 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’interrompt.

• Si vous utilisez une session de débogage en mode noyau, définissez HostFailKdDebugBreak afin que le réflecteur s’arrête dans le débogueur en mode noyau avant de mettre fin au 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 de 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 liés au pilote UMDF, consultez Détermination de la raison pour laquelle le réflecteur a arrêté le processus hôte et Débogage des pannes du pilote UMDF

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 l’attachez, vous entrez dans le 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, il n’est pas possible d’attacher manuellement à temps pour déboguer le code d’initialisation. Au lieu de cela, vous pouvez définir 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 chargement du pilote. Ce délai vous donne le temps d’attacher WinDbg à la bonne instance du processus WUDFHost.

Procédez comme suit :

1. Dans le Registre de 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, puis recherchez tous les processus nommés WUDFHost.exe (il n’y en a peut-être pas). S’il existe des processus nommés WUDFHost.exe, notez leurs identificateurs de processus pour référence ultérieure.
4. Dans 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 de nouvelle instance de WUDFHost.exe, cliquez sur Annuler, puis choisissez à nouveau Attacher au processus. Lorsque vous avez trouvé la nouvelle instance de WUDFHost.exe, sélectionnez-la, puis cliquez sur OK.

Si le regroupement de périphériques est en cours d’utilisation et que vous définissez la valeur de Registre HostProcessDbgBreakOnDriverLoad , vous pouvez voir des interruptions du débogueur en raison du 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’un ordinateur hôte (débogage en mode noyau)

À partir d’un hôte distant, établissez une session de débogage en mode noyau, puis définissez le processus actuel sur le instance de Wudfhost qui héberge votre pilote. Si vous déboguez à partir d’un débogueur de noyau distant, vous pouvez définir HostProcessDbgBreakOnDriverStart ou HostProcessDbgBreakOnDriverLoad sur 0x80000000 pour ne spécifier aucun délai d’expiration, mais entrer dans le débogueur du noyau.

Suivez ces étapes :

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 est différent de zéro, le framework désactive les délais d’expiration afin que le réflecteur n’arrête pas l’hôte pendant qu’un débogueur en mode utilisateur est attaché 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 le chargement de votre pilote : sxe ld:MyDriver.dll (arrêt sur le chargement du module)

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

5. Selon les sélections effectuées ci-dessus, votre débogueur de noyau distant doit s’arrêter lorsque le pilote charge ou décharge sur la cible.