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