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