Module.h revision 263367
1//===-- Module.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#ifndef liblldb_Module_h_ 11#define liblldb_Module_h_ 12 13#include "lldb/Core/ArchSpec.h" 14#include "lldb/Core/UUID.h" 15#include "lldb/Host/FileSpec.h" 16#include "lldb/Host/Mutex.h" 17#include "lldb/Host/TimeValue.h" 18#include "lldb/Symbol/ClangASTContext.h" 19#include "lldb/Symbol/SymbolContextScope.h" 20#include "lldb/Target/PathMappingList.h" 21 22namespace lldb_private { 23 24//---------------------------------------------------------------------- 25/// @class Module Module.h "lldb/Core/Module.h" 26/// @brief A class that describes an executable image and its associated 27/// object and symbol files. 28/// 29/// The module is designed to be able to select a single slice of an 30/// executable image as it would appear on disk and during program 31/// execution. 32/// 33/// Modules control when and if information is parsed according to which 34/// accessors are called. For example the object file (ObjectFile) 35/// representation will only be parsed if the object file is requested 36/// using the Module::GetObjectFile() is called. The debug symbols 37/// will only be parsed if the symbol vendor (SymbolVendor) is 38/// requested using the Module::GetSymbolVendor() is called. 39/// 40/// The module will parse more detailed information as more queries are 41/// made. 42//---------------------------------------------------------------------- 43class Module : 44 public std::enable_shared_from_this<Module>, 45 public SymbolContextScope 46{ 47public: 48 // Static functions that can track the lifetime of module objects. 49 // This is handy because we might have Module objects that are in 50 // shared pointers that aren't in the global module list (from 51 // ModuleList). If this is the case we need to know about it. 52 // The modules in the global list maintained by these functions 53 // can be viewed using the "target modules list" command using the 54 // "--global" (-g for short). 55 static size_t 56 GetNumberAllocatedModules (); 57 58 static Module * 59 GetAllocatedModuleAtIndex (size_t idx); 60 61 static Mutex * 62 GetAllocationModuleCollectionMutex(); 63 64 //------------------------------------------------------------------ 65 /// Construct with file specification and architecture. 66 /// 67 /// Clients that wish to share modules with other targets should 68 /// use ModuleList::GetSharedModule(). 69 /// 70 /// @param[in] file_spec 71 /// The file specification for the on disk repesentation of 72 /// this executable image. 73 /// 74 /// @param[in] arch 75 /// The architecture to set as the current architecture in 76 /// this module. 77 /// 78 /// @param[in] object_name 79 /// The name of an object in a module used to extract a module 80 /// within a module (.a files and modules that contain multiple 81 /// architectures). 82 /// 83 /// @param[in] object_offset 84 /// The offset within an existing module used to extract a 85 /// module within a module (.a files and modules that contain 86 /// multiple architectures). 87 //------------------------------------------------------------------ 88 Module (const FileSpec& file_spec, 89 const ArchSpec& arch, 90 const ConstString *object_name = NULL, 91 off_t object_offset = 0, 92 const TimeValue *object_mod_time_ptr = NULL); 93 94 Module (const ModuleSpec &module_spec); 95 //------------------------------------------------------------------ 96 /// Destructor. 97 //------------------------------------------------------------------ 98 virtual 99 ~Module (); 100 101 bool 102 MatchesModuleSpec (const ModuleSpec &module_ref); 103 104 //------------------------------------------------------------------ 105 /// Set the load address for all sections in a module to be the 106 /// file address plus \a slide. 107 /// 108 /// Many times a module will be loaded in a target with a constant 109 /// offset applied to all top level sections. This function can 110 /// set the load address for all top level sections to be the 111 /// section file address + offset. 112 /// 113 /// @param[in] target 114 /// The target in which to apply the section load addresses. 115 /// 116 /// @param[in] offset 117 /// The offset to apply to all file addresses for all top 118 /// level sections in the object file as each section load 119 /// address is being set. 120 /// 121 /// @param[out] changed 122 /// If any section load addresses were changed in \a target, 123 /// then \a changed will be set to \b true. Else \a changed 124 /// will be set to false. This allows this function to be 125 /// called multiple times on the same module for the same 126 /// target. If the module hasn't moved, then \a changed will 127 /// be false and no module updated notification will need to 128 /// be sent out. 129 /// 130 /// @return 131 /// /b True if any sections were successfully loaded in \a target, 132 /// /b false otherwise. 133 //------------------------------------------------------------------ 134 bool 135 SetLoadAddress (Target &target, 136 lldb::addr_t offset, 137 bool &changed); 138 139 //------------------------------------------------------------------ 140 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*) 141 /// 142 /// @see SymbolContextScope 143 //------------------------------------------------------------------ 144 virtual void 145 CalculateSymbolContext (SymbolContext* sc); 146 147 virtual lldb::ModuleSP 148 CalculateSymbolContextModule (); 149 150 void 151 GetDescription (Stream *s, 152 lldb::DescriptionLevel level = lldb::eDescriptionLevelFull); 153 154 //------------------------------------------------------------------ 155 /// Get the module path and object name. 156 /// 157 /// Modules can refer to object files. In this case the specification 158 /// is simple and would return the path to the file: 159 /// 160 /// "/usr/lib/foo.dylib" 161 /// 162 /// Modules can be .o files inside of a BSD archive (.a file). In 163 /// this case, the object specification will look like: 164 /// 165 /// "/usr/lib/foo.a(bar.o)" 166 /// 167 /// There are many places where logging wants to log this fully 168 /// qualified specification, so we centralize this functionality 169 /// here. 170 /// 171 /// @return 172 /// The object path + object name if there is one. 173 //------------------------------------------------------------------ 174 std::string 175 GetSpecificationDescription () const; 176 177 //------------------------------------------------------------------ 178 /// Dump a description of this object to a Stream. 179 /// 180 /// Dump a description of the contents of this object to the 181 /// supplied stream \a s. The dumped content will be only what has 182 /// been loaded or parsed up to this point at which this function 183 /// is called, so this is a good way to see what has been parsed 184 /// in a module. 185 /// 186 /// @param[in] s 187 /// The stream to which to dump the object descripton. 188 //------------------------------------------------------------------ 189 void 190 Dump (Stream *s); 191 192 //------------------------------------------------------------------ 193 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*) 194 /// 195 /// @see SymbolContextScope 196 //------------------------------------------------------------------ 197 virtual void 198 DumpSymbolContext (Stream *s); 199 200 201 //------------------------------------------------------------------ 202 /// Find a symbol in the object file's symbol table. 203 /// 204 /// @param[in] name 205 /// The name of the symbol that we are looking for. 206 /// 207 /// @param[in] symbol_type 208 /// If set to eSymbolTypeAny, find a symbol of any type that 209 /// has a name that matches \a name. If set to any other valid 210 /// SymbolType enumeration value, then search only for 211 /// symbols that match \a symbol_type. 212 /// 213 /// @return 214 /// Returns a valid symbol pointer if a symbol was found, 215 /// NULL otherwise. 216 //------------------------------------------------------------------ 217 const Symbol * 218 FindFirstSymbolWithNameAndType (const ConstString &name, 219 lldb::SymbolType symbol_type = lldb::eSymbolTypeAny); 220 221 size_t 222 FindSymbolsWithNameAndType (const ConstString &name, 223 lldb::SymbolType symbol_type, 224 SymbolContextList &sc_list); 225 226 size_t 227 FindSymbolsMatchingRegExAndType (const RegularExpression ®ex, 228 lldb::SymbolType symbol_type, 229 SymbolContextList &sc_list); 230 231 //------------------------------------------------------------------ 232 /// Find a funciton symbols in the object file's symbol table. 233 /// 234 /// @param[in] name 235 /// The name of the symbol that we are looking for. 236 /// 237 /// @param[in] name_type_mask 238 /// A mask that has one or more bitwise OR'ed values from the 239 /// lldb::FunctionNameType enumeration type that indicate what 240 /// kind of names we are looking for. 241 /// 242 /// @param[out] sc_list 243 /// A list to append any matching symbol contexts to. 244 /// 245 /// @return 246 /// The number of symbol contexts that were added to \a sc_list 247 //------------------------------------------------------------------ 248 size_t 249 FindFunctionSymbols (const ConstString &name, 250 uint32_t name_type_mask, 251 SymbolContextList& sc_list); 252 253 //------------------------------------------------------------------ 254 /// Find compile units by partial or full path. 255 /// 256 /// Finds all compile units that match \a path in all of the modules 257 /// and returns the results in \a sc_list. 258 /// 259 /// @param[in] path 260 /// The name of the function we are looking for. 261 /// 262 /// @param[in] append 263 /// If \b true, then append any compile units that were found 264 /// to \a sc_list. If \b false, then the \a sc_list is cleared 265 /// and the contents of \a sc_list are replaced. 266 /// 267 /// @param[out] sc_list 268 /// A symbol context list that gets filled in with all of the 269 /// matches. 270 /// 271 /// @return 272 /// The number of matches added to \a sc_list. 273 //------------------------------------------------------------------ 274 size_t 275 FindCompileUnits (const FileSpec &path, 276 bool append, 277 SymbolContextList &sc_list); 278 279 280 //------------------------------------------------------------------ 281 /// Find functions by name. 282 /// 283 /// If the function is an inlined function, it will have a block, 284 /// representing the inlined function, and the function will be the 285 /// containing function. If it is not inlined, then the block will 286 /// be NULL. 287 /// 288 /// @param[in] name 289 /// The name of the compile unit we are looking for. 290 /// 291 /// @param[in] namespace_decl 292 /// If valid, a namespace to search in. 293 /// 294 /// @param[in] name_type_mask 295 /// A bit mask of bits that indicate what kind of names should 296 /// be used when doing the lookup. Bits include fully qualified 297 /// names, base names, C++ methods, or ObjC selectors. 298 /// See FunctionNameType for more details. 299 /// 300 /// @param[in] append 301 /// If \b true, any matches will be appended to \a sc_list, else 302 /// matches replace the contents of \a sc_list. 303 /// 304 /// @param[out] sc_list 305 /// A symbol context list that gets filled in with all of the 306 /// matches. 307 /// 308 /// @return 309 /// The number of matches added to \a sc_list. 310 //------------------------------------------------------------------ 311 size_t 312 FindFunctions (const ConstString &name, 313 const ClangNamespaceDecl *namespace_decl, 314 uint32_t name_type_mask, 315 bool symbols_ok, 316 bool inlines_ok, 317 bool append, 318 SymbolContextList& sc_list); 319 320 //------------------------------------------------------------------ 321 /// Find functions by name. 322 /// 323 /// If the function is an inlined function, it will have a block, 324 /// representing the inlined function, and the function will be the 325 /// containing function. If it is not inlined, then the block will 326 /// be NULL. 327 /// 328 /// @param[in] regex 329 /// A regular expression to use when matching the name. 330 /// 331 /// @param[in] append 332 /// If \b true, any matches will be appended to \a sc_list, else 333 /// matches replace the contents of \a sc_list. 334 /// 335 /// @param[out] sc_list 336 /// A symbol context list that gets filled in with all of the 337 /// matches. 338 /// 339 /// @return 340 /// The number of matches added to \a sc_list. 341 //------------------------------------------------------------------ 342 size_t 343 FindFunctions (const RegularExpression& regex, 344 bool symbols_ok, 345 bool inlines_ok, 346 bool append, 347 SymbolContextList& sc_list); 348 349 //------------------------------------------------------------------ 350 /// Find addresses by file/line 351 /// 352 /// @param[in] target_sp 353 /// The target the addresses are desired for. 354 /// 355 /// @param[in] file 356 /// Source file to locate. 357 /// 358 /// @param[in] line 359 /// Source line to locate. 360 /// 361 /// @param[in] function 362 /// Optional filter function. Addresses within this function will be 363 /// added to the 'local' list. All others will be added to the 'extern' list. 364 /// 365 /// @param[out] output_local 366 /// All matching addresses within 'function' 367 /// 368 /// @param[out] output_extern 369 /// All matching addresses not within 'function' 370 void FindAddressesForLine (const lldb::TargetSP target_sp, 371 const FileSpec &file, uint32_t line, 372 Function *function, 373 std::vector<Address> &output_local, std::vector<Address> &output_extern); 374 375 //------------------------------------------------------------------ 376 /// Find global and static variables by name. 377 /// 378 /// @param[in] name 379 /// The name of the global or static variable we are looking 380 /// for. 381 /// 382 /// @param[in] namespace_decl 383 /// If valid, a namespace to search in. 384 /// 385 /// @param[in] append 386 /// If \b true, any matches will be appended to \a 387 /// variable_list, else matches replace the contents of 388 /// \a variable_list. 389 /// 390 /// @param[in] max_matches 391 /// Allow the number of matches to be limited to \a 392 /// max_matches. Specify UINT32_MAX to get all possible matches. 393 /// 394 /// @param[in] variable_list 395 /// A list of variables that gets the matches appended to (if 396 /// \a append it \b true), or replace (if \a append is \b false). 397 /// 398 /// @return 399 /// The number of matches added to \a variable_list. 400 //------------------------------------------------------------------ 401 size_t 402 FindGlobalVariables (const ConstString &name, 403 const ClangNamespaceDecl *namespace_decl, 404 bool append, 405 size_t max_matches, 406 VariableList& variable_list); 407 408 //------------------------------------------------------------------ 409 /// Find global and static variables by regular exression. 410 /// 411 /// @param[in] regex 412 /// A regular expression to use when matching the name. 413 /// 414 /// @param[in] append 415 /// If \b true, any matches will be appended to \a 416 /// variable_list, else matches replace the contents of 417 /// \a variable_list. 418 /// 419 /// @param[in] max_matches 420 /// Allow the number of matches to be limited to \a 421 /// max_matches. Specify UINT32_MAX to get all possible matches. 422 /// 423 /// @param[in] variable_list 424 /// A list of variables that gets the matches appended to (if 425 /// \a append it \b true), or replace (if \a append is \b false). 426 /// 427 /// @return 428 /// The number of matches added to \a variable_list. 429 //------------------------------------------------------------------ 430 size_t 431 FindGlobalVariables (const RegularExpression& regex, 432 bool append, 433 size_t max_matches, 434 VariableList& variable_list); 435 436 //------------------------------------------------------------------ 437 /// Find types by name. 438 /// 439 /// Type lookups in modules go through the SymbolVendor (which will 440 /// use one or more SymbolFile subclasses). The SymbolFile needs to 441 /// be able to lookup types by basename and not the fully qualified 442 /// typename. This allows the type accelerator tables to stay small, 443 /// even with heavily templatized C++. The type search will then 444 /// narrow down the search results. If "exact_match" is true, then 445 /// the type search will only match exact type name matches. If 446 /// "exact_match" is false, the type will match as long as the base 447 /// typename matches and as long as any immediate containing 448 /// namespaces/class scopes that are specified match. So to search 449 /// for a type "d" in "b::c", the name "b::c::d" can be specified 450 /// and it will match any class/namespace "b" which contains a 451 /// class/namespace "c" which contains type "d". We do this to 452 /// allow users to not always have to specify complete scoping on 453 /// all expressions, but it also allows for exact matching when 454 /// required. 455 /// 456 /// @param[in] sc 457 /// A symbol context that scopes where to extract a type list 458 /// from. 459 /// 460 /// @param[in] type_name 461 /// The name of the type we are looking for that is a fully 462 /// or partially qualfieid type name. 463 /// 464 /// @param[in] exact_match 465 /// If \b true, \a type_name is fully qualifed and must match 466 /// exactly. If \b false, \a type_name is a partially qualfied 467 /// name where the leading namespaces or classes can be 468 /// omitted to make finding types that a user may type 469 /// easier. 470 /// 471 /// @param[out] type_list 472 /// A type list gets populated with any matches. 473 /// 474 /// @return 475 /// The number of matches added to \a type_list. 476 //------------------------------------------------------------------ 477 size_t 478 FindTypes (const SymbolContext& sc, 479 const ConstString &type_name, 480 bool exact_match, 481 size_t max_matches, 482 TypeList& types); 483 484 lldb::TypeSP 485 FindFirstType (const SymbolContext& sc, 486 const ConstString &type_name, 487 bool exact_match); 488 489 //------------------------------------------------------------------ 490 /// Find types by name that are in a namespace. This function is 491 /// used by the expression parser when searches need to happen in 492 /// an exact namespace scope. 493 /// 494 /// @param[in] sc 495 /// A symbol context that scopes where to extract a type list 496 /// from. 497 /// 498 /// @param[in] type_name 499 /// The name of a type within a namespace that should not include 500 /// any qualifying namespaces (just a type basename). 501 /// 502 /// @param[in] namespace_decl 503 /// The namespace declaration that this type must exist in. 504 /// 505 /// @param[out] type_list 506 /// A type list gets populated with any matches. 507 /// 508 /// @return 509 /// The number of matches added to \a type_list. 510 //------------------------------------------------------------------ 511 size_t 512 FindTypesInNamespace (const SymbolContext& sc, 513 const ConstString &type_name, 514 const ClangNamespaceDecl *namespace_decl, 515 size_t max_matches, 516 TypeList& type_list); 517 518 //------------------------------------------------------------------ 519 /// Get const accessor for the module architecture. 520 /// 521 /// @return 522 /// A const reference to the architecture object. 523 //------------------------------------------------------------------ 524 const ArchSpec& 525 GetArchitecture () const; 526 527 //------------------------------------------------------------------ 528 /// Get const accessor for the module file specification. 529 /// 530 /// This function returns the file for the module on the host system 531 /// that is running LLDB. This can differ from the path on the 532 /// platform since we might be doing remote debugging. 533 /// 534 /// @return 535 /// A const reference to the file specification object. 536 //------------------------------------------------------------------ 537 const FileSpec & 538 GetFileSpec () const 539 { 540 return m_file; 541 } 542 543 //------------------------------------------------------------------ 544 /// Get accessor for the module platform file specification. 545 /// 546 /// Platform file refers to the path of the module as it is known on 547 /// the remote system on which it is being debugged. For local 548 /// debugging this is always the same as Module::GetFileSpec(). But 549 /// remote debugging might mention a file "/usr/lib/liba.dylib" 550 /// which might be locally downloaded and cached. In this case the 551 /// platform file could be something like: 552 /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" 553 /// The file could also be cached in a local developer kit directory. 554 /// 555 /// @return 556 /// A const reference to the file specification object. 557 //------------------------------------------------------------------ 558 const FileSpec & 559 GetPlatformFileSpec () const 560 { 561 if (m_platform_file) 562 return m_platform_file; 563 return m_file; 564 } 565 566 void 567 SetPlatformFileSpec (const FileSpec &file) 568 { 569 m_platform_file = file; 570 } 571 572 const FileSpec & 573 GetRemoteInstallFileSpec () const 574 { 575 return m_remote_install_file; 576 } 577 578 void 579 SetRemoteInstallFileSpec (const FileSpec &file) 580 { 581 m_remote_install_file = file; 582 } 583 584 const FileSpec & 585 GetSymbolFileFileSpec () const 586 { 587 return m_symfile_spec; 588 } 589 590 void 591 SetSymbolFileFileSpec (const FileSpec &file); 592 593 const TimeValue & 594 GetModificationTime () const 595 { 596 return m_mod_time; 597 } 598 599 const TimeValue & 600 GetObjectModificationTime () const 601 { 602 return m_object_mod_time; 603 } 604 605 void 606 SetObjectModificationTime (const TimeValue &mod_time) 607 { 608 m_mod_time = mod_time; 609 } 610 611 //------------------------------------------------------------------ 612 /// Tells whether this module is capable of being the main executable 613 /// for a process. 614 /// 615 /// @return 616 /// \b true if it is, \b false otherwise. 617 //------------------------------------------------------------------ 618 bool 619 IsExecutable (); 620 621 //------------------------------------------------------------------ 622 /// Tells whether this module has been loaded in the target passed in. 623 /// This call doesn't distinguish between whether the module is loaded 624 /// by the dynamic loader, or by a "target module add" type call. 625 /// 626 /// @param[in] target 627 /// The target to check whether this is loaded in. 628 /// 629 /// @return 630 /// \b true if it is, \b false otherwise. 631 //------------------------------------------------------------------ 632 bool 633 IsLoadedInTarget (Target *target); 634 635 bool 636 LoadScriptingResourceInTarget (Target *target, 637 Error& error, 638 Stream* feedback_stream = NULL); 639 640 //------------------------------------------------------------------ 641 /// Get the number of compile units for this module. 642 /// 643 /// @return 644 /// The number of compile units that the symbol vendor plug-in 645 /// finds. 646 //------------------------------------------------------------------ 647 size_t 648 GetNumCompileUnits(); 649 650 lldb::CompUnitSP 651 GetCompileUnitAtIndex (size_t idx); 652 653 const ConstString & 654 GetObjectName() const; 655 656 uint64_t 657 GetObjectOffset() const 658 { 659 return m_object_offset; 660 } 661 662 //------------------------------------------------------------------ 663 /// Get the object file representation for the current architecture. 664 /// 665 /// If the object file has not been located or parsed yet, this 666 /// function will find the best ObjectFile plug-in that can parse 667 /// Module::m_file. 668 /// 669 /// @return 670 /// If Module::m_file does not exist, or no plug-in was found 671 /// that can parse the file, or the object file doesn't contain 672 /// the current architecture in Module::m_arch, NULL will be 673 /// returned, else a valid object file interface will be 674 /// returned. The returned pointer is owned by this object and 675 /// remains valid as long as the object is around. 676 //------------------------------------------------------------------ 677 virtual ObjectFile * 678 GetObjectFile (); 679 680 //------------------------------------------------------------------ 681 /// Get the unified section list for the module. This is the section 682 /// list created by the module's object file and any debug info and 683 /// symbol files created by the symbol vendor. 684 /// 685 /// If the symbol vendor has not been loaded yet, this function 686 /// will return the section list for the object file. 687 /// 688 /// @return 689 /// Unified module section list. 690 //------------------------------------------------------------------ 691 virtual SectionList * 692 GetSectionList (); 693 694 uint32_t 695 GetVersion (uint32_t *versions, uint32_t num_versions); 696 697 // Load an object file from memory. 698 ObjectFile * 699 GetMemoryObjectFile (const lldb::ProcessSP &process_sp, 700 lldb::addr_t header_addr, 701 Error &error); 702 //------------------------------------------------------------------ 703 /// Get the symbol vendor interface for the current architecture. 704 /// 705 /// If the symbol vendor file has not been located yet, this 706 /// function will find the best SymbolVendor plug-in that can 707 /// use the current object file. 708 /// 709 /// @return 710 /// If this module does not have a valid object file, or no 711 /// plug-in can be found that can use the object file, NULL will 712 /// be returned, else a valid symbol vendor plug-in interface 713 /// will be returned. The returned pointer is owned by this 714 /// object and remains valid as long as the object is around. 715 //------------------------------------------------------------------ 716 virtual SymbolVendor* 717 GetSymbolVendor(bool can_create = true, 718 lldb_private::Stream *feedback_strm = NULL); 719 720 //------------------------------------------------------------------ 721 /// Get accessor the type list for this module. 722 /// 723 /// @return 724 /// A valid type list pointer, or NULL if there is no valid 725 /// symbol vendor for this module. 726 //------------------------------------------------------------------ 727 TypeList* 728 GetTypeList (); 729 730 //------------------------------------------------------------------ 731 /// Get a pointer to the UUID value contained in this object. 732 /// 733 /// If the executable image file doesn't not have a UUID value built 734 /// into the file format, an MD5 checksum of the entire file, or 735 /// slice of the file for the current architecture should be used. 736 /// 737 /// @return 738 /// A const pointer to the internal copy of the UUID value in 739 /// this module if this module has a valid UUID value, NULL 740 /// otherwise. 741 //------------------------------------------------------------------ 742 const lldb_private::UUID & 743 GetUUID (); 744 745 //------------------------------------------------------------------ 746 /// A debugging function that will cause everything in a module to 747 /// be parsed. 748 /// 749 /// All compile units will be pasred, along with all globals and 750 /// static variables and all functions for those compile units. 751 /// All types, scopes, local variables, static variables, global 752 /// variables, and line tables will be parsed. This can be used 753 /// prior to dumping a module to see a complete list of the 754 /// resuling debug information that gets parsed, or as a debug 755 /// function to ensure that the module can consume all of the 756 /// debug data the symbol vendor provides. 757 //------------------------------------------------------------------ 758 void 759 ParseAllDebugSymbols(); 760 761 bool 762 ResolveFileAddress (lldb::addr_t vm_addr, Address& so_addr); 763 764 //------------------------------------------------------------------ 765 /// Resolve the symbol context for the given address. 766 /// 767 /// Tries to resolve the matching symbol context based on a lookup 768 /// from the current symbol vendor. If the lazy lookup fails, 769 /// an attempt is made to parse the eh_frame section to handle 770 /// stripped symbols. If this fails, an attempt is made to resolve 771 /// the symbol to the previous address to handle the case of a 772 /// function with a tail call. 773 /// 774 /// Use properties of the modified SymbolContext to inspect any 775 /// resolved target, module, compilation unit, symbol, function, 776 /// function block or line entry. Use the return value to determine 777 /// which of these properties have been modified. 778 /// 779 /// @param[in] so_addr 780 /// A load address to resolve. 781 /// 782 /// @param[in] resolve_scope 783 /// The scope that should be resolved (see SymbolContext::Scope). 784 /// A combination of flags from the enumeration SymbolContextItem 785 /// requesting a resolution depth. Note that the flags that are 786 /// actually resolved may be a superset of the requested flags. 787 /// For instance, eSymbolContextSymbol requires resolution of 788 /// eSymbolContextModule, and eSymbolContextFunction requires 789 /// eSymbolContextSymbol. 790 /// 791 /// @param[out] sc 792 /// The SymbolContext that is modified based on symbol resolution. 793 /// 794 /// @param[in] resolve_tail_call_address 795 /// Determines if so_addr should resolve to a symbol in the case 796 /// of a function whose last instruction is a call. In this case, 797 /// the PC can be one past the address range of the function. 798 /// 799 /// @return 800 /// The scope that has been resolved (see SymbolContext::Scope). 801 /// 802 /// @see SymbolContext::Scope 803 //------------------------------------------------------------------ 804 uint32_t 805 ResolveSymbolContextForAddress (const Address& so_addr, uint32_t resolve_scope, 806 SymbolContext& sc, bool resolve_tail_call_address = false); 807 808 //------------------------------------------------------------------ 809 /// Resolve items in the symbol context for a given file and line. 810 /// 811 /// Tries to resolve \a file_path and \a line to a list of matching 812 /// symbol contexts. 813 /// 814 /// The line table entries contains addresses that can be used to 815 /// further resolve the values in each match: the function, block, 816 /// symbol. Care should be taken to minimize the amount of 817 /// information that is requested to only what is needed -- 818 /// typically the module, compile unit, line table and line table 819 /// entry are sufficient. 820 /// 821 /// @param[in] file_path 822 /// A path to a source file to match. If \a file_path does not 823 /// specify a directory, then this query will match all files 824 /// whose base filename matches. If \a file_path does specify 825 /// a directory, the fullpath to the file must match. 826 /// 827 /// @param[in] line 828 /// The source line to match, or zero if just the compile unit 829 /// should be resolved. 830 /// 831 /// @param[in] check_inlines 832 /// Check for inline file and line number matches. This option 833 /// should be used sparingly as it will cause all line tables 834 /// for every compile unit to be parsed and searched for 835 /// matching inline file entries. 836 /// 837 /// @param[in] resolve_scope 838 /// The scope that should be resolved (see 839 /// SymbolContext::Scope). 840 /// 841 /// @param[out] sc_list 842 /// A symbol context list that gets matching symbols contexts 843 /// appended to. 844 /// 845 /// @return 846 /// The number of matches that were added to \a sc_list. 847 /// 848 /// @see SymbolContext::Scope 849 //------------------------------------------------------------------ 850 uint32_t 851 ResolveSymbolContextForFilePath (const char *file_path, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list); 852 853 //------------------------------------------------------------------ 854 /// Resolve items in the symbol context for a given file and line. 855 /// 856 /// Tries to resolve \a file_spec and \a line to a list of matching 857 /// symbol contexts. 858 /// 859 /// The line table entries contains addresses that can be used to 860 /// further resolve the values in each match: the function, block, 861 /// symbol. Care should be taken to minimize the amount of 862 /// information that is requested to only what is needed -- 863 /// typically the module, compile unit, line table and line table 864 /// entry are sufficient. 865 /// 866 /// @param[in] file_spec 867 /// A file spec to a source file to match. If \a file_path does 868 /// not specify a directory, then this query will match all 869 /// files whose base filename matches. If \a file_path does 870 /// specify a directory, the fullpath to the file must match. 871 /// 872 /// @param[in] line 873 /// The source line to match, or zero if just the compile unit 874 /// should be resolved. 875 /// 876 /// @param[in] check_inlines 877 /// Check for inline file and line number matches. This option 878 /// should be used sparingly as it will cause all line tables 879 /// for every compile unit to be parsed and searched for 880 /// matching inline file entries. 881 /// 882 /// @param[in] resolve_scope 883 /// The scope that should be resolved (see 884 /// SymbolContext::Scope). 885 /// 886 /// @param[out] sc_list 887 /// A symbol context list that gets filled in with all of the 888 /// matches. 889 /// 890 /// @return 891 /// A integer that contains SymbolContext::Scope bits set for 892 /// each item that was successfully resolved. 893 /// 894 /// @see SymbolContext::Scope 895 //------------------------------------------------------------------ 896 uint32_t 897 ResolveSymbolContextsForFileSpec (const FileSpec &file_spec, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list); 898 899 900 void 901 SetFileSpecAndObjectName (const FileSpec &file, 902 const ConstString &object_name); 903 904 bool 905 GetIsDynamicLinkEditor () const 906 { 907 return m_is_dynamic_loader_module; 908 } 909 910 void 911 SetIsDynamicLinkEditor (bool b) 912 { 913 m_is_dynamic_loader_module = b; 914 } 915 916 ClangASTContext & 917 GetClangASTContext (); 918 919 // Special error functions that can do printf style formatting that will prepend the message with 920 // something appropriate for this module (like the architecture, path and object name (if any)). 921 // This centralizes code so that everyone doesn't need to format their error and log messages on 922 // their own and keeps the output a bit more consistent. 923 void 924 LogMessage (Log *log, const char *format, ...) __attribute__ ((format (printf, 3, 4))); 925 926 void 927 LogMessageVerboseBacktrace (Log *log, const char *format, ...) __attribute__ ((format (printf, 3, 4))); 928 929 void 930 ReportWarning (const char *format, ...) __attribute__ ((format (printf, 2, 3))); 931 932 void 933 ReportError (const char *format, ...) __attribute__ ((format (printf, 2, 3))); 934 935 // Only report an error once when the module is first detected to be modified 936 // so we don't spam the console with many messages. 937 void 938 ReportErrorIfModifyDetected (const char *format, ...) __attribute__ ((format (printf, 2, 3))); 939 940 //------------------------------------------------------------------ 941 // Return true if the file backing this module has changed since the 942 // module was originally created since we saved the intial file 943 // modification time when the module first gets created. 944 //------------------------------------------------------------------ 945 bool 946 FileHasChanged () const; 947 948 //------------------------------------------------------------------ 949 // SymbolVendor, SymbolFile and ObjectFile member objects should 950 // lock the module mutex to avoid deadlocks. 951 //------------------------------------------------------------------ 952 Mutex & 953 GetMutex () const 954 { 955 return m_mutex; 956 } 957 958 PathMappingList & 959 GetSourceMappingList () 960 { 961 return m_source_mappings; 962 } 963 964 const PathMappingList & 965 GetSourceMappingList () const 966 { 967 return m_source_mappings; 968 } 969 970 //------------------------------------------------------------------ 971 /// Finds a source file given a file spec using the module source 972 /// path remappings (if any). 973 /// 974 /// Tries to resolve \a orig_spec by checking the module source path 975 /// remappings. It makes sure the file exists, so this call can be 976 /// expensive if the remappings are on a network file system, so 977 /// use this function sparingly (not in a tight debug info parsing 978 /// loop). 979 /// 980 /// @param[in] orig_spec 981 /// The original source file path to try and remap. 982 /// 983 /// @param[out] new_spec 984 /// The newly remapped filespec that is guaranteed to exist. 985 /// 986 /// @return 987 /// /b true if \a orig_spec was successfully located and 988 /// \a new_spec is filled in with an existing file spec, 989 /// \b false otherwise. 990 //------------------------------------------------------------------ 991 bool 992 FindSourceFile (const FileSpec &orig_spec, FileSpec &new_spec) const; 993 994 //------------------------------------------------------------------ 995 /// Remaps a source file given \a path into \a new_path. 996 /// 997 /// Remaps \a path if any source remappings match. This function 998 /// does NOT stat the file system so it can be used in tight loops 999 /// where debug info is being parsed. 1000 /// 1001 /// @param[in] path 1002 /// The original source file path to try and remap. 1003 /// 1004 /// @param[out] new_path 1005 /// The newly remapped filespec that is may or may not exist. 1006 /// 1007 /// @return 1008 /// /b true if \a path was successfully located and \a new_path 1009 /// is filled in with a new source path, \b false otherwise. 1010 //------------------------------------------------------------------ 1011 bool 1012 RemapSourceFile (const char *path, std::string &new_path) const; 1013 1014 1015 //------------------------------------------------------------------ 1016 /// Prepare to do a function name lookup. 1017 /// 1018 /// Looking up functions by name can be a tricky thing. LLDB requires 1019 /// that accelerator tables contain full names for functions as well 1020 /// as function basenames which include functions, class methods and 1021 /// class functions. When the user requests that an action use a 1022 /// function by name, we are sometimes asked to automatically figure 1023 /// out what a name could possibly map to. A user might request a 1024 /// breakpoint be set on "count". If no options are supplied to limit 1025 /// the scope of where to search for count, we will by default match 1026 /// any function names named "count", all class and instance methods 1027 /// named "count" (no matter what the namespace or contained context) 1028 /// and any selectors named "count". If a user specifies "a::b" we 1029 /// will search for the basename "b", and then prune the results that 1030 /// don't match "a::b" (note that "c::a::b" and "d::e::a::b" will 1031 /// match a query of "a::b". 1032 /// 1033 /// @param[in] name 1034 /// The user supplied name to use in the lookup 1035 /// 1036 /// @param[in] name_type_mask 1037 /// The mask of bits from lldb::FunctionNameType enumerations 1038 /// that tell us what kind of name we are looking for. 1039 /// 1040 /// @param[out] lookup_name 1041 /// The actual name that will be used when calling 1042 /// SymbolVendor::FindFunctions() or Symtab::FindFunctionSymbols() 1043 /// 1044 /// @param[out] lookup_name_type_mask 1045 /// The actual name mask that should be used in the calls to 1046 /// SymbolVendor::FindFunctions() or Symtab::FindFunctionSymbols() 1047 /// 1048 /// @param[out] match_name_after_lookup 1049 /// A boolean that indicates if we need to iterate through any 1050 /// match results obtained from SymbolVendor::FindFunctions() or 1051 /// Symtab::FindFunctionSymbols() to see if the name contains 1052 /// \a name. For example if \a name is "a::b", this function will 1053 /// return a \a lookup_name of "b", with \a match_name_after_lookup 1054 /// set to true to indicate any matches will need to be checked 1055 /// to make sure they contain \a name. 1056 //------------------------------------------------------------------ 1057 static void 1058 PrepareForFunctionNameLookup (const ConstString &name, 1059 uint32_t name_type_mask, 1060 ConstString &lookup_name, 1061 uint32_t &lookup_name_type_mask, 1062 bool &match_name_after_lookup); 1063 1064protected: 1065 //------------------------------------------------------------------ 1066 // Member Variables 1067 //------------------------------------------------------------------ 1068 mutable Mutex m_mutex; ///< A mutex to keep this object happy in multi-threaded environments. 1069 TimeValue m_mod_time; ///< The modification time for this module when it was created. 1070 ArchSpec m_arch; ///< The architecture for this module. 1071 lldb_private::UUID m_uuid; ///< Each module is assumed to have a unique identifier to help match it up to debug symbols. 1072 FileSpec m_file; ///< The file representation on disk for this module (if there is one). 1073 FileSpec m_platform_file;///< The path to the module on the platform on which it is being debugged 1074 FileSpec m_remote_install_file; ///< If set when debugging on remote platforms, this module will be installed at this location 1075 FileSpec m_symfile_spec; ///< If this path is valid, then this is the file that _will_ be used as the symbol file for this module 1076 ConstString m_object_name; ///< The name an object within this module that is selected, or empty of the module is represented by \a m_file. 1077 uint64_t m_object_offset; 1078 TimeValue m_object_mod_time; 1079 lldb::ObjectFileSP m_objfile_sp; ///< A shared pointer to the object file parser for this module as it may or may not be shared with the SymbolFile 1080 std::unique_ptr<SymbolVendor> m_symfile_ap; ///< A pointer to the symbol vendor for this module. 1081 ClangASTContext m_ast; ///< The AST context for this module. 1082 PathMappingList m_source_mappings; ///< Module specific source remappings for when you have debug info for a module that doesn't match where the sources currently are 1083 std::unique_ptr<lldb_private::SectionList> m_sections_ap; ///< Unified section list for module that is used by the ObjectFile and and ObjectFile instances for the debug info 1084 1085 bool m_did_load_objfile:1, 1086 m_did_load_symbol_vendor:1, 1087 m_did_parse_uuid:1, 1088 m_did_init_ast:1, 1089 m_is_dynamic_loader_module:1; 1090 mutable bool m_file_has_changed:1, 1091 m_first_file_changed_log:1; /// See if the module was modified after it was initially opened. 1092 1093 //------------------------------------------------------------------ 1094 /// Resolve a file or load virtual address. 1095 /// 1096 /// Tries to resolve \a vm_addr as a file address (if \a 1097 /// vm_addr_is_file_addr is true) or as a load address if \a 1098 /// vm_addr_is_file_addr is false) in the symbol vendor. 1099 /// \a resolve_scope indicates what clients wish to resolve 1100 /// and can be used to limit the scope of what is parsed. 1101 /// 1102 /// @param[in] vm_addr 1103 /// The load virtual address to resolve. 1104 /// 1105 /// @param[in] vm_addr_is_file_addr 1106 /// If \b true, \a vm_addr is a file address, else \a vm_addr 1107 /// if a load address. 1108 /// 1109 /// @param[in] resolve_scope 1110 /// The scope that should be resolved (see 1111 /// SymbolContext::Scope). 1112 /// 1113 /// @param[out] so_addr 1114 /// The section offset based address that got resolved if 1115 /// any bits are returned. 1116 /// 1117 /// @param[out] sc 1118 // The symbol context that has objects filled in. Each bit 1119 /// in the \a resolve_scope pertains to a member in the \a sc. 1120 /// 1121 /// @return 1122 /// A integer that contains SymbolContext::Scope bits set for 1123 /// each item that was successfully resolved. 1124 /// 1125 /// @see SymbolContext::Scope 1126 //------------------------------------------------------------------ 1127 uint32_t 1128 ResolveSymbolContextForAddress (lldb::addr_t vm_addr, 1129 bool vm_addr_is_file_addr, 1130 uint32_t resolve_scope, 1131 Address& so_addr, 1132 SymbolContext& sc); 1133 1134 void 1135 SymbolIndicesToSymbolContextList (Symtab *symtab, 1136 std::vector<uint32_t> &symbol_indexes, 1137 SymbolContextList &sc_list); 1138 1139 bool 1140 SetArchitecture (const ArchSpec &new_arch); 1141 1142 SectionList * 1143 GetUnifiedSectionList(); 1144 1145 friend class ModuleList; 1146 friend class ObjectFile; 1147 friend class SymbolFile; 1148 1149private: 1150 1151 size_t 1152 FindTypes_Impl (const SymbolContext& sc, 1153 const ConstString &name, 1154 const ClangNamespaceDecl *namespace_decl, 1155 bool append, 1156 size_t max_matches, 1157 TypeList& types); 1158 1159 1160 DISALLOW_COPY_AND_ASSIGN (Module); 1161}; 1162 1163} // namespace lldb_private 1164 1165#endif // liblldb_Module_h_ 1166