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