Étendues et groupes de symboles

Un groupe de symboles contient un ensemble de symboles pour une manipulation efficace en tant que groupe. Un groupe de symboles peut être créé et rempli manuellement ou peut être généré et mis à jour automatiquement en fonction de symboles dans des étendues lexicales, telles que des variables locales et des arguments de fonction. L’interface IDebugSymbolGroup est utilisée pour représenter un groupe de symboles.

Il existe deux façons de créer un groupe de symboles. Un groupe de symboles vide est retourné par CreateSymbolGroup, et le groupe de symboles pour l’étendue lexicale actuelle est retourné par GetScopeSymbolGroup.

Note Le groupe de symboles généré à partir de l’étendue actuelle est un instantané des variables locales. Si une exécution se produit dans la cible, les symboles peuvent ne plus être précis. En outre, si l’étendue actuelle change, le groupe de symboles ne représentera plus l’étendue actuelle (car il continuera à représenter l’étendue pour laquelle il a été créé).

Les symboles peuvent être ajoutés à un groupe de symboles à l’aide de AddSymbol et supprimés à l’aide de RemoveSymbolByIndex ou RemoveSymbolByName. La méthode OutputAsType indique au débogueur d’utiliser un type de symbole différent lors de la gestion des données d’un symbole.

Note Les valeurs des symboles délimités peuvent ne pas être exactes. En particulier, l’architecture de la machine et les optimisations du compilateur peuvent empêcher le débogueur de déterminer avec précision la valeur d’un symbole.

Les informations d’entrée de symbole sont une description d’un symbole, y compris son emplacement et son type. Pour trouver ces informations pour un symbole dans un module, utilisez IDebugSymbols3::GetSymbolEntryInformation. Pour trouver ces informations pour un symbole dans un groupe de symboles, utilisez IDebugSymbolGroup2::GetSymbolEntryInformation. Consultez DEBUG_SYMBOL_ENTRY pour plus d’informations sur la saisie de symboles.

Les méthodes suivantes retournent des informations sur un symbole dans un groupe de symboles :

• GetSymbolName retourne le nom du symbole.

• GetSymbolOffset retourne l’adresse absolue dans l’espace d’adressage virtuel de la cible du symbole, si le symbole a une adresse absolue.

• GetSymbolRegister retourne le registre contenant le symbole, si le symbole est contenu dans un registre.

• GetSymbolSize retourne la taille des données du symbole.

• GetSymbolTypeName retourne le nom du type du symbole.

• GetSymbolValueText retourne la valeur du symbole sous forme de chaîne.

Si un symbole est stocké dans un registre ou dans un emplacement de mémoire connu du moteur de débogueur, sa valeur peut être modifiée à l’aide de WriteSymbol.

Un symbole est un symbole parent s’il contient d’autres symboles. Par exemple, une structure contient ses membres. Un symbole est un symbole enfant s’il est contenu dans un autre symbole. Un symbole peut être à la fois un symbole parent et un symbole enfant. Chaque groupe de symboles a une structure plate et contient des symboles parents et leurs enfants. Chaque symbole a une profondeur : les symboles sans parents dans le groupe de symboles ont une profondeur de zéro, et la profondeur de chaque symbole enfant est supérieure à la profondeur de son parent. Les enfants d’un symbole parent peuvent être présents ou non dans le groupe de symboles. Lorsque les enfants sont présents dans le groupe de symboles, le symbole parent est appelé développé. Pour ajouter ou supprimer les enfants d’un symbole dans un groupe de symboles, utilisez ExpandSymbol.

Le nombre de symboles dans un groupe de symboles est retourné par GetNumberSymbols. L’index d’un symbole dans un groupe de symboles est un numéro d’identification ; l’index est compris entre zéro et le nombre de symboles moins un. Chaque fois qu’un symbole est ajouté ou supprimé d’un groupe de symboles (par exemple, en développant un symbole), l’index de tous les symboles du groupe de symboles peut changer.

Les paramètres de symbole, y compris des informations sur les relations parent-enfant, sont disponibles à l’aide de GetSymbolParameters. Cette méthode retourne une structure DEBUG_SYMBOL_PARAMETERS .

Les symboles d’un groupe de symboles peuvent être imprimés dans le flux de sortie du débogueur à l’aide de la méthode OutputSymbols.

Étendues

L’étendue actuelle, ou contexte local actuel, détermine les variables locales exposées par le moteur de débogueur. L’étendue comporte trois composants :

1. Frame de pile.

2. Instruction actuelle.

3. Contexte de registre.

Si le frame de pile se trouve en haut de la pile des appels, l’instruction actuelle est l’instruction qui a entraîné le dernier événement. Sinon, l’instruction actuelle est l’appel de fonction qui a entraîné la prochaine trame de pile supérieure.

Les méthodes GetScope et SetScope peuvent être utilisées pour obtenir et définir l’étendue actuelle. Lorsqu’un événement se produit, l’étendue actuelle est définie sur l’étendue de l’événement. L’étendue actuelle peut être réinitialisée à l’étendue du dernier événement à l’aide de ResetScope.

Contexte de thread

Le contexte de thread est l’état conservé par Windows lors du basculement de threads. Ceci est similaire au contexte de registre, à ceci près qu’il existe un état de processeur de noyau uniquement qui fait partie du contexte de registre, mais pas du contexte de thread. Cet état supplémentaire est disponible en tant que registres pendant le débogage en mode noyau.

Le contexte de thread est représenté par la structure CONTEXT définie dans ntddk.h. Cette structure dépend de la plateforme et son interprétation dépend du type de processeur effectif. Les méthodes GetThreadContext et SetThreadContext peuvent être utilisées pour obtenir et définir le contexte du thread.