Configuration manuelle Kernel-Mode débogage d’une machine virtuelle à l’aide d’un port COM virtuel

Article
04/14/2023

Les outils de débogage pour Windows prennent en charge le débogage du noyau d’une machine virtuelle. La machine virtuelle peut se trouver sur le même ordinateur physique que le débogueur ou sur un autre ordinateur connecté au même réseau. Cette rubrique explique comment configurer manuellement le débogage d’une machine virtuelle à l’aide d’un port COM virtuel via KDCOM.

L’utilisation de la mise en réseau virtuelle KDNET est une option plus rapide et recommandée. Pour plus d’informations, consultez Configuration du débogage réseau d’une machine virtuelle avec KDNET.

Configuration de la machine virtuelle cible

L’ordinateur qui exécute le débogueur est appelé ordinateur hôte, et la machine virtuelle en cours de débogage est appelée machine virtuelle cible.

Important

Avant d’utiliser BCDEdit pour modifier les informations de démarrage, vous devrez peut-être suspendre temporairement les fonctionnalités de sécurité Windows telles que BitLocker et le démarrage sécurisé sur le PC de test. Réactivez ces fonctionnalités de sécurité une fois le test terminé et gérez correctement le PC de test, lorsque les fonctionnalités de sécurité sont désactivées.

Dans la machine virtuelle, dans une fenêtre d’invite de commandes avec élévation de privilèges, entrez les commandes suivantes.

bcdedit /debug on

bcdedit /dbgsettings serial debugport :nbaudrate :115200

où n est le numéro d’un port COM sur la machine virtuelle.
Dans la machine virtuelle, configurez le port COM pour qu’il soit mappé à un canal nommé. Le débogueur se connecte via ce canal. Pour plus d’informations sur la création de ce canal, consultez la documentation de votre machine virtuelle.
Démarrez le débogueur en mode avec élévation de privilèges, par exemple à partir d’une invite de commandes administrateur. Le débogueur doit s’exécuter en mode avec élévation de privilèges lors du débogage d’une machine virtuelle sur un canal série. Une fois que le débogueur est attaché et en cours d’exécution, redémarrez la machine virtuelle cible.

Démarrage de la session de débogage à l’aide de WinDbg

Sur l’ordinateur hôte, ouvrez WinDbg en tant qu’administrateur. Le débogueur doit s’exécuter en mode avec élévation de privilèges lors du débogage d’une machine virtuelle sur un canal série. Dans le menu Fichier , choisissez Débogage du noyau. Dans la boîte de dialogue Débogage du noyau, ouvrez l’onglet COM. Cochez la case Canal et case activée la case Reconnecter. Pour Taux de bauds, entrez 115200. Pour Réinitialisations, entrez 0.

Si le débogueur s’exécute sur le même ordinateur que la machine virtuelle, entrez ce qui suit pour Port.

\\.\pipe\PipeName.

Si le débogueur s’exécute sur un autre ordinateur que la machine virtuelle, entrez ce qui suit pour Port.

\\VMHost\pipe\PipeName

Sélectionnez OK.

Vous pouvez également démarrer WinDbg sur la ligne de commande. Si le débogueur s’exécute sur le même ordinateur physique que la machine virtuelle, entrez la commande suivante dans une fenêtre d’invite de commandes.

windbg -k com :pipe,port=\\.\pipe\PipeName,resets=0,reconnect

Si le débogueur s’exécute sur un autre ordinateur physique que la machine virtuelle, entrez la commande suivante dans une fenêtre d’invite de commandes.

windbg -k com :pipe,port=\\VMHost\pipe\PipeName,resets=0,reconnect

Démarrage de la session de débogage à l’aide de KD

Pour déboguer une machine virtuelle qui s’exécute sur le même ordinateur physique que le débogueur, entrez la commande suivante dans une fenêtre d’invite de commandes avec élévation de privilèges .

kd -k com :pipe,port=\\.\pipe\PipeName,resets=0,reconnect

Pour déboguer une machine virtuelle qui s’exécute sur un autre ordinateur physique que le débogueur, entrez la commande suivante dans une fenêtre d’invite de commandes.

kd -k com :pipe,port=\\VMHost\pipe\PipeName,resets=0,reconnect

Paramètres

VMHost
Spécifie le nom de l’ordinateur sur lequel la machine virtuelle s’exécute.

PipeName
Spécifie le nom du canal que vous avez créé sur la machine virtuelle.

