Anatomie d’une DLL d’extension DbgEng

Une DLL d’extension DbgEng exporte un certain nombre de fonctions de rappel, dont certaines peuvent être des implémentations de commandes d’extension.

Ces DLL d’extension sont chargées par le moteur de débogueur et peuvent fournir des fonctionnalités supplémentaires ou une automatisation des tâches lors de l’exécution du débogage en mode utilisateur ou en mode noyau sur Microsoft Windows.

Si vous avez effectué une installation complète des outils de débogage pour Windows, un exemple d’extension DbgEng appelée « exts » se trouve dans le sous-répertoire sdk\samples\exts du répertoire d’installation.

Commandes d’extension

Une DLL d’extension peut exporter n’importe quel nombre de fonctions utilisées pour exécuter des commandes d’extension. Chaque fonction est explicitement déclarée en tant qu’exportation dans le fichier .def, et son nom doit se composer entièrement de lettres minuscules.

Les fonctions utilisées pour implémenter des commandes d’extension doivent correspondre au prototype PDEBUG_EXTENSION_CALL.

Ces fonctions sont nommées selon la convention C++ standard, sauf que les lettres majuscules ne sont pas autorisées. Le nom de la fonction exportée et le nom de la commande d’extension sont identiques, sauf que la commande d’extension commence par un point d’exclamation ( !). Par exemple, lorsque vous chargez myextension.dll dans le débogueur, puis tapez !stack dans la fenêtre Commande du débogueur, le débogueur recherche une fonction exportée nommée pile dans myextension.dll.

Si myextension.dll n’est pas déjà chargé, ou s’il peut y avoir d’autres commandes d’extension portant le même nom dans d’autres DLL d’extension, vous pouvez taper !myextension.stack dans la fenêtre Debugger Command pour indiquer la DLL d’extension et la commande d’extension dans cette DLL.

Autres fonctions exportées

Une DLL d’extension DbgEng doit exporter DebugExtensionInitialize. Elle est appelée lorsque la DLL est chargée, pour initialiser la DLL. Il peut être utilisé par la DLL pour initialiser des variables globales.

Une DLL d’extension peut exporter DebugExtensionUninitialize. Si elle est exportée, elle est appelée avant que la DLL d’extension ne soit déchargée. Il peut être utilisé par la DLL pour propre avant son déchargement.

Une DLL d’extension peut exporter DebugExtensionNotify. S’il est exporté, il est appelé lorsqu’une session commence ou se termine, et lorsqu’une cible démarre ou s’arrête l’exécution. Ces notifications sont également fournies aux objets IDebugEventCallbacks inscrits auprès d’un client.

Une DLL d’extension peut exporter KnownStructOutput. S’il est exporté, il est appelé lors du chargement de la DLL. Cette fonction retourne une liste de structures que la DLL sait comment imprimer sur une seule ligne. Il peut être appelé ultérieurement pour mettre en forme des instances de ces structures pour l’impression.

Procédure du moteur pour le chargement d’une DLL d’extension DbgEng

Lorsqu’une DLL d’extension est chargée, les fonctions de rappel sont appelées par le moteur dans l’ordre suivant :

1. DebugExtensionInitialize est appelé pour que la DLL d’extension puisse s’initialiser.

2. S’il est exporté, DebugExtensionNotify est appelé si le moteur a une session active, puis appelé à nouveau si la session est suspendue et accessible.

3. En cas d’exportation, KnownStructOutput est appelé pour demander une liste de structures que la DLL sait comment imprimer sur une seule ligne.

Pour plus d’informations sur l’utilisation du débogueur pour charger et décharger une DLL d’extension, consultez Chargement des DLL d’extension du débogueur, et Utilisation des commandes d’extension du débogueur pour plus d’informations sur l’exécution d’une commande d’extension.

Le moteur de débogueur place un bloc try/ except autour d’un appel à une DLL d’extension. Cela protège le moteur contre certains types de bogues dans le code de l’extension ; mais, étant donné que les appels d’extension sont exécutés dans le même thread que le moteur, ils peuvent toujours provoquer un blocage.