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 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 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 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 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 block that defines the function represented by this 226 /// symbol context. 227 /// 228 /// If this symbol context points to a block that is an inlined 229 /// function, or is contained within an inlined function, the block 230 /// that defines the inlined function is returned. 231 /// 232 /// If this symbol context has no block in it, or the block is not 233 /// itself an inlined function block or contained within one, we 234 /// return the top level function block. 235 /// 236 /// This is a handy function to call when you want to get the block 237 /// whose variable list will include the arguments for the function 238 /// that is represented by this symbol context (whether the function 239 /// is an inline function or not). 240 /// 241 /// @return 242 /// The block object pointer that defines the function that is 243 /// represented by this symbol context object, NULL otherwise. 244 //------------------------------------------------------------------ 245 Block * 246 GetFunctionBlock (); 247 248 249 //------------------------------------------------------------------ 250 /// If this symbol context represents a function that is a method, 251 /// return true and provide information about the method. 252 /// 253 /// @param[out] language 254 /// If \b true is returned, the language for the method. 255 /// 256 /// @param[out] is_instance_method 257 /// If \b true is returned, \b true if this is a instance method, 258 /// \b false if this is a static/class function. 259 /// 260 /// @param[out] language_object_name 261 /// If \b true is returned, the name of the artificial variable 262 /// for the language ("this" for C++, "self" for ObjC). 263 /// 264 /// @return 265 /// \b True if this symbol context represents a function that 266 /// is a method of a class, \b false otherwise. 267 //------------------------------------------------------------------ 268 bool 269 GetFunctionMethodInfo (lldb::LanguageType &language, 270 bool &is_instance_method, 271 ConstString &language_object_name); 272 273 //------------------------------------------------------------------ 274 /// Find a name of the innermost function for the symbol context. 275 /// 276 /// For instance, if the symbol context contains an inlined block, 277 /// it will return the inlined function name. 278 /// 279 /// @param[in] prefer_mangled 280 /// if \btrue, then the mangled name will be returned if there 281 /// is one. Otherwise the unmangled name will be returned if it 282 /// is available. 283 /// 284 /// @return 285 /// The name of the function represented by this symbol context. 286 //------------------------------------------------------------------ 287 ConstString 288 GetFunctionName (Mangled::NamePreference preference = Mangled::ePreferDemangled) const; 289 290 291 //------------------------------------------------------------------ 292 /// Get the line entry that corresponds to the function. 293 /// 294 /// If the symbol context contains an inlined block, the line entry 295 /// for the start address of the inlined function will be returned, 296 /// otherwise the line entry for the start address of the function 297 /// will be returned. This can be used after doing a 298 /// Module::FindFunctions(...) or ModuleList::FindFunctions(...) 299 /// call in order to get the correct line table information for 300 /// the symbol context. 301 /// it will return the inlined function name. 302 /// 303 /// @param[in] prefer_mangled 304 /// if \btrue, then the mangled name will be returned if there 305 /// is one. Otherwise the unmangled name will be returned if it 306 /// is available. 307 /// 308 /// @return 309 /// The name of the function represented by this symbol context. 310 //------------------------------------------------------------------ 311 LineEntry 312 GetFunctionStartLineEntry () const; 313 314 //------------------------------------------------------------------ 315 /// Find the block containing the inlined block that contains this block. 316 /// 317 /// For instance, if the symbol context contains an inlined block, 318 /// it will return the inlined function name. 319 /// 320 /// @param[in] curr_frame_pc 321 /// The address within the block of this object. 322 /// 323 /// @param[out] next_frame_sc 324 /// A new symbol context that does what the title says it does. 325 /// 326 /// @param[out] next_frame_addr 327 /// This is what you should report as the PC in \a next_frame_sc. 328 /// 329 /// @return 330 /// \b true if this SymbolContext specifies a block contained in an 331 /// inlined block. If this returns \b true, \a next_frame_sc and 332 /// \a next_frame_addr will be filled in correctly. 333 //------------------------------------------------------------------ 334 bool 335 GetParentOfInlinedScope (const Address &curr_frame_pc, 336 SymbolContext &next_frame_sc, 337 Address &inlined_frame_addr) const; 338 339 //------------------------------------------------------------------ 340 // Member variables 341 //------------------------------------------------------------------ 342 lldb::TargetSP target_sp; ///< The Target for a given query 343 lldb::ModuleSP module_sp; ///< The Module for a given query 344 CompileUnit * comp_unit; ///< The CompileUnit for a given query 345 Function * function; ///< The Function for a given query 346 Block * block; ///< The Block for a given query 347 LineEntry line_entry; ///< The LineEntry for a given query 348 Symbol * symbol; ///< The Symbol for a given query 349 }; 350 351 352 class SymbolContextSpecifier 353 { 354 public: 355 typedef enum SpecificationType 356 { 357 eNothingSpecified = 0, 358 eModuleSpecified = 1 << 0, 359 eFileSpecified = 1 << 1, 360 eLineStartSpecified = 1 << 2, 361 eLineEndSpecified = 1 << 3, 362 eFunctionSpecified = 1 << 4, 363 eClassOrNamespaceSpecified = 1 << 5, 364 eAddressRangeSpecified = 1 << 6 365 } SpecificationType; 366 367 // This one produces a specifier that matches everything... 368 SymbolContextSpecifier (const lldb::TargetSP& target_sp); 369 370 ~SymbolContextSpecifier(); 371 372 bool 373 AddSpecification (const char *spec_string, SpecificationType type); 374 375 bool 376 AddLineSpecification (uint32_t line_no, SpecificationType type); 377 378 void 379 Clear(); 380 381 bool 382 SymbolContextMatches(SymbolContext &sc); 383 384 bool 385 AddressMatches(lldb::addr_t addr); 386 387 void 388 GetDescription (Stream *s, lldb::DescriptionLevel level) const; 389 390 private: 391 lldb::TargetSP m_target_sp; 392 std::string m_module_spec; 393 lldb::ModuleSP m_module_sp; 394 std::unique_ptr<FileSpec> m_file_spec_ap; 395 size_t m_start_line; 396 size_t m_end_line; 397 std::string m_function_spec; 398 std::string m_class_name; 399 std::unique_ptr<AddressRange> m_address_range_ap; 400 uint32_t m_type; // Or'ed bits from SpecificationType 401 402 }; 403 404 //---------------------------------------------------------------------- 405 /// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h" 406 /// @brief Defines a list of symbol context objects. 407 /// 408 /// This class provides a common structure that can be used to contain 409 /// the result of a query that can contain a multiple results. Examples 410 /// of such queries include: 411 /// @li Looking up a function by name. 412 /// @li Finding all addressses for a specified file and line number. 413 //---------------------------------------------------------------------- 414 class SymbolContextList 415 { 416 public: 417 //------------------------------------------------------------------ 418 /// Default constructor. 419 /// 420 /// Initialize with an empty list. 421 //------------------------------------------------------------------ 422 SymbolContextList (); 423 424 //------------------------------------------------------------------ 425 /// Destructor. 426 //------------------------------------------------------------------ 427 ~SymbolContextList (); 428 429 //------------------------------------------------------------------ 430 /// Append a new symbol context to the list. 431 /// 432 /// @param[in] sc 433 /// A symbol context to append to the list. 434 //------------------------------------------------------------------ 435 void 436 Append (const SymbolContext& sc); 437 438 void 439 Append (const SymbolContextList& sc_list); 440 441 bool 442 AppendIfUnique (const SymbolContext& sc, 443 bool merge_symbol_into_function); 444 445 bool 446 MergeSymbolContextIntoFunctionContext (const SymbolContext& symbol_sc, 447 uint32_t start_idx = 0, 448 uint32_t stop_idx = UINT32_MAX); 449 450 uint32_t 451 AppendIfUnique (const SymbolContextList& sc_list, 452 bool merge_symbol_into_function); 453 //------------------------------------------------------------------ 454 /// Clear the object's state. 455 /// 456 /// Clears the symbol context list. 457 //------------------------------------------------------------------ 458 void 459 Clear(); 460 461 //------------------------------------------------------------------ 462 /// Dump a description of this object to a Stream. 463 /// 464 /// Dump a description of the contents of each symbol context in 465 /// the list to the supplied stream \a s. 466 /// 467 /// @param[in] s 468 /// The stream to which to dump the object descripton. 469 //------------------------------------------------------------------ 470 void 471 Dump(Stream *s, Target *target) const; 472 473 //------------------------------------------------------------------ 474 /// Get accessor for a symbol context at index \a idx. 475 /// 476 /// Dump a description of the contents of each symbol context in 477 /// the list to the supplied stream \a s. 478 /// 479 /// @param[in] idx 480 /// The zero based index into the symbol context list. 481 /// 482 /// @param[out] sc 483 /// A reference to the symbol context to fill in. 484 /// 485 /// @return 486 /// Returns \b true if \a idx was a valid index into this 487 /// symbol context list and \a sc was filled in, \b false 488 /// otherwise. 489 //------------------------------------------------------------------ 490 bool 491 GetContextAtIndex(size_t idx, SymbolContext& sc) const; 492 493 //------------------------------------------------------------------ 494 /// Direct reference accessor for a symbol context at index \a idx. 495 /// 496 /// The index \a idx must be a valid index, no error checking will 497 /// be done to ensure that it is valid. 498 /// 499 /// @param[in] idx 500 /// The zero based index into the symbol context list. 501 /// 502 /// @return 503 /// A const reference to the symbol context to fill in. 504 //------------------------------------------------------------------ 505 SymbolContext& 506 operator [] (size_t idx) 507 { 508 return m_symbol_contexts[idx]; 509 } 510 511 const SymbolContext& 512 operator [] (size_t idx) const 513 { 514 return m_symbol_contexts[idx]; 515 } 516 517 //------------------------------------------------------------------ 518 /// Get accessor for the last symbol context in the list. 519 /// 520 /// @param[out] sc 521 /// A reference to the symbol context to fill in. 522 /// 523 /// @return 524 /// Returns \b true if \a sc was filled in, \b false if the 525 /// list is empty. 526 //------------------------------------------------------------------ 527 bool 528 GetLastContext(SymbolContext& sc) const; 529 530 bool 531 RemoveContextAtIndex (size_t idx); 532 //------------------------------------------------------------------ 533 /// Get accessor for a symbol context list size. 534 /// 535 /// @return 536 /// Returns the number of symbol context objects in the list. 537 //------------------------------------------------------------------ 538 uint32_t 539 GetSize() const; 540 541 uint32_t 542 NumLineEntriesWithLine (uint32_t line) const; 543 544 void 545 GetDescription(Stream *s, 546 lldb::DescriptionLevel level, 547 Target *target) const; 548 549 protected: 550 typedef std::vector<SymbolContext> collection; ///< The collection type for the list. 551 552 //------------------------------------------------------------------ 553 // Member variables. 554 //------------------------------------------------------------------ 555 collection m_symbol_contexts; ///< The list of symbol contexts. 556 }; 557 558 bool operator== (const SymbolContext& lhs, const SymbolContext& rhs); 559 bool operator!= (const SymbolContext& lhs, const SymbolContext& rhs); 560 561 bool operator== (const SymbolContextList& lhs, const SymbolContextList& rhs); 562 bool operator!= (const SymbolContextList& lhs, const SymbolContextList& rhs); 563 564 } // namespace lldb_private 565 566 #endif // liblldb_SymbolContext_h_ 567