resets=0
Spécifie qu’un nombre illimité de paquets de réinitialisation peut être envoyé à la cible lors de la synchronisation de l’hôte et de la cible. Utilisez le paramètre resets=0 pour Microsoft Virtual PC et autres machines virtuelles dont les canaux suppriment les octets excédentaires. N’utilisez pas ce paramètre pour VMware ou d’autres machines virtuelles dont les canaux ne suppriment pas tous les octets excédentaires.

Reconnecter
Entraîne la déconnexion et la reconnexion automatique du canal par le débogueur en cas d’échec de lecture/écriture. En outre, si le débogueur ne trouve pas le canal nommé au démarrage du débogueur, le paramètre de reconnexion oblige le débogueur à attendre qu’un canal nommé PipeName apparaisse. Utilisez reconnecter pour un PC virtuel et d’autres machines virtuelles qui détruisent et recréent leurs canaux lors d’un redémarrage de l’ordinateur. N’utilisez pas ce paramètre pour VMware ou d’autres machines virtuelles qui conservent leurs canaux pendant le redémarrage d’un ordinateur.

Pour plus d’informations sur les options de ligne de commande supplémentaires, consultez Options de Command-Line KD ou Options de Command-Line WinDbg.

Machines Virtuelles de génération 2

Par défaut, les ports COM ne sont pas présentés dans les machines virtuelles de génération 2. Vous pouvez ajouter des ports COM via PowerShell ou WMI. Pour que les ports COM soient affichés dans la console du Gestionnaire Hyper-V, ils doivent être créés avec un chemin d’accès.

Pour activer le débogage du noyau à l’aide d’un port COM sur une machine virtuelle de génération 2, procédez comme suit :

Désactivez le démarrage sécurisé en entrant cette commande PowerShell :

Set-VMFirmware –VmnameVmName–EnableSecureBoot Off

où VmName est le nom de votre machine virtuelle.
Ajoutez un port COM à la machine virtuelle en entrant cette commande PowerShell :

Set-VMComPort –VMNameVmName1 \\.\pipe\PipeName

Par exemple, la commande suivante configure le premier port COM sur la machine virtuelle TestVM pour se connecter au canal nommé TestPipe sur l’ordinateur local.

Set-VMComPort –VMName TestVM 1 \\.\pipe\TestPipe
Une fois que le débogueur est attaché et en cours d’exécution, arrêtez et démarrez la machine virtuelle à froid pour activer les ports COM dans la machine virtuelle.　Les UARTS émulés ne sont pas disponibles pour le débogage, sauf si au moins un est réellement configuré avec un nom de canal et qu’ils ne peuvent pas être ajoutés à chaud.
Réactivez le démarrage sécurisé une fois que vous avez terminé de mettre à jour les modifications de configuration.

Pour plus d’informations sur les machines virtuelles de génération 2, consultez Vue d’ensemble des machines virtuelles de génération 2.

Remarques

Si l’ordinateur cible a cessé de répondre, l’ordinateur cible est toujours arrêté en raison d’une action de débogage du noyau antérieure, ou si vous avez utilisé l’option de ligne de commande-b, le débogueur s’interrompt immédiatement dans l’ordinateur cible.

Sinon, l’ordinateur cible continue de s’exécuter jusqu’à ce que le débogueur l’ordonne de s’arrêter.

Résolution des problèmes de pare-feu et d’accès réseau

Votre débogueur (WinDbg ou KD) doit avoir accès via le pare-feu. Cela peut même être le cas pour les ports série virtuels pris en charge par les cartes réseau.

Si Windows vous invite à désactiver le pare-feu lorsque le débogueur est chargé, sélectionnez les trois zones.

Selon les spécificités de la machine virtuelle utilisée, vous devrez peut-être modifier les paramètres réseau de vos machines virtuelles pour les relier à l’adaptateur de débogage du réseau noyau Microsoft. Sinon, les machines virtuelles n’auront pas accès au réseau.

Pare-feu Windows

Vous pouvez utiliser Panneau de configuration pour autoriser l’accès via le pare-feu Windows. Ouvrez Panneau de configuration > système et sécurité, puis sélectionnez Autoriser une application via le Pare-feu Windows. Dans la liste des applications, recherchez Le débogueur symbolique de l’interface graphique graphique Windows et le débogueur de noyau Windows. Utilisez les zones case activée pour autoriser ces deux applications à passer par le pare-feu. Redémarrez votre application de débogage (WinDbg ou KD).

Machines virtuelles tierces

Vmware Si vous redémarrez la machine virtuelle à l’aide des fonctionnalités vmWare (par exemple, le bouton de réinitialisation), quittez WinDbg, puis redémarrez WinDbg pour continuer le débogage. Pendant le débogage de machine virtuelle, VMWare consomme souvent 100 % du processeur.