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/LineEntry.h" 20 #include "lldb/Utility/Iterable.h" 21 22 namespace lldb_private { 23 24 class 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 //---------------------------------------------------------------------- 36 class SymbolContext 37 { 38 public: 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 (bool clear_target); 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 description. 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 output. 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 description. 161 /// 162 /// @param[in] so_addr 163 /// The resolved section offset address. 164 /// 165 /// @param[in] show_fullpaths 166 /// When printing file paths (with the Module), whether the 167 /// base name of the Module should be printed or the full path. 168 /// 169 /// @param[in] show_module 170 /// Whether the module name should be printed followed by a 171 /// grave accent "`" character. 172 /// 173 /// @param[in] show_inlined_frames 174 /// If a given pc is in inlined function(s), whether the inlined 175 /// functions should be printed on separate lines in addition to 176 /// the concrete function containing the pc. 177 /// 178 /// @param[in] show_function_arguments 179 /// If false, this method will try to elide the function argument 180 /// types when printing the function name. This may be ambiguous 181 /// for languages that have function overloading - but it may 182 /// make the "function name" too long to include all the argument 183 /// types. 184 /// 185 /// @param[in] show_function_name 186 /// Normally this should be true - the function/symbol name should 187 /// be printed. In disassembly formatting, where we want a format 188 /// like "<*+36>", this should be false and "*" will be printed 189 /// instead. 190 //------------------------------------------------------------------ 191 bool 192 DumpStopContext (Stream *s, 193 ExecutionContextScope *exe_scope, 194 const Address &so_addr, 195 bool show_fullpaths, 196 bool show_module, 197 bool show_inlined_frames, 198 bool show_function_arguments, 199 bool show_function_name) const; 200 201 //------------------------------------------------------------------ 202 /// Get the address range contained within a symbol context. 203 /// 204 /// Address range priority is as follows: 205 /// - line_entry address range if line_entry is valid and eSymbolContextLineEntry is set in \a scope 206 /// - block address range if block is not NULL and eSymbolContextBlock is set in \a scope 207 /// - function address range if function is not NULL and eSymbolContextFunction is set in \a scope 208 /// - symbol address range if symbol is not NULL and eSymbolContextSymbol is set in \a scope 209 /// 210 /// @param[in] scope 211 /// A mask of symbol context bits telling this function which 212 /// address ranges it can use when trying to extract one from 213 /// the valid (non-NULL) symbol context classes. 214 /// 215 /// @param[in] range_idx 216 /// The address range index to grab. Since many functions and 217 /// blocks are not always contiguous, they may have more than 218 /// one address range. 219 /// 220 /// @param[in] use_inline_block_range 221 /// If \a scope has the eSymbolContextBlock bit set, and there 222 /// is a valid block in the symbol context, return the block 223 /// address range for the containing inline function block, not 224 /// the deepest most block. This allows us to extract information 225 /// for the address range of the inlined function block, not 226 /// the deepest lexical block. 227 /// 228 /// @param[out] range 229 /// An address range object that will be filled in if \b true 230 /// is returned. 231 /// 232 /// @return 233 /// \b True if this symbol context contains items that describe 234 /// an address range, \b false otherwise. 235 //------------------------------------------------------------------ 236 bool 237 GetAddressRange (uint32_t scope, 238 uint32_t range_idx, 239 bool use_inline_block_range, 240 AddressRange &range) const; 241 242 243 void 244 GetDescription(Stream *s, 245 lldb::DescriptionLevel level, 246 Target *target) const; 247 248 uint32_t 249 GetResolvedMask () const; 250 251 252 //------------------------------------------------------------------ 253 /// Find a block that defines the function represented by this 254 /// symbol context. 255 /// 256 /// If this symbol context points to a block that is an inlined 257 /// function, or is contained within an inlined function, the block 258 /// that defines the inlined function is returned. 259 /// 260 /// If this symbol context has no block in it, or the block is not 261 /// itself an inlined function block or contained within one, we 262 /// return the top level function block. 263 /// 264 /// This is a handy function to call when you want to get the block 265 /// whose variable list will include the arguments for the function 266 /// that is represented by this symbol context (whether the function 267 /// is an inline function or not). 268 /// 269 /// @return 270 /// The block object pointer that defines the function that is 271 /// represented by this symbol context object, NULL otherwise. 272 //------------------------------------------------------------------ 273 Block * 274 GetFunctionBlock (); 275 276 277 //------------------------------------------------------------------ 278 /// If this symbol context represents a function that is a method, 279 /// return true and provide information about the method. 280 /// 281 /// @param[out] language 282 /// If \b true is returned, the language for the method. 283 /// 284 /// @param[out] is_instance_method 285 /// If \b true is returned, \b true if this is a instance method, 286 /// \b false if this is a static/class function. 287 /// 288 /// @param[out] language_object_name 289 /// If \b true is returned, the name of the artificial variable 290 /// for the language ("this" for C++, "self" for ObjC). 291 /// 292 /// @return 293 /// \b True if this symbol context represents a function that 294 /// is a method of a class, \b false otherwise. 295 //------------------------------------------------------------------ 296 bool 297 GetFunctionMethodInfo (lldb::LanguageType &language, 298 bool &is_instance_method, 299 ConstString &language_object_name); 300 301 //------------------------------------------------------------------ 302 /// Find a name of the innermost function for the symbol context. 303 /// 304 /// For instance, if the symbol context contains an inlined block, 305 /// it will return the inlined function name. 306 /// 307 /// @param[in] prefer_mangled 308 /// if \btrue, then the mangled name will be returned if there 309 /// is one. Otherwise the unmangled name will be returned if it 310 /// is available. 311 /// 312 /// @return 313 /// The name of the function represented by this symbol context. 314 //------------------------------------------------------------------ 315 ConstString 316 GetFunctionName (Mangled::NamePreference preference = Mangled::ePreferDemangled) const; 317 318 319 //------------------------------------------------------------------ 320 /// Get the line entry that corresponds to the function. 321 /// 322 /// If the symbol context contains an inlined block, the line entry 323 /// for the start address of the inlined function will be returned, 324 /// otherwise the line entry for the start address of the function 325 /// will be returned. This can be used after doing a 326 /// Module::FindFunctions(...) or ModuleList::FindFunctions(...) 327 /// call in order to get the correct line table information for 328 /// the symbol context. 329 /// it will return the inlined function name. 330 /// 331 /// @param[in] prefer_mangled 332 /// if \btrue, then the mangled name will be returned if there 333 /// is one. Otherwise the unmangled name will be returned if it 334 /// is available. 335 /// 336 /// @return 337 /// The name of the function represented by this symbol context. 338 //------------------------------------------------------------------ 339 LineEntry 340 GetFunctionStartLineEntry () const; 341 342 //------------------------------------------------------------------ 343 /// Find the block containing the inlined block that contains this block. 344 /// 345 /// For instance, if the symbol context contains an inlined block, 346 /// it will return the inlined function name. 347 /// 348 /// @param[in] curr_frame_pc 349 /// The address within the block of this object. 350 /// 351 /// @param[out] next_frame_sc 352 /// A new symbol context that does what the title says it does. 353 /// 354 /// @param[out] next_frame_addr 355 /// This is what you should report as the PC in \a next_frame_sc. 356 /// 357 /// @return 358 /// \b true if this SymbolContext specifies a block contained in an 359 /// inlined block. If this returns \b true, \a next_frame_sc and 360 /// \a next_frame_addr will be filled in correctly. 361 //------------------------------------------------------------------ 362 bool 363 GetParentOfInlinedScope (const Address &curr_frame_pc, 364 SymbolContext &next_frame_sc, 365 Address &inlined_frame_addr) const; 366 367 //------------------------------------------------------------------ 368 // Member variables 369 //------------------------------------------------------------------ 370 lldb::TargetSP target_sp; ///< The Target for a given query 371 lldb::ModuleSP module_sp; ///< The Module for a given query 372 CompileUnit * comp_unit; ///< The CompileUnit for a given query 373 Function * function; ///< The Function for a given query 374 Block * block; ///< The Block for a given query 375 LineEntry line_entry; ///< The LineEntry for a given query 376 Symbol * symbol; ///< The Symbol for a given query 377 Variable * variable; ///< The global variable matching the given query 378 }; 379 380 381 class SymbolContextSpecifier 382 { 383 public: 384 typedef enum SpecificationType 385 { 386 eNothingSpecified = 0, 387 eModuleSpecified = 1 << 0, 388 eFileSpecified = 1 << 1, 389 eLineStartSpecified = 1 << 2, 390 eLineEndSpecified = 1 << 3, 391 eFunctionSpecified = 1 << 4, 392 eClassOrNamespaceSpecified = 1 << 5, 393 eAddressRangeSpecified = 1 << 6 394 } SpecificationType; 395 396 // This one produces a specifier that matches everything... 397 SymbolContextSpecifier (const lldb::TargetSP& target_sp); 398 399 ~SymbolContextSpecifier(); 400 401 bool 402 AddSpecification (const char *spec_string, SpecificationType type); 403 404 bool 405 AddLineSpecification (uint32_t line_no, SpecificationType type); 406 407 void 408 Clear(); 409 410 bool 411 SymbolContextMatches(SymbolContext &sc); 412 413 bool 414 AddressMatches(lldb::addr_t addr); 415 416 void 417 GetDescription (Stream *s, lldb::DescriptionLevel level) const; 418 419 private: 420 lldb::TargetSP m_target_sp; 421 std::string m_module_spec; 422 lldb::ModuleSP m_module_sp; 423 std::unique_ptr<FileSpec> m_file_spec_ap; 424 size_t m_start_line; 425 size_t m_end_line; 426 std::string m_function_spec; 427 std::string m_class_name; 428 std::unique_ptr<AddressRange> m_address_range_ap; 429 uint32_t m_type; // Or'ed bits from SpecificationType 430 431 }; 432 433 //---------------------------------------------------------------------- 434 /// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h" 435 /// @brief Defines a list of symbol context objects. 436 /// 437 /// This class provides a common structure that can be used to contain 438 /// the result of a query that can contain a multiple results. Examples 439 /// of such queries include: 440 /// @li Looking up a function by name. 441 /// @li Finding all addresses for a specified file and line number. 442 //---------------------------------------------------------------------- 443 class SymbolContextList 444 { 445 public: 446 //------------------------------------------------------------------ 447 /// Default constructor. 448 /// 449 /// Initialize with an empty list. 450 //------------------------------------------------------------------ 451 SymbolContextList (); 452 453 //------------------------------------------------------------------ 454 /// Destructor. 455 //------------------------------------------------------------------ 456 ~SymbolContextList (); 457 458 //------------------------------------------------------------------ 459 /// Append a new symbol context to the list. 460 /// 461 /// @param[in] sc 462 /// A symbol context to append to the list. 463 //------------------------------------------------------------------ 464 void 465 Append (const SymbolContext& sc); 466 467 void 468 Append (const SymbolContextList& sc_list); 469 470 bool 471 AppendIfUnique (const SymbolContext& sc, 472 bool merge_symbol_into_function); 473 474 bool 475 MergeSymbolContextIntoFunctionContext (const SymbolContext& symbol_sc, 476 uint32_t start_idx = 0, 477 uint32_t stop_idx = UINT32_MAX); 478 479 uint32_t 480 AppendIfUnique (const SymbolContextList& sc_list, 481 bool merge_symbol_into_function); 482 //------------------------------------------------------------------ 483 /// Clear the object's state. 484 /// 485 /// Clears the symbol context list. 486 //------------------------------------------------------------------ 487 void 488 Clear(); 489 490 //------------------------------------------------------------------ 491 /// Dump a description of this object to a Stream. 492 /// 493 /// Dump a description of the contents of each symbol context in 494 /// the list to the supplied stream \a s. 495 /// 496 /// @param[in] s 497 /// The stream to which to dump the object description. 498 //------------------------------------------------------------------ 499 void 500 Dump(Stream *s, Target *target) const; 501 502 //------------------------------------------------------------------ 503 /// Get accessor for a symbol context at index \a idx. 504 /// 505 /// Dump a description of the contents of each symbol context in 506 /// the list to the supplied stream \a s. 507 /// 508 /// @param[in] idx 509 /// The zero based index into the symbol context list. 510 /// 511 /// @param[out] sc 512 /// A reference to the symbol context to fill in. 513 /// 514 /// @return 515 /// Returns \b true if \a idx was a valid index into this 516 /// symbol context list and \a sc was filled in, \b false 517 /// otherwise. 518 //------------------------------------------------------------------ 519 bool 520 GetContextAtIndex(size_t idx, SymbolContext& sc) const; 521 522 //------------------------------------------------------------------ 523 /// Direct reference accessor for a symbol context at index \a idx. 524 /// 525 /// The index \a idx must be a valid index, no error checking will 526 /// be done to ensure that it is valid. 527 /// 528 /// @param[in] idx 529 /// The zero based index into the symbol context list. 530 /// 531 /// @return 532 /// A const reference to the symbol context to fill in. 533 //------------------------------------------------------------------ 534 SymbolContext& 535 operator [] (size_t idx) 536 { 537 return m_symbol_contexts[idx]; 538 } 539 540 const SymbolContext& 541 operator [] (size_t idx) const 542 { 543 return m_symbol_contexts[idx]; 544 } 545 546 //------------------------------------------------------------------ 547 /// Get accessor for the last symbol context in the list. 548 /// 549 /// @param[out] sc 550 /// A reference to the symbol context to fill in. 551 /// 552 /// @return 553 /// Returns \b true if \a sc was filled in, \b false if the 554 /// list is empty. 555 //------------------------------------------------------------------ 556 bool 557 GetLastContext(SymbolContext& sc) const; 558 559 bool 560 RemoveContextAtIndex (size_t idx); 561 //------------------------------------------------------------------ 562 /// Get accessor for a symbol context list size. 563 /// 564 /// @return 565 /// Returns the number of symbol context objects in the list. 566 //------------------------------------------------------------------ 567 uint32_t 568 GetSize() const; 569 570 uint32_t 571 NumLineEntriesWithLine (uint32_t line) const; 572 573 void 574 GetDescription(Stream *s, 575 lldb::DescriptionLevel level, 576 Target *target) const; 577 578 protected: 579 typedef std::vector<SymbolContext> collection; ///< The collection type for the list. 580 581 //------------------------------------------------------------------ 582 // Member variables. 583 //------------------------------------------------------------------ 584 collection m_symbol_contexts; ///< The list of symbol contexts. 585 586 public: 587 typedef AdaptedIterable<collection, SymbolContext, vector_adapter> SymbolContextIterable; 588 SymbolContextIterable SymbolContexts()589 SymbolContexts() 590 { 591 return SymbolContextIterable(m_symbol_contexts); 592 } 593 }; 594 595 bool operator== (const SymbolContext& lhs, const SymbolContext& rhs); 596 bool operator!= (const SymbolContext& lhs, const SymbolContext& rhs); 597 598 bool operator== (const SymbolContextList& lhs, const SymbolContextList& rhs); 599 bool operator!= (const SymbolContextList& lhs, const SymbolContextList& rhs); 600 601 } // namespace lldb_private 602 603 #endif // liblldb_SymbolContext_h_ 604