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