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 22 namespace 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 //---------------------------------------------------------------------- 43 class Module : 44 public std::enable_shared_from_this<Module>, 45 public SymbolContextScope 46 { 47 public: 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 global and static variables by name. 351 /// 352 /// @param[in] name 353 /// The name of the global or static variable we are looking 354 /// for. 355 /// 356 /// @param[in] namespace_decl 357 /// If valid, a namespace to search in. 358 /// 359 /// @param[in] append 360 /// If \b true, any matches will be appended to \a 361 /// variable_list, else matches replace the contents of 362 /// \a variable_list. 363 /// 364 /// @param[in] max_matches 365 /// Allow the number of matches to be limited to \a 366 /// max_matches. Specify UINT32_MAX to get all possible matches. 367 /// 368 /// @param[in] variable_list 369 /// A list of variables that gets the matches appended to (if 370 /// \a append it \b true), or replace (if \a append is \b false). 371 /// 372 /// @return 373 /// The number of matches added to \a variable_list. 374 //------------------------------------------------------------------ 375 size_t 376 FindGlobalVariables (const ConstString &name, 377 const ClangNamespaceDecl *namespace_decl, 378 bool append, 379 size_t max_matches, 380 VariableList& variable_list); 381 382 //------------------------------------------------------------------ 383 /// Find global and static variables by regular exression. 384 /// 385 /// @param[in] regex 386 /// A regular expression to use when matching the name. 387 /// 388 /// @param[in] append 389 /// If \b true, any matches will be appended to \a 390 /// variable_list, else matches replace the contents of 391 /// \a variable_list. 392 /// 393 /// @param[in] max_matches 394 /// Allow the number of matches to be limited to \a 395 /// max_matches. Specify UINT32_MAX to get all possible matches. 396 /// 397 /// @param[in] variable_list 398 /// A list of variables that gets the matches appended to (if 399 /// \a append it \b true), or replace (if \a append is \b false). 400 /// 401 /// @return 402 /// The number of matches added to \a variable_list. 403 //------------------------------------------------------------------ 404 size_t 405 FindGlobalVariables (const RegularExpression& regex, 406 bool append, 407 size_t max_matches, 408 VariableList& variable_list); 409 410 //------------------------------------------------------------------ 411 /// Find types by name. 412 /// 413 /// Type lookups in modules go through the SymbolVendor (which will 414 /// use one or more SymbolFile subclasses). The SymbolFile needs to 415 /// be able to lookup types by basename and not the fully qualified 416 /// typename. This allows the type accelerator tables to stay small, 417 /// even with heavily templatized C++. The type search will then 418 /// narrow down the search results. If "exact_match" is true, then 419 /// the type search will only match exact type name matches. If 420 /// "exact_match" is false, the type will match as long as the base 421 /// typename matches and as long as any immediate containing 422 /// namespaces/class scopes that are specified match. So to search 423 /// for a type "d" in "b::c", the name "b::c::d" can be specified 424 /// and it will match any class/namespace "b" which contains a 425 /// class/namespace "c" which contains type "d". We do this to 426 /// allow users to not always have to specify complete scoping on 427 /// all expressions, but it also allows for exact matching when 428 /// required. 429 /// 430 /// @param[in] sc 431 /// A symbol context that scopes where to extract a type list 432 /// from. 433 /// 434 /// @param[in] type_name 435 /// The name of the type we are looking for that is a fully 436 /// or partially qualfieid type name. 437 /// 438 /// @param[in] exact_match 439 /// If \b true, \a type_name is fully qualifed and must match 440 /// exactly. If \b false, \a type_name is a partially qualfied 441 /// name where the leading namespaces or classes can be 442 /// omitted to make finding types that a user may type 443 /// easier. 444 /// 445 /// @param[out] type_list 446 /// A type list gets populated with any matches. 447 /// 448 /// @return 449 /// The number of matches added to \a type_list. 450 //------------------------------------------------------------------ 451 size_t 452 FindTypes (const SymbolContext& sc, 453 const ConstString &type_name, 454 bool exact_match, 455 size_t max_matches, 456 TypeList& types); 457 458 lldb::TypeSP 459 FindFirstType (const SymbolContext& sc, 460 const ConstString &type_name, 461 bool exact_match); 462 463 //------------------------------------------------------------------ 464 /// Find types by name that are in a namespace. This function is 465 /// used by the expression parser when searches need to happen in 466 /// an exact namespace scope. 467 /// 468 /// @param[in] sc 469 /// A symbol context that scopes where to extract a type list 470 /// from. 471 /// 472 /// @param[in] type_name 473 /// The name of a type within a namespace that should not include 474 /// any qualifying namespaces (just a type basename). 475 /// 476 /// @param[in] namespace_decl 477 /// The namespace declaration that this type must exist in. 478 /// 479 /// @param[out] type_list 480 /// A type list gets populated with any matches. 481 /// 482 /// @return 483 /// The number of matches added to \a type_list. 484 //------------------------------------------------------------------ 485 size_t 486 FindTypesInNamespace (const SymbolContext& sc, 487 const ConstString &type_name, 488 const ClangNamespaceDecl *namespace_decl, 489 size_t max_matches, 490 TypeList& type_list); 491 492 //------------------------------------------------------------------ 493 /// Get const accessor for the module architecture. 494 /// 495 /// @return 496 /// A const reference to the architecture object. 497 //------------------------------------------------------------------ 498 const ArchSpec& 499 GetArchitecture () const; 500 501 //------------------------------------------------------------------ 502 /// Get const accessor for the module file specification. 503 /// 504 /// This function returns the file for the module on the host system 505 /// that is running LLDB. This can differ from the path on the 506 /// platform since we might be doing remote debugging. 507 /// 508 /// @return 509 /// A const reference to the file specification object. 510 //------------------------------------------------------------------ 511 const FileSpec & GetFileSpec()512 GetFileSpec () const 513 { 514 return m_file; 515 } 516 517 //------------------------------------------------------------------ 518 /// Get accessor for the module platform file specification. 519 /// 520 /// Platform file refers to the path of the module as it is known on 521 /// the remote system on which it is being debugged. For local 522 /// debugging this is always the same as Module::GetFileSpec(). But 523 /// remote debugging might mention a file "/usr/lib/liba.dylib" 524 /// which might be locally downloaded and cached. In this case the 525 /// platform file could be something like: 526 /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" 527 /// The file could also be cached in a local developer kit directory. 528 /// 529 /// @return 530 /// A const reference to the file specification object. 531 //------------------------------------------------------------------ 532 const FileSpec & GetPlatformFileSpec()533 GetPlatformFileSpec () const 534 { 535 if (m_platform_file) 536 return m_platform_file; 537 return m_file; 538 } 539 540 void SetPlatformFileSpec(const FileSpec & file)541 SetPlatformFileSpec (const FileSpec &file) 542 { 543 m_platform_file = file; 544 } 545 546 const FileSpec & GetSymbolFileFileSpec()547 GetSymbolFileFileSpec () const 548 { 549 return m_symfile_spec; 550 } 551 552 void 553 SetSymbolFileFileSpec (const FileSpec &file); 554 555 const TimeValue & GetModificationTime()556 GetModificationTime () const 557 { 558 return m_mod_time; 559 } 560 561 const TimeValue & GetObjectModificationTime()562 GetObjectModificationTime () const 563 { 564 return m_object_mod_time; 565 } 566 567 void SetObjectModificationTime(const TimeValue & mod_time)568 SetObjectModificationTime (const TimeValue &mod_time) 569 { 570 m_mod_time = mod_time; 571 } 572 573 //------------------------------------------------------------------ 574 /// Tells whether this module is capable of being the main executable 575 /// for a process. 576 /// 577 /// @return 578 /// \b true if it is, \b false otherwise. 579 //------------------------------------------------------------------ 580 bool 581 IsExecutable (); 582 583 //------------------------------------------------------------------ 584 /// Tells whether this module has been loaded in the target passed in. 585 /// This call doesn't distinguish between whether the module is loaded 586 /// by the dynamic loader, or by a "target module add" type call. 587 /// 588 /// @param[in] target 589 /// The target to check whether this is loaded in. 590 /// 591 /// @return 592 /// \b true if it is, \b false otherwise. 593 //------------------------------------------------------------------ 594 bool 595 IsLoadedInTarget (Target *target); 596 597 bool 598 LoadScriptingResourceInTarget (Target *target, 599 Error& error, 600 Stream* feedback_stream = NULL); 601 602 //------------------------------------------------------------------ 603 /// Get the number of compile units for this module. 604 /// 605 /// @return 606 /// The number of compile units that the symbol vendor plug-in 607 /// finds. 608 //------------------------------------------------------------------ 609 size_t 610 GetNumCompileUnits(); 611 612 lldb::CompUnitSP 613 GetCompileUnitAtIndex (size_t idx); 614 615 const ConstString & 616 GetObjectName() const; 617 618 uint64_t GetObjectOffset()619 GetObjectOffset() const 620 { 621 return m_object_offset; 622 } 623 624 //------------------------------------------------------------------ 625 /// Get the object file representation for the current architecture. 626 /// 627 /// If the object file has not been located or parsed yet, this 628 /// function will find the best ObjectFile plug-in that can parse 629 /// Module::m_file. 630 /// 631 /// @return 632 /// If Module::m_file does not exist, or no plug-in was found 633 /// that can parse the file, or the object file doesn't contain 634 /// the current architecture in Module::m_arch, NULL will be 635 /// returned, else a valid object file interface will be 636 /// returned. The returned pointer is owned by this object and 637 /// remains valid as long as the object is around. 638 //------------------------------------------------------------------ 639 virtual ObjectFile * 640 GetObjectFile (); 641 642 //------------------------------------------------------------------ 643 /// Get the unified section list for the module. This is the section 644 /// list created by the module's object file and any debug info and 645 /// symbol files created by the symbol vendor. 646 /// 647 /// If the symbol vendor has not been loaded yet, this function 648 /// will return the section list for the object file. 649 /// 650 /// @return 651 /// Unified module section list. 652 //------------------------------------------------------------------ 653 virtual SectionList * 654 GetSectionList (); 655 656 uint32_t 657 GetVersion (uint32_t *versions, uint32_t num_versions); 658 659 // Load an object file from memory. 660 ObjectFile * 661 GetMemoryObjectFile (const lldb::ProcessSP &process_sp, 662 lldb::addr_t header_addr, 663 Error &error); 664 //------------------------------------------------------------------ 665 /// Get the symbol vendor interface for the current architecture. 666 /// 667 /// If the symbol vendor file has not been located yet, this 668 /// function will find the best SymbolVendor plug-in that can 669 /// use the current object file. 670 /// 671 /// @return 672 /// If this module does not have a valid object file, or no 673 /// plug-in can be found that can use the object file, NULL will 674 /// be returned, else a valid symbol vendor plug-in interface 675 /// will be returned. The returned pointer is owned by this 676 /// object and remains valid as long as the object is around. 677 //------------------------------------------------------------------ 678 virtual SymbolVendor* 679 GetSymbolVendor(bool can_create = true, 680 lldb_private::Stream *feedback_strm = NULL); 681 682 //------------------------------------------------------------------ 683 /// Get accessor the type list for this module. 684 /// 685 /// @return 686 /// A valid type list pointer, or NULL if there is no valid 687 /// symbol vendor for this module. 688 //------------------------------------------------------------------ 689 TypeList* 690 GetTypeList (); 691 692 //------------------------------------------------------------------ 693 /// Get a pointer to the UUID value contained in this object. 694 /// 695 /// If the executable image file doesn't not have a UUID value built 696 /// into the file format, an MD5 checksum of the entire file, or 697 /// slice of the file for the current architecture should be used. 698 /// 699 /// @return 700 /// A const pointer to the internal copy of the UUID value in 701 /// this module if this module has a valid UUID value, NULL 702 /// otherwise. 703 //------------------------------------------------------------------ 704 const lldb_private::UUID & 705 GetUUID (); 706 707 //------------------------------------------------------------------ 708 /// A debugging function that will cause everything in a module to 709 /// be parsed. 710 /// 711 /// All compile units will be pasred, along with all globals and 712 /// static variables and all functions for those compile units. 713 /// All types, scopes, local variables, static variables, global 714 /// variables, and line tables will be parsed. This can be used 715 /// prior to dumping a module to see a complete list of the 716 /// resuling debug information that gets parsed, or as a debug 717 /// function to ensure that the module can consume all of the 718 /// debug data the symbol vendor provides. 719 //------------------------------------------------------------------ 720 void 721 ParseAllDebugSymbols(); 722 723 bool 724 ResolveFileAddress (lldb::addr_t vm_addr, Address& so_addr); 725 726 uint32_t 727 ResolveSymbolContextForAddress (const Address& so_addr, uint32_t resolve_scope, SymbolContext& sc); 728 729 //------------------------------------------------------------------ 730 /// Resolve items in the symbol context for a given file and line. 731 /// 732 /// Tries to resolve \a file_path and \a line to a list of matching 733 /// symbol contexts. 734 /// 735 /// The line table entries contains addresses that can be used to 736 /// further resolve the values in each match: the function, block, 737 /// symbol. Care should be taken to minimize the amount of 738 /// information that is requested to only what is needed -- 739 /// typically the module, compile unit, line table and line table 740 /// entry are sufficient. 741 /// 742 /// @param[in] file_path 743 /// A path to a source file to match. If \a file_path does not 744 /// specify a directory, then this query will match all files 745 /// whose base filename matches. If \a file_path does specify 746 /// a directory, the fullpath to the file must match. 747 /// 748 /// @param[in] line 749 /// The source line to match, or zero if just the compile unit 750 /// should be resolved. 751 /// 752 /// @param[in] check_inlines 753 /// Check for inline file and line number matches. This option 754 /// should be used sparingly as it will cause all line tables 755 /// for every compile unit to be parsed and searched for 756 /// matching inline file entries. 757 /// 758 /// @param[in] resolve_scope 759 /// The scope that should be resolved (see 760 /// SymbolContext::Scope). 761 /// 762 /// @param[out] sc_list 763 /// A symbol context list that gets matching symbols contexts 764 /// appended to. 765 /// 766 /// @return 767 /// The number of matches that were added to \a sc_list. 768 /// 769 /// @see SymbolContext::Scope 770 //------------------------------------------------------------------ 771 uint32_t 772 ResolveSymbolContextForFilePath (const char *file_path, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list); 773 774 //------------------------------------------------------------------ 775 /// Resolve items in the symbol context for a given file and line. 776 /// 777 /// Tries to resolve \a file_spec and \a line to a list of matching 778 /// symbol contexts. 779 /// 780 /// The line table entries contains addresses that can be used to 781 /// further resolve the values in each match: the function, block, 782 /// symbol. Care should be taken to minimize the amount of 783 /// information that is requested to only what is needed -- 784 /// typically the module, compile unit, line table and line table 785 /// entry are sufficient. 786 /// 787 /// @param[in] file_spec 788 /// A file spec to a source file to match. If \a file_path does 789 /// not specify a directory, then this query will match all 790 /// files whose base filename matches. If \a file_path does 791 /// specify a directory, the fullpath to the file must match. 792 /// 793 /// @param[in] line 794 /// The source line to match, or zero if just the compile unit 795 /// should be resolved. 796 /// 797 /// @param[in] check_inlines 798 /// Check for inline file and line number matches. This option 799 /// should be used sparingly as it will cause all line tables 800 /// for every compile unit to be parsed and searched for 801 /// matching inline file entries. 802 /// 803 /// @param[in] resolve_scope 804 /// The scope that should be resolved (see 805 /// SymbolContext::Scope). 806 /// 807 /// @param[out] sc_list 808 /// A symbol context list that gets filled in with all of the 809 /// matches. 810 /// 811 /// @return 812 /// A integer that contains SymbolContext::Scope bits set for 813 /// each item that was successfully resolved. 814 /// 815 /// @see SymbolContext::Scope 816 //------------------------------------------------------------------ 817 uint32_t 818 ResolveSymbolContextsForFileSpec (const FileSpec &file_spec, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list); 819 820 821 void 822 SetFileSpecAndObjectName (const FileSpec &file, 823 const ConstString &object_name); 824 825 bool GetIsDynamicLinkEditor()826 GetIsDynamicLinkEditor () const 827 { 828 return m_is_dynamic_loader_module; 829 } 830 831 void SetIsDynamicLinkEditor(bool b)832 SetIsDynamicLinkEditor (bool b) 833 { 834 m_is_dynamic_loader_module = b; 835 } 836 837 ClangASTContext & 838 GetClangASTContext (); 839 840 // Special error functions that can do printf style formatting that will prepend the message with 841 // something appropriate for this module (like the architecture, path and object name (if any)). 842 // This centralizes code so that everyone doesn't need to format their error and log messages on 843 // their own and keeps the output a bit more consistent. 844 void 845 LogMessage (Log *log, const char *format, ...) __attribute__ ((format (printf, 3, 4))); 846 847 void 848 LogMessageVerboseBacktrace (Log *log, const char *format, ...) __attribute__ ((format (printf, 3, 4))); 849 850 void 851 ReportWarning (const char *format, ...) __attribute__ ((format (printf, 2, 3))); 852 853 void 854 ReportError (const char *format, ...) __attribute__ ((format (printf, 2, 3))); 855 856 // Only report an error once when the module is first detected to be modified 857 // so we don't spam the console with many messages. 858 void 859 ReportErrorIfModifyDetected (const char *format, ...) __attribute__ ((format (printf, 2, 3))); 860 861 //------------------------------------------------------------------ 862 // Return true if the file backing this module has changed since the 863 // module was originally created since we saved the intial file 864 // modification time when the module first gets created. 865 //------------------------------------------------------------------ 866 bool 867 FileHasChanged () const; 868 869 //------------------------------------------------------------------ 870 // SymbolVendor, SymbolFile and ObjectFile member objects should 871 // lock the module mutex to avoid deadlocks. 872 //------------------------------------------------------------------ 873 Mutex & GetMutex()874 GetMutex () const 875 { 876 return m_mutex; 877 } 878 879 PathMappingList & GetSourceMappingList()880 GetSourceMappingList () 881 { 882 return m_source_mappings; 883 } 884 885 const PathMappingList & GetSourceMappingList()886 GetSourceMappingList () const 887 { 888 return m_source_mappings; 889 } 890 891 //------------------------------------------------------------------ 892 /// Finds a source file given a file spec using the module source 893 /// path remappings (if any). 894 /// 895 /// Tries to resolve \a orig_spec by checking the module source path 896 /// remappings. It makes sure the file exists, so this call can be 897 /// expensive if the remappings are on a network file system, so 898 /// use this function sparingly (not in a tight debug info parsing 899 /// loop). 900 /// 901 /// @param[in] orig_spec 902 /// The original source file path to try and remap. 903 /// 904 /// @param[out] new_spec 905 /// The newly remapped filespec that is guaranteed to exist. 906 /// 907 /// @return 908 /// /b true if \a orig_spec was successfully located and 909 /// \a new_spec is filled in with an existing file spec, 910 /// \b false otherwise. 911 //------------------------------------------------------------------ 912 bool 913 FindSourceFile (const FileSpec &orig_spec, FileSpec &new_spec) const; 914 915 //------------------------------------------------------------------ 916 /// Remaps a source file given \a path into \a new_path. 917 /// 918 /// Remaps \a path if any source remappings match. This function 919 /// does NOT stat the file system so it can be used in tight loops 920 /// where debug info is being parsed. 921 /// 922 /// @param[in] path 923 /// The original source file path to try and remap. 924 /// 925 /// @param[out] new_path 926 /// The newly remapped filespec that is may or may not exist. 927 /// 928 /// @return 929 /// /b true if \a path was successfully located and \a new_path 930 /// is filled in with a new source path, \b false otherwise. 931 //------------------------------------------------------------------ 932 bool 933 RemapSourceFile (const char *path, std::string &new_path) const; 934 935 936 //------------------------------------------------------------------ 937 /// Prepare to do a function name lookup. 938 /// 939 /// Looking up functions by name can be a tricky thing. LLDB requires 940 /// that accelerator tables contain full names for functions as well 941 /// as function basenames which include functions, class methods and 942 /// class functions. When the user requests that an action use a 943 /// function by name, we are sometimes asked to automatically figure 944 /// out what a name could possibly map to. A user might request a 945 /// breakpoint be set on "count". If no options are supplied to limit 946 /// the scope of where to search for count, we will by default match 947 /// any function names named "count", all class and instance methods 948 /// named "count" (no matter what the namespace or contained context) 949 /// and any selectors named "count". If a user specifies "a::b" we 950 /// will search for the basename "b", and then prune the results that 951 /// don't match "a::b" (note that "c::a::b" and "d::e::a::b" will 952 /// match a query of "a::b". 953 /// 954 /// @param[in] name 955 /// The user supplied name to use in the lookup 956 /// 957 /// @param[in] name_type_mask 958 /// The mask of bits from lldb::FunctionNameType enumerations 959 /// that tell us what kind of name we are looking for. 960 /// 961 /// @param[out] lookup_name 962 /// The actual name that will be used when calling 963 /// SymbolVendor::FindFunctions() or Symtab::FindFunctionSymbols() 964 /// 965 /// @param[out] lookup_name_type_mask 966 /// The actual name mask that should be used in the calls to 967 /// SymbolVendor::FindFunctions() or Symtab::FindFunctionSymbols() 968 /// 969 /// @param[out] match_name_after_lookup 970 /// A boolean that indicates if we need to iterate through any 971 /// match results obtained from SymbolVendor::FindFunctions() or 972 /// Symtab::FindFunctionSymbols() to see if the name contains 973 /// \a name. For example if \a name is "a::b", this function will 974 /// return a \a lookup_name of "b", with \a match_name_after_lookup 975 /// set to true to indicate any matches will need to be checked 976 /// to make sure they contain \a name. 977 //------------------------------------------------------------------ 978 static void 979 PrepareForFunctionNameLookup (const ConstString &name, 980 uint32_t name_type_mask, 981 ConstString &lookup_name, 982 uint32_t &lookup_name_type_mask, 983 bool &match_name_after_lookup); 984 985 protected: 986 //------------------------------------------------------------------ 987 // Member Variables 988 //------------------------------------------------------------------ 989 mutable Mutex m_mutex; ///< A mutex to keep this object happy in multi-threaded environments. 990 TimeValue m_mod_time; ///< The modification time for this module when it was created. 991 ArchSpec m_arch; ///< The architecture for this module. 992 lldb_private::UUID m_uuid; ///< Each module is assumed to have a unique identifier to help match it up to debug symbols. 993 FileSpec m_file; ///< The file representation on disk for this module (if there is one). 994 FileSpec m_platform_file;///< The path to the module on the platform on which it is being debugged 995 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 996 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. 997 uint64_t m_object_offset; 998 TimeValue m_object_mod_time; 999 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 1000 std::unique_ptr<SymbolVendor> m_symfile_ap; ///< A pointer to the symbol vendor for this module. 1001 ClangASTContext m_ast; ///< The AST context for this module. 1002 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 1003 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 1004 1005 bool m_did_load_objfile:1, 1006 m_did_load_symbol_vendor:1, 1007 m_did_parse_uuid:1, 1008 m_did_init_ast:1, 1009 m_is_dynamic_loader_module:1; 1010 mutable bool m_file_has_changed:1, 1011 m_first_file_changed_log:1; /// See if the module was modified after it was initially opened. 1012 1013 //------------------------------------------------------------------ 1014 /// Resolve a file or load virtual address. 1015 /// 1016 /// Tries to resolve \a vm_addr as a file address (if \a 1017 /// vm_addr_is_file_addr is true) or as a load address if \a 1018 /// vm_addr_is_file_addr is false) in the symbol vendor. 1019 /// \a resolve_scope indicates what clients wish to resolve 1020 /// and can be used to limit the scope of what is parsed. 1021 /// 1022 /// @param[in] vm_addr 1023 /// The load virtual address to resolve. 1024 /// 1025 /// @param[in] vm_addr_is_file_addr 1026 /// If \b true, \a vm_addr is a file address, else \a vm_addr 1027 /// if a load address. 1028 /// 1029 /// @param[in] resolve_scope 1030 /// The scope that should be resolved (see 1031 /// SymbolContext::Scope). 1032 /// 1033 /// @param[out] so_addr 1034 /// The section offset based address that got resolved if 1035 /// any bits are returned. 1036 /// 1037 /// @param[out] sc 1038 // The symbol context that has objects filled in. Each bit 1039 /// in the \a resolve_scope pertains to a member in the \a sc. 1040 /// 1041 /// @return 1042 /// A integer that contains SymbolContext::Scope bits set for 1043 /// each item that was successfully resolved. 1044 /// 1045 /// @see SymbolContext::Scope 1046 //------------------------------------------------------------------ 1047 uint32_t 1048 ResolveSymbolContextForAddress (lldb::addr_t vm_addr, 1049 bool vm_addr_is_file_addr, 1050 uint32_t resolve_scope, 1051 Address& so_addr, 1052 SymbolContext& sc); 1053 1054 void 1055 SymbolIndicesToSymbolContextList (Symtab *symtab, 1056 std::vector<uint32_t> &symbol_indexes, 1057 SymbolContextList &sc_list); 1058 1059 bool 1060 SetArchitecture (const ArchSpec &new_arch); 1061 1062 SectionList * 1063 GetUnifiedSectionList(); 1064 1065 friend class ModuleList; 1066 friend class ObjectFile; 1067 friend class SymbolFile; 1068 1069 private: 1070 1071 size_t 1072 FindTypes_Impl (const SymbolContext& sc, 1073 const ConstString &name, 1074 const ClangNamespaceDecl *namespace_decl, 1075 bool append, 1076 size_t max_matches, 1077 TypeList& types); 1078 1079 1080 DISALLOW_COPY_AND_ASSIGN (Module); 1081 }; 1082 1083 } // namespace lldb_private 1084 1085 #endif // liblldb_Module_h_ 1086