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