SymbolContext.h revision 2f57db09a49f2a05a620b8163bbe1e748a46ec73
1//===-- SymbolContext.h -----------------------------------------*- C++ -*-===// 2// 3// The LLVM Compiler Infrastructure 4// 5// This file is distributed under the University of Illinois Open Source 6// License. See LICENSE.TXT for details. 7// 8//===----------------------------------------------------------------------===// 9 10 11#ifndef liblldb_SymbolContext_h_ 12#define liblldb_SymbolContext_h_ 13 14#include <vector> 15 16#include "lldb/lldb-private.h" 17#include "lldb/Core/Address.h" 18#include "lldb/Core/Mangled.h" 19#include "lldb/Symbol/ClangASTType.h" 20#include "lldb/Symbol/LineEntry.h" 21 22namespace lldb_private { 23 24class SymbolContextScope; 25//---------------------------------------------------------------------- 26/// @class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h" 27/// @brief Defines a symbol context baton that can be handed other debug 28/// core functions. 29/// 30/// Many debugger functions require a context when doing lookups. This 31/// class provides a common structure that can be used as the result 32/// of a query that can contain a single result. Examples of such 33/// queries include 34/// @li Looking up a load address. 35//---------------------------------------------------------------------- 36class SymbolContext 37{ 38public: 39 40 //------------------------------------------------------------------ 41 /// Default constructor. 42 /// 43 /// Initialize all pointer members to NULL and all struct members 44 /// to their default state. 45 //------------------------------------------------------------------ 46 SymbolContext (); 47 48 //------------------------------------------------------------------ 49 /// Construct with an object that knows how to reconstruct its 50 /// symbol context. 51 /// 52 /// @param[in] sc_scope 53 /// A symbol context scope object that knows how to reconstruct 54 /// it's context. 55 //------------------------------------------------------------------ 56 explicit 57 SymbolContext (SymbolContextScope *sc_scope); 58 59 //------------------------------------------------------------------ 60 /// Construct with module, and optional compile unit, function, 61 /// block, line table, line entry and symbol. 62 /// 63 /// Initialize all pointer to the specified values. 64 /// 65 /// @param[in] module 66 /// A Module pointer to the module for this context. 67 /// 68 /// @param[in] comp_unit 69 /// A CompileUnit pointer to the compile unit for this context. 70 /// 71 /// @param[in] function 72 /// A Function pointer to the function for this context. 73 /// 74 /// @param[in] block 75 /// A Block pointer to the deepest block for this context. 76 /// 77 /// @param[in] line_entry 78 /// A LineEntry pointer to the line entry for this context. 79 /// 80 /// @param[in] symbol 81 /// A Symbol pointer to the symbol for this context. 82 //------------------------------------------------------------------ 83 explicit 84 SymbolContext (const lldb::TargetSP &target_sp, 85 const lldb::ModuleSP &module_sp, 86 CompileUnit *comp_unit = NULL, 87 Function *function = NULL, 88 Block *block = NULL, 89 LineEntry *line_entry = NULL, 90 Symbol *symbol = NULL); 91 92 // This version sets the target to a NULL TargetSP if you don't know it. 93 explicit 94 SymbolContext (const lldb::ModuleSP &module_sp, 95 CompileUnit *comp_unit = NULL, 96 Function *function = NULL, 97 Block *block = NULL, 98 LineEntry *line_entry = NULL, 99 Symbol *symbol = NULL); 100 101 ~SymbolContext (); 102 //------------------------------------------------------------------ 103 /// Copy constructor 104 /// 105 /// Makes a copy of the another SymbolContext object \a rhs. 106 /// 107 /// @param[in] rhs 108 /// A const SymbolContext object reference to copy. 109 //------------------------------------------------------------------ 110 SymbolContext (const SymbolContext& rhs); 111 112 //------------------------------------------------------------------ 113 /// Assignment operator. 114 /// 115 /// Copies the address value from another SymbolContext object \a 116 /// rhs into \a this object. 117 /// 118 /// @param[in] rhs 119 /// A const SymbolContext object reference to copy. 120 /// 121 /// @return 122 /// A const SymbolContext object reference to \a this. 123 //------------------------------------------------------------------ 124 const SymbolContext& 125 operator= (const SymbolContext& rhs); 126 127 //------------------------------------------------------------------ 128 /// Clear the object's state. 129 /// 130 /// Resets all pointer members to NULL, and clears any class objects 131 /// to their default state. 132 //------------------------------------------------------------------ 133 void 134 Clear (); 135 136 //------------------------------------------------------------------ 137 /// Dump a description of this object to a Stream. 138 /// 139 /// Dump a description of the contents of this object to the 140 /// supplied stream \a s. 141 /// 142 /// @param[in] s 143 /// The stream to which to dump the object descripton. 144 //------------------------------------------------------------------ 145 void 146 Dump (Stream *s, Target *target) const; 147 148 //------------------------------------------------------------------ 149 /// Dump the stop context in this object to a Stream. 150 /// 151 /// Dump the best description of this object to the stream. The 152 /// information displayed depends on the amount and quality of the 153 /// information in this context. If a module, function, file and 154 /// line number are available, they will be dumped. If only a 155 /// module and function or symbol name with offset is available, 156 /// that will be ouput. Else just the address at which the target 157 /// was stopped will be displayed. 158 /// 159 /// @param[in] s 160 /// The stream to which to dump the object descripton. 161 /// 162 /// @param[in] so_addr 163 /// The resolved section offset address. 164 //------------------------------------------------------------------ 165 bool 166 DumpStopContext (Stream *s, 167 ExecutionContextScope *exe_scope, 168 const Address &so_addr, 169 bool show_fullpaths, 170 bool show_module, 171 bool show_inlined_frames) const; 172 173 //------------------------------------------------------------------ 174 /// Get the address range contained within a symbol context. 175 /// 176 /// Address range priority is as follows: 177 /// - line_entry address range if line_entry is valid and eSymbolContextLineEntry is set in \a scope 178 /// - block address range if block is not NULL and eSymbolContextBlock is set in \a scope 179 /// - function address range if function is not NULL and eSymbolContextFunction is set in \a scope 180 /// - symbol address range if symbol is not NULL and eSymbolContextSymbol is set in \a scope 181 /// 182 /// @param[in] scope 183 /// A mask of symbol context bits telling this function which 184 /// address ranges it can use when trying to extract one from 185 /// the valid (non-NULL) symbol context classes. 186 /// 187 /// @param[in] range_idx 188 /// The address range index to grab. Since many functions and 189 /// blocks are not always contiguous, they may have more than 190 /// one address range. 191 /// 192 /// @param[in] use_inline_block_range 193 /// If \a scope has the eSymbolContextBlock bit set, and there 194 /// is a valid block in the symbol context, return the block 195 /// address range for the containing inline function block, not 196 /// the deepest most block. This allows us to extract information 197 /// for the address range of the inlined function block, not 198 /// the deepest lexical block. 199 /// 200 /// @param[out] range 201 /// An address range object that will be filled in if \b true 202 /// is returned. 203 /// 204 /// @return 205 /// \b True if this symbol context contains items that describe 206 /// an address range, \b false otherwise. 207 //------------------------------------------------------------------ 208 bool 209 GetAddressRange (uint32_t scope, 210 uint32_t range_idx, 211 bool use_inline_block_range, 212 AddressRange &range) const; 213 214 215 void 216 GetDescription(Stream *s, 217 lldb::DescriptionLevel level, 218 Target *target) const; 219 220 uint32_t 221 GetResolvedMask () const; 222 223 224 //------------------------------------------------------------------ 225 /// Find a function matching the given name, working out from this 226 /// symbol context. 227 /// 228 /// @return 229 /// The number of symbol contexts found. 230 //------------------------------------------------------------------ 231 size_t 232 FindFunctionsByName (const ConstString &name, 233 bool include_symbols, 234 bool append, 235 SymbolContextList &sc_list) const; 236 237 238 ClangNamespaceDecl 239 FindNamespace (const ConstString &name) const; 240 241 //------------------------------------------------------------------ 242 /// Find a variable matching the given name, working out from this 243 /// symbol context. 244 /// 245 /// @return 246 /// A shared pointer to the variable found. 247 //------------------------------------------------------------------ 248 //lldb::VariableSP 249 //FindVariableByName (const char *name) const; 250 251 //------------------------------------------------------------------ 252 /// Find a type matching the given name, working out from this 253 /// symbol context. 254 /// 255 /// @return 256 /// A shared pointer to the variable found. 257 //------------------------------------------------------------------ 258 lldb::TypeSP 259 FindTypeByName (const ConstString &name) const; 260 261// static SymbolContext 262// CreateSymbolContextFromDescription (lldb::TargetSP &target, 263// const char *module, 264// const char *comp_unit, 265// const char *function, 266// const char *block_spec 267// const char *line_number, 268// const char *symbol); 269 270 //------------------------------------------------------------------ 271 /// Find a name of the innermost function for the symbol context. 272 /// 273 /// For instance, if the symbol context contains an inlined block, 274 /// it will return the inlined function name. 275 /// 276 /// @param[in] prefer_mangled 277 /// if \btrue, then the mangled name will be returned if there 278 /// is one. Otherwise the unmangled name will be returned if it 279 /// is available. 280 /// 281 /// @return 282 /// The name of the function represented by this symbol context. 283 //------------------------------------------------------------------ 284 ConstString 285 GetFunctionName (Mangled::NamePreference preference = Mangled::ePreferDemangled); 286 287 //------------------------------------------------------------------ 288 /// Find the block containing the inlined block that contains this block. 289 /// 290 /// For instance, if the symbol context contains an inlined block, 291 /// it will return the inlined function name. 292 /// 293 /// @param[in] curr_frame_pc 294 /// The address within the block of this object. 295 /// 296 /// @param[out] next_frame_sc 297 /// A new symbol context that does what the title says it does. 298 /// 299 /// @param[out] next_frame_addr 300 /// This is what you should report as the PC in \a next_frame_sc. 301 /// 302 /// @return 303 /// \b true if this SymbolContext specifies a block contained in an 304 /// inlined block. If this returns \b true, \a next_frame_sc and 305 /// \a next_frame_addr will be filled in correctly. 306 //------------------------------------------------------------------ 307 bool 308 GetParentOfInlinedScope (const Address &curr_frame_pc, 309 SymbolContext &next_frame_sc, 310 Address &inlined_frame_addr) const; 311 312 //------------------------------------------------------------------ 313 // Member variables 314 //------------------------------------------------------------------ 315 lldb::TargetSP target_sp; ///< The Target for a given query 316 lldb::ModuleSP module_sp; ///< The Module for a given query 317 CompileUnit * comp_unit; ///< The CompileUnit for a given query 318 Function * function; ///< The Function for a given query 319 Block * block; ///< The Block for a given query 320 LineEntry line_entry; ///< The LineEntry for a given query 321 Symbol * symbol; ///< The Symbol for a given query 322}; 323 324 325class SymbolContextSpecifier 326{ 327public: 328 typedef enum SpecificationType 329 { 330 eNothingSpecified = 0, 331 eModuleSpecified = 1 << 0, 332 eFileSpecified = 1 << 1, 333 eLineStartSpecified = 1 << 2, 334 eLineEndSpecified = 1 << 3, 335 eFunctionSpecified = 1 << 4, 336 eClassOrNamespaceSpecified = 1 << 5, 337 eAddressRangeSpecified = 1 << 6 338 } SpecificationType; 339 340 // This one produces a specifier that matches everything... 341 SymbolContextSpecifier (const lldb::TargetSP& target_sp); 342 343 ~SymbolContextSpecifier(); 344 345 bool 346 AddSpecification (const char *spec_string, SpecificationType type); 347 348 bool 349 AddLineSpecification (uint32_t line_no, SpecificationType type); 350 351 void 352 Clear(); 353 354 bool 355 SymbolContextMatches(SymbolContext &sc); 356 357 bool 358 AddressMatches(lldb::addr_t addr); 359 360 void 361 GetDescription (Stream *s, lldb::DescriptionLevel level) const; 362 363private: 364 lldb::TargetSP m_target_sp; 365 std::string m_module_spec; 366 lldb::ModuleSP m_module_sp; 367 std::auto_ptr<FileSpec> m_file_spec_ap; 368 size_t m_start_line; 369 size_t m_end_line; 370 std::string m_function_spec; 371 std::string m_class_name; 372 std::auto_ptr<AddressRange> m_address_range_ap; 373 uint32_t m_type; // Or'ed bits from SpecificationType 374 375}; 376 377//---------------------------------------------------------------------- 378/// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h" 379/// @brief Defines a list of symbol context objects. 380/// 381/// This class provides a common structure that can be used to contain 382/// the result of a query that can contain a multiple results. Examples 383/// of such queries include: 384/// @li Looking up a function by name. 385/// @li Finding all addressses for a specified file and line number. 386//---------------------------------------------------------------------- 387class SymbolContextList 388{ 389public: 390 //------------------------------------------------------------------ 391 /// Default constructor. 392 /// 393 /// Initialize with an empty list. 394 //------------------------------------------------------------------ 395 SymbolContextList (); 396 397 //------------------------------------------------------------------ 398 /// Destructor. 399 //------------------------------------------------------------------ 400 ~SymbolContextList (); 401 402 //------------------------------------------------------------------ 403 /// Append a new symbol context to the list. 404 /// 405 /// @param[in] sc 406 /// A symbol context to append to the list. 407 //------------------------------------------------------------------ 408 void 409 Append (const SymbolContext& sc); 410 411 bool 412 AppendIfUnique (const SymbolContext& sc, bool merge_symbol_into_function); 413 414 //------------------------------------------------------------------ 415 /// Clear the object's state. 416 /// 417 /// Clears the symbol context list. 418 //------------------------------------------------------------------ 419 void 420 Clear(); 421 422 //------------------------------------------------------------------ 423 /// Dump a description of this object to a Stream. 424 /// 425 /// Dump a description of the contents of each symbol context in 426 /// the list to the supplied stream \a s. 427 /// 428 /// @param[in] s 429 /// The stream to which to dump the object descripton. 430 //------------------------------------------------------------------ 431 void 432 Dump(Stream *s, Target *target) const; 433 434 //------------------------------------------------------------------ 435 /// Get accessor for a symbol context at index \a idx. 436 /// 437 /// Dump a description of the contents of each symbol context in 438 /// the list to the supplied stream \a s. 439 /// 440 /// @param[in] idx 441 /// The zero based index into the symbol context list. 442 /// 443 /// @param[out] sc 444 /// A reference to the symbol context to fill in. 445 /// 446 /// @return 447 /// Returns \b true if \a idx was a valid index into this 448 /// symbol context list and \a sc was filled in, \b false 449 /// otherwise. 450 //------------------------------------------------------------------ 451 bool 452 GetContextAtIndex(uint32_t idx, SymbolContext& sc) const; 453 454 bool 455 RemoveContextAtIndex (uint32_t idx); 456 //------------------------------------------------------------------ 457 /// Get accessor for a symbol context list size. 458 /// 459 /// @return 460 /// Returns the number of symbol context objects in the list. 461 //------------------------------------------------------------------ 462 uint32_t 463 GetSize() const; 464 465 uint32_t 466 NumLineEntriesWithLine (uint32_t line) const; 467 468protected: 469 typedef std::vector<SymbolContext> collection; ///< The collection type for the list. 470 471 //------------------------------------------------------------------ 472 // Member variables. 473 //------------------------------------------------------------------ 474 collection m_symbol_contexts; ///< The list of symbol contexts. 475}; 476 477bool operator== (const SymbolContext& lhs, const SymbolContext& rhs); 478bool operator!= (const SymbolContext& lhs, const SymbolContext& rhs); 479 480bool operator== (const SymbolContextList& lhs, const SymbolContextList& rhs); 481bool operator!= (const SymbolContextList& lhs, const SymbolContextList& rhs); 482 483} // namespace lldb_private 484 485#endif // liblldb_SymbolContext_h_ 486