Configuration du transport du débogueur EXDI

Article
11/01/2024

Cette rubrique explique comment configurer le débogage en mode noyau à l’aide d’EXDI. L’interface de débogage étendue (EXDI) est une couche d’adaptation entre un débogueur logiciel et une cible de débogage.

Les outils de débogage pour Windows prennent en charge le débogage du noyau à l’aide d’EXDI à partir de Windows version 22000.
L’interface utilisateur permettant de configurer EXDI est disponible dans le débogueur à partir de la version 1.2410.11001.0.

EXDI peut permettre d’établir une connexion avec l’environnement virtuel QEMU. Pour plus d’informations, consultez Configuration du débogage en mode noyau QEMU à l’aide d’EXDI.

Remarque

EXDI est une forme avancée et spécialisée de débogage pour des environnements spécifiques. Nous recommandons l’utilisation d’une connexion KDNET standard, plus facile à configurer. Pour une configuration automatique du débogage réseau, consulter la configuration automatique du débogage réseau du noyau KDNET.

Présentation du serveur EXDI COM

EXDI est une interface qui étend WinDbg en ajoutant la prise en charge des débogueurs matériels (par exemple, basé sur JTAG ou GdbServer). Le diagramme ci-dessous illustre le rôle d’EXDI-GdbServer.

Diagramme de pile illustrant le rôle d’EXDI-GdbServer avec WinDbg-DbgEng en haut, une interface EXDI et un serveur COM EXDI communiquant avec un serveur GDB.

Un serveur COM fait référence à un composant binaire implémentant une interface COM. Dans ce cas, exdi3.idl implémenté par ExdiGdbSrv.dll pour le client de protocole du débogueur Windows.

Le ExdiGdbsrv.dll lui-même implémente le côté client du protocole GDB-RSP côté serveur GDB (ou parfois appelé stub de serveur GDB) est implémenté par le serveur GDB QEMU (ou Trace32/OpenOCD/UEFI GDB stub, etc.)

Étant donné que la connexion EXDI n’a aucune dépendance sur Windows ou le protocole KDNET de débogage Windows chargé sur le PC cible. Étant donné que ces composants de débogueur logiciel ne sont pas obligatoires, EXDI peut s’avérer utile au début de l’affichage de l’appareil et dans le débogage des problèmes de démarrage du système d’exploitation.

Important

EXDI n’utilisant pas le protocole KDNET, le débogueur connecté dispose de beaucoup moins d’informations sur ce qui se passe sur le PC et de nombreuses commandes fonctionneront différemment ou ne fonctionneront pas du tout. L’accès aux symboles privés pour le code en cours de débogage peut permettre au débogueur de mieux comprendre l’exécution du code des systèmes cibles. Pour en savoir plus, consulter Symboles publics et privés.

Configuration requise pour l’appareil EXDI en mode noyau

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

Ce qui suit est nécessaire :

Sur les ordinateurs cible et hôte, une carte réseau prise en charge par l’environnement souhaité, tel que QEMU.
Une connexion réseau entre la cible et l’hôte à l’aide du protocole TCP/IP.
Windows 10 ou Windows 11 version 22000 ou ultérieure.

Limites

Comme décrit ci-dessus, EXDI n’utilisant pas le protocole KDNET, le débogueur connecté dispose de moins d’informations sur le système cible et l’utilisation du débogueur est différent. Sans accès aux symboles privés pour le code cible, de nombreuses commandes qui utilisent des symboles pour comprendre l’état du système cible ne fonctionneront pas. Dans ce cas, il est possible de visualiser le contenu de la mémoire et du registre, et de désassembler le code. Sans symboles privés, il peut s’aérer très difficile et chronophage de déterminer l’emplacement de l’exécution du code ou l’exécution d’autres tâches de débogage courantes.

Débogage EXDI et KDNET simultanés

Dans certains scénarios complexes, par exemple dans l’affichage précoce de l’appareil, il peut être utile de disposer de deux connexions à l’appareil cible. Une EXDI et une KDNET. Si la cible est un système d’exploitation Windows, le débogage de logiciels KDNET est configuré comme il le serait normalement, par exemple pour se connecter à une machine virtuelle. Dans cette configuration, l’un des deux débogueurs simultanés peut s’introduire pour déboguer le code sur l’ordinateur cible.

WinDbg dans le serveur de processus

Le composant EXDI binaire peut s’exécuter en dehors du processus Windbg ou dans le processus Windbg. L’utilisation de l’interface utilisateur EXDI ou de la Inproc=<EXDI COM server binary> fiabilité améliore considérablement la fiabilité en réduisant les erreurs de démarrage COM. Par conséquent, il est toujours recommandé d’exécuter la session EXDI avec le paramètre Inproc, qui est toujours activé lors de l’utilisation de l’interface utilisateur.

