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