Pour le démarrage de ligne de commande, l’option par défaut est hors processus, mais inprocess doit être activée à l’aide du InProc=ExdiGdbDrv.dll paramètre.

Client serveur COM GDB

Cette rubrique décrit l’utilisation du client de serveur GDB EXDI COM (ExdiGdbSrv.dll), qui implémente l’interface du débogueur COM EXDI. On peut utiliser la même interface COM pour implémenter d’autres interfaces, notamment un serveur COM EXDI pour JTAG-DCI.

Résumé du processus d’utilisation d’une connexion EXDI

Utilisez ce processus pour utiliser une connexion EXDI avec WinDbg.

Télécharger et installer les outils de débogage Windows sur le système hôte.
Lancez WinDbg à l’aide de l’interface utilisateur ou de l’option -kx pour vous connecter au serveur EXDI.
Utilisez WinDbg pour déboguer le système cible à l’aide d’un sous-ensemble de commandes de débogueur disponibles.

Pour obtenir un exemple de scénario d’utilisation d’EXDI, consultez Configuration du débogage en mode noyau QEMU à l’aide d’EXDI.

Télécharger et installer les outils de débogage Windows

Installer les outils de débogage Windows sur le système hôte. Pour des informations sur le téléchargement et l’installation des outils de débogage, consulter la rubrique Outils de débogage pour Windows.

Lancer WinDbg et se connecter au serveur EXDI

Les options suivantes peuvent être configurées dans l’interface utilisateur de connexion du noyau EXDI.

Interface utilisateur de connexion du noyau EXDI Windbg, avec les options de connexion affichées, notamment l’adresse IP et le port.

[Trace32|BMC-OpenOCD|QEMU|VMWare|UEFI] Type cible Sélectionner en fonction du type cible que vous souhaitez déboguer. Les types cibles suivants sont disponibles.
- Trace32 : Configuration du serveur GDB du débogueur GDB de Lauterbach Trace32
- BMC-OpenOCD : Configuration du serveur GDB du débogueur BMC-OpenOCD
- QEMU : Configuration du serveur GDB du simulateur QEMU SW
- VMWare : Configuration du serveur VMWare GDB
- UEFI : débogage du microprogramme UEFI
Architecture [x86 | ARM64 | x64] cible : architecture du processeur cible. Notez que tous les types cibles peuvent ne pas prendre en charge toutes les architectures cibles.
Système d’exploitation cible : sélectionnez en fonction du système d’exploitation [Windows|Linux] cible que vous souhaitez déboguer.
Taille [None | 0xFE - PreNT |0xFFE - NT] heuristique de l’analyse d’images : sélectionnez l’une des trois options pour déterminer la taille heuristique de l’analyse d’images. Cette valeur configure la façon dont le moteur de débogueur analyse la mémoire à la recherche de la signature PE DOS, utilisée pour collecter l’état d’exécution du code. Si la valeur d’attribut n’est pas spécifiée (ou « 0 »), le moteur du débogueur n’utilise pas l’heuristique rapide et revient à l’heuristique héritée qui analyse toute la mémoire à la recherche de la signature PE DOS. La valeur par défaut est sélectionnée pour chaque type cible et est recommandée.
Serveur et port TargetIPAddress:TargetPortAddress Gdb : défini sur une chaîne qui contient, IPTargetAddress, deux-points et PortAddress cible. Par exemple, LocalHost:1234 ou 168.82.1.5:5555.
Arrêt sur les connexions [on|off] Cochez la case à cocher pour s’arrêter à la cible une fois la connexion établie.
Options avancées

Afficher le journal des paquets de communication : cochez la case à cocher pour afficher les valeurs hexadécimales du journal [on|off] des paquets de communications GDBServer brut pour le débogage et la résolution des problèmes.

Une fois les options souhaitées sélectionnées, sélectionnez Ok pour vous connecter.

Configurer des options avancées à l’aide des fichiers XML de configuration EXDI

Les options les plus nécessaires sont disponibles dans l’interface utilisateur décrite dans cette rubrique. Pour plus d’informations sur la configuration des options avancées à l’aide des fichiers XML de configuration EXDI, consultez les fichiers de configuration EXDI XML.

Exemple EXDI de ligne de commande WinDbg

Pour lancer la session windbg qui utilise l’interface EXDI à l’invite de commandes, utilisez ces options.

c:\Debuggers> windbg.exe -v -kx exdi:CLSID={29f9906e-9dbe-4d4b-b0fb-6acf7fb6d014},Kd=Guess,InProc=ExdiGdbDrv.dll,DataBreaks=Exdi

Pour afficher une sortie supplémentaire utile à des fins de diagnostic, on peut utiliser la session -v: détaillée. Pour des informations générales sur les options WinDbg, consulter Options de ligne de commande WinDbg. Pour en savoir plus, consulter les paramètres de chargement d’EXDI WinDbg ci-dessous.

La console du débogueur affiche l’initialisation du transport EXDI.

EXDI: DbgCoInitialize returned 0x00000001
EXDI: CoCreateInstance() returned 0x00000000
EXDI: QueryInterface(IExdiServer3) returned 0x00000000
EXDI: Server::GetTargetInfo() returned 0x00000000
EXDI: Server::SetKeepaliveInterface() returned 0x00000000
EXDI: Server::GetNbCodeBpAvail() returned 0x00000000
EXDI: ExdiNotifyRunChange::Initialize() returned 0x00000000
EXDI: LiveKernelTargetInfo::Initialize() returned 0x00000000
EXDI: Target initialization succeeded
Kernel Debugger connection established

Session WinDbg principale affichant EXDI CLSID dans le titre de la fenêtre.

La fenêtre de console EXDIGdbServer peut également afficher des informations sur l’état de la connexion EXDI. Pour en savoir plus sur la console, consulter Résolution des problèmes.

Paramètres de chargement EXDI WinDbg

Les paramètres suivants sont utilisés avec WinDbg pour démarrer une session de noyau EXDI.

-kx EXDI :Options

Les options EXDI suivantes sont disponibles via l’option -kx. Chaque option doit être séparée à l’aide d’une virgule.

Paramètre	Description
CLSID	ID de classe affecté au LiveExdiGdbSrvServer (tel que défini dans le fichier ExdiGdbSrv.idl).
Kd=Guess -or- NtBaseAddr	Le moteur de débogueur utilisera un mécanisme heuristique général , ou recherche l’adresse de base NT.
ForceX86	Force le moteur de débogueur à utiliser l’interface IeXdiX86Context3 pour obtenir/définir le contexte du processeur.
DataBreaks=Exdi	Autoriser l’utilisation de points d’arrêt de données.
Inproc	Autoriser l’utilisation d’une macro inproc Exdi-Server. Cette option est recommandée : InProc=ExdiGdbDrv.dll
PathToSrvCfgFiles	Chemin d’accès aux fichiers de configuration XML pour EXDI.

Contrôle de la recherche heuristique et de la taille heuristique

Comme décrit précédemment, le débogueur utilise un algorithme heuristique pour localiser l’adresse de base NT. Pour annuler la recherche heuristique, lors du démarrage de WinDbg via la ligne de commande, effectuez les étapes suivantes.

Définissez heuristicScanSize sur 0 dans le fichier exdiconfigdata.xml pour le serveur cible auquel vous allez vous attacher.
Utilisez le kd=NtBaseAddr type heuristique sur la ligne de commande Windbg.

Pour plus d’informations sur l’utilisation des fichiers de configuration XML, consultez les fichiers de configuration XML EXDI.

Utiliser WinDbg pour déboguer le système cible - points d’arrêt

La dbgeng.dll utilise un algorithme heuristique pour rechercher l’emplacement de l’adresse de charge de base NT au moment où la commande d’arrêt s’est produite. Si les symboles privés ne sont pas disponibles, ce processus échoue.

Cela signifie que dans de nombreuses séquences de connexion, l’arrêt ne fonctionnera pas comme prévu. si on accède manuellement au code, il s’agira d’un emplacement aléatoire que Windows est en train d’exécuter à ce moment-là. Comme les symboles du code cible peuvent ne pas être disponibles, il peut s’avérer difficile de définir des points d’arrêt à l’aide de symboles.

Commandes de débogueur

Les commandes comme celles ci-dessous qui accèdent directement à la mémoire fonctionnent.

k, kb, kc, kd, kp, kP, kv (Afficher l’arborescence des appels de procédure)

r (Registres)

d, da, db, dc, dd, dD, df, dp, dq, du, dw (Afficher la mémoire)

u (Désassembler)

On peut également parcourir le code à l’aide de p (Étape).

Il existe également des commandes que l’on peut utiliser pour tenter de localiser le code qu’on souhaite déboguer.

s (Rechercher dans la mémoire)

.imgscan (Rechercher des en-têtes d’image)

Imgscan peut être utile pour le débogage EDXI, car contrairement au débogage traditionnel du noyau basé sur KDNET, il n’est pas toujours possible de définir des points d’arrêt basés sur des symboles. La localisation d’une image cible souhaitée peut permettre d’utiliser son emplacement pour définir un point d’arrêt d’accès à la mémoire.

.exdicmd (commande EXDI)

.exdicmd envoie une commande EXDI au système cible à l’aide de la connexion de débogage EXDI active. Pour en savoir plus, consulter .exdicmd (commande EXDI).

Dépannage

Utiliser la sortie de la fenêtre ExdiGdbServer pour surveiller la séquence de connexion.

Fenêtre de texte ExdiGdbServer affichant des nombres hexadécimaux longs.

Problème : erreur : Impossible d’établir une connexion avec gbDServer. Vérifier le chaîne de connexion <hostname/ip>:portnumber

Ce problème peut se produire pour plusieurs raisons :

La ExdiGdbSrv.dll ne peut pas se connecter au serveur GDB cible.
Le serveur GDB n’est pas encore en cours d’exécution sur la cible.
Problèmes de pare-feu : vérifier que les deux adresses IP sont accessibles en utilisant ping, un traceur ou un autre outil pour vérifier que le trafic GDB peut passer à travers le pare-feu.

Problème : le scénario d’erreur avec le système cible n’est pas disponible - DbgCoInitialize a renvoyé 0x00000001

La sortie suivante peut être renvoyée si le système cible n’est pas chargé ou n’est pas disponible.

Microsoft (R) Windows Debugger Version 10.0.20317.1 AMD64
Copyright (c) Microsoft Corporation. All rights reserved.

EXDI: DbgCoInitialize returned 0x00000001

Il s’agit d’une erreur courante lorsque le serveur COM ExdiGdbSrv.dll n’a pas pu se connecter à QEMU GDServer, de sorte qu’il peut échouer pour la raison suivante :

La session précédente de la ExdiGdbSrv.dll est toujours hébergée par un processus de dllhost.exe. Il faut donc arrêter le processus de dllhost.exe. Utilisez TaskList à une invite de commandes pour localiser le PID de dllhost.exe qui héberge le ExdiGdbSrv.dll. Utilisez et supprimez TaskKill /PID <PID ID> /f le PID associé. Pour plus d’informations sur l’utilisation des PID, consultez Recherche de l’ID de processus.
Le QEMU gdbserver n’a pas encore été lancé ou le fichier exdiconfigdata.xml contient des valeurs IP:Port non valides. Si la session WinDbg est lancée sur le même PC hôte que la machine virtuelle Windows QEMU, l’adresse IP=LocalHost.
Échec lors du lancement du serveur COM EXDI (ExdiGDbSrv.dll) via le processus dllhost.exe (associé à COM). Pour résoudre ce problème, redémarrer le PC du débogueur hôte ou se déconnecter de Windows, puis se reconnecter. Si cela ne fonctionne pas, réinscrire le serveur COM EXDI après le redémarrage/la connexion.
- regsvr32.exe <full path to the ExdiGdbSrv.dll)

Problème : la session de débogage n’a pas pu être lancée : FAILURE HR=0x80004005 :Failed to AttachKernel.

Ce problème peut se produire pour plusieurs raisons :

Comme décrit ci-dessus, il est possible que la session précédente de la ExdiGdbSrv.dll soit toujours active. Rechercher et arrêter l’hôte DLL associé, comme décrit ci-dessus.

Boîte de dialogue WinDbg affichant l’échec avec HR 0x80004005.

Problème : impossible de démarrer le débogage du noyau à l’aide d’EXDI.

Ce problème peut se produire pour plusieurs raisons :

Une autre instance de la ExdiGdbSrv.dll (hébergée par dllhost.exe) s’exécute sur l’ordinateur du débogueur hôte.
Arrêter l’instance supplémentaire du service COM hébergeant la ExdiGdbSrv.dll.
- Commencer par répertorier les processus, à l’aide d’un utilitaire comme TList sur le PC hôte. La DLLHost qui héberge la ExdiGdbSrv.dll affiche ExdiGdbServer.
  
  tlist 261928 dllhost.exe ExdiGdbServer
- Utiliser kill -f XXXXX à l’invite de commande du débogueur pour arrêter le processus à l’aide du numéro de processus.

Problème : erreur : impossible de configurer la session GdbServer.

Ce problème peut se produire pour plusieurs raisons :

Une erreur s’est produite lors de la localisation des informations de session, telles que le chemin d’accès aux fichiers de configuration XML.

Problème : erreur : la variable d’environnement EXDI_GDBSRV_XML_CONFIG_FILE n’est pas définie.

Ce problème peut se produire pour plusieurs raisons :

Les variables d’environnement ExdiGdbSrv.dll ne sont pas définies ou ne sont pas disponibles dans l’environnement.

Problème : Erreur : la variable d’environnement EXDI_GDBSRV_XML_CONFIG_FILE n’est pas définie. L’exemple Exdi-GdbServer ne se poursuit pas à ce stade. Définissez le chemin d’accès complet au fichier de configuration Exdi XML.

Ce problème peut se produire pour plusieurs raisons :

La variable d’environnement EXDI_GDBSRV_XML_CONFIG_FILE n’est pas définie. Dans certains cas, ExdiGDbSrv.dll continue à fonctionner en appuyant sur le bouton « OK », mais windbg.exe échoue à interroger les registres système (par exemple, via les fonctions rdmsr/wrmsr).