1 //===-- Module.h ------------------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef LLDB_CORE_MODULE_H
10 #define LLDB_CORE_MODULE_H
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"
31 #include "llvm/ADT/DenseSet.h"
32 #include "llvm/ADT/StringRef.h"
33 #include "llvm/Support/Chrono.h"
43 namespace lldb_private {
44 class CompilerDeclContext;
48 class RegularExpression;
53 class SymbolContextList;
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;
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.
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.
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.
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 {
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();
96 static Module *GetAllocatedModuleAtIndex(size_t idx);
98 static std::recursive_mutex &GetAllocationModuleCollectionMutex();
100 /// Construct with file specification and architecture.
102 /// Clients that wish to share modules with other targets should use
103 /// ModuleList::GetSharedModule().
105 /// \param[in] file_spec
106 /// The file specification for the on disk representation of
107 /// this executable image.
110 /// The architecture to set as the current architecture in
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
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).
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<>());
128 Module(const ModuleSpec &module_spec);
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);
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();
146 module_sp->m_arch = arch;
148 // Also copy the object file's FileSpec.
149 module_sp->m_file = module_sp->m_objfile_sp->GetFileSpec();
156 bool MatchesModuleSpec(const ModuleSpec &module_ref);
158 /// Set the load address for all sections in a module to be the file address
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 +
166 /// \param[in] target
167 /// The target in which to apply the section load addresses.
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.
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.
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
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,
197 /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
199 /// \see SymbolContextScope
200 void CalculateSymbolContext(SymbolContext *sc) override;
202 lldb::ModuleSP CalculateSymbolContextModule() override;
205 GetDescription(llvm::raw_ostream &s,
206 lldb::DescriptionLevel level = lldb::eDescriptionLevelFull);
208 /// Get the module path and object name.
210 /// Modules can refer to object files. In this case the specification is
211 /// simple and would return the path to the file:
213 /// "/usr/lib/foo.dylib"
215 /// Modules can be .o files inside of a BSD archive (.a file). In this case,
216 /// the object specification will look like:
218 /// "/usr/lib/foo.a(bar.o)"
220 /// There are many places where logging wants to log this fully qualified
221 /// specification, so we centralize this functionality here.
224 /// The object path + object name if there is one.
225 std::string GetSpecificationDescription() const;
227 /// Dump a description of this object to a Stream.
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.
235 /// The stream to which to dump the object description.
236 void Dump(Stream *s);
238 /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
240 /// \see SymbolContextScope
241 void DumpSymbolContext(Stream *s) override;
243 /// Find a symbol in the object file's symbol table.
246 /// The name of the symbol that we are looking for.
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.
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);
260 void FindSymbolsWithNameAndType(ConstString name,
261 lldb::SymbolType symbol_type,
262 SymbolContextList &sc_list);
264 void FindSymbolsMatchingRegExAndType(const RegularExpression ®ex,
265 lldb::SymbolType symbol_type,
266 SymbolContextList &sc_list);
268 /// Find a function symbols in the object file's symbol table.
271 /// The name of the symbol that we are looking for.
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.
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);
283 /// Find compile units by partial or full path.
285 /// Finds all compile units that match \a path in all of the modules and
286 /// returns the results in \a sc_list.
289 /// The name of the function we are looking for.
291 /// \param[out] sc_list
292 /// A symbol context list that gets filled in with all of the
294 void FindCompileUnits(const FileSpec &path, SymbolContextList &sc_list);
296 /// Find functions by name.
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.
303 /// The name of the function we are looking for.
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.
311 /// \param[out] sc_list
312 /// A symbol context list that gets filled in with all of the
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);
320 /// Find functions by name.
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.
327 /// A regular expression to use when matching the name.
329 /// \param[out] sc_list
330 /// A symbol context list that gets filled in with all of the
332 void FindFunctions(const RegularExpression ®ex,
333 const ModuleFunctionSearchOptions &options,
334 SymbolContextList &sc_list);
336 /// Find addresses by file/line
338 /// \param[in] target_sp
339 /// The target the addresses are desired for.
342 /// Source file to locate.
345 /// Source line to locate.
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'
352 /// \param[out] output_local
353 /// All matching addresses within 'function'
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,
360 std::vector<Address> &output_local,
361 std::vector<Address> &output_extern);
363 /// Find global and static variables by name.
366 /// The name of the global or static variable we are looking
369 /// \param[in] parent_decl_ctx
370 /// If valid, a decl context that results must exist within
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.
376 /// \param[in] variable_list
377 /// A list of variables that gets the matches appended to.
379 void FindGlobalVariables(ConstString name,
380 const CompilerDeclContext &parent_decl_ctx,
381 size_t max_matches, VariableList &variable_list);
383 /// Find global and static variables by regular expression.
386 /// A regular expression to use when matching the name.
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.
392 /// \param[in] variable_list
393 /// A list of variables that gets the matches appended to.
395 void FindGlobalVariables(const RegularExpression ®ex, size_t max_matches,
396 VariableList &variable_list);
398 /// Find types by name.
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.
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.
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
425 /// \param[out] types
426 /// A type list gets populated with any matches.
429 FindTypes(ConstString type_name, bool exact_match, size_t max_matches,
430 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
433 /// Find types by name.
435 /// This behaves like the other FindTypes method but allows to
436 /// specify a DeclContext and a language for the type being searched
439 /// \param searched_symbol_files
440 /// Prevents one file from being visited multiple times.
442 FindTypes(llvm::ArrayRef<CompilerContext> pattern, LanguageSet languages,
443 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
446 lldb::TypeSP FindFirstType(const SymbolContext &sc, ConstString type_name,
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
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).
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);
463 /// Get const accessor for the module architecture.
466 /// A const reference to the architecture object.
467 const ArchSpec &GetArchitecture() const;
469 /// Get const accessor for the module file specification.
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.
476 /// A const reference to the file specification object.
477 const FileSpec &GetFileSpec() const { return m_file; }
479 /// Get accessor for the module platform file specification.
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.
490 /// A const reference to the file specification object.
491 const FileSpec &GetPlatformFileSpec() const {
493 return m_platform_file;
497 void SetPlatformFileSpec(const FileSpec &file) { m_platform_file = file; }
499 const FileSpec &GetRemoteInstallFileSpec() const {
500 return m_remote_install_file;
503 void SetRemoteInstallFileSpec(const FileSpec &file) {
504 m_remote_install_file = file;
507 const FileSpec &GetSymbolFileFileSpec() const { return m_symfile_spec; }
509 void PreloadSymbols();
511 void SetSymbolFileFileSpec(const FileSpec &file);
513 const llvm::sys::TimePoint<> &GetModificationTime() const {
517 const llvm::sys::TimePoint<> &GetObjectModificationTime() const {
518 return m_object_mod_time;
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);
526 /// Tells whether this module is capable of being the main executable for a
530 /// \b true if it is, \b false otherwise.
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.
537 /// \param[in] target
538 /// The target to check whether this is loaded in.
541 /// \b true if it is, \b false otherwise.
542 bool IsLoadedInTarget(Target *target);
544 bool LoadScriptingResourceInTarget(Target *target, Status &error,
545 Stream *feedback_stream = nullptr);
547 /// Get the number of compile units for this module.
550 /// The number of compile units that the symbol vendor plug-in
552 size_t GetNumCompileUnits();
554 lldb::CompUnitSP GetCompileUnitAtIndex(size_t idx);
556 ConstString GetObjectName() const;
558 uint64_t GetObjectOffset() const { return m_object_offset; }
560 /// Get the object file representation for the current architecture.
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.
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();
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.
578 /// If the symbol vendor has not been loaded yet, this function will return
579 /// the section list for the object file.
582 /// Unified module section list.
583 virtual SectionList *GetSectionList();
585 /// Notify the module that the file addresses for the Sections have been
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
592 virtual void SectionFileAddressesChanged();
594 /// Returns a reference to the UnwindTable for this Module
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.
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();
607 llvm::VersionTuple GetVersion();
609 /// Load an object file from memory.
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.
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);
624 /// Get the module's symbol file
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);
637 /// Get a reference to the UUID value contained in this object.
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.
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
647 const lldb_private::UUID &GetUUID();
649 /// A debugging function that will cause everything in a module to
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();
661 bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr);
663 /// Resolve the symbol context for the given address.
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.
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.
676 /// \param[in] so_addr
677 /// A load address to resolve.
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.
689 /// The SymbolContext that is modified based on symbol resolution.
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.
697 /// The scope that has been resolved (see SymbolContext::Scope).
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);
704 /// Resolve items in the symbol context for a given file and line.
706 /// Tries to resolve \a file_path and \a line to a list of matching symbol
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.
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.
722 /// The source line to match, or zero if just the compile unit
723 /// should be resolved.
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.
731 /// \param[in] resolve_scope
732 /// The scope that should be resolved (see
733 /// SymbolContext::Scope).
735 /// \param[out] sc_list
736 /// A symbol context list that gets matching symbols contexts
740 /// The number of matches that were added to \a sc_list.
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);
747 /// Resolve items in the symbol context for a given file and line.
749 /// Tries to resolve \a file_spec and \a line to a list of matching symbol
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.
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.
765 /// The source line to match, or zero if just the compile unit
766 /// should be resolved.
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.
774 /// \param[in] resolve_scope
775 /// The scope that should be resolved (see
776 /// SymbolContext::Scope).
778 /// \param[out] sc_list
779 /// A symbol context list that gets filled in with all of the
783 /// A integer that contains SymbolContext::Scope bits set for
784 /// each item that was successfully resolved.
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);
791 void SetFileSpecAndObjectName(const FileSpec &file, ConstString object_name);
793 bool GetIsDynamicLinkEditor();
795 llvm::Expected<TypeSystem &>
796 GetTypeSystemForLanguage(lldb::LanguageType language);
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)));
806 void LogMessageVerboseBacktrace(Log *log, const char *format, ...)
807 __attribute__((format(printf, 3, 4)));
809 void ReportWarning(const char *format, ...)
810 __attribute__((format(printf, 2, 3)));
812 void ReportError(const char *format, ...)
813 __attribute__((format(printf, 2, 3)));
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)));
820 void ReportWarningOptimization(llvm::Optional<lldb::user_id_t> debugger_id);
823 ReportWarningUnsupportedLanguage(lldb::LanguageType language,
824 llvm::Optional<lldb::user_id_t> debugger_id);
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;
831 // SymbolFile and ObjectFile member objects should lock the
832 // module mutex to avoid deadlocks.
833 std::recursive_mutex &GetMutex() const { return m_mutex; }
835 PathMappingList &GetSourceMappingList() { return m_source_mappings; }
837 const PathMappingList &GetSourceMappingList() const {
838 return m_source_mappings;
841 /// Finds a source file given a file spec using the module source path
842 /// remappings (if any).
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).
849 /// \param[in] orig_spec
850 /// The original source file path to try and remap.
852 /// \param[out] new_spec
853 /// The newly remapped filespec that is guaranteed to exist.
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;
861 /// Remaps a source file given \a path into \a new_path.
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
868 /// The original source file path to try and remap.
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;
876 /// Update the ArchSpec to a more specific variant.
877 bool MergeArchitecture(const ArchSpec &arch_spec);
879 /// Accessor for the symbol table parse time metric.
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; }
885 /// Accessor for the symbol table index time metric.
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; }
891 /// \class LookupInfo Module.h "lldb/Core/Module.h"
892 /// A class that encapsulates name lookup information.
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.
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.
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
914 LookupInfo() = default;
916 LookupInfo(ConstString name, lldb::FunctionNameType name_type_mask,
917 lldb::LanguageType language);
919 ConstString GetName() const { return m_name; }
921 void SetName(ConstString name) { m_name = name; }
923 ConstString GetLookupName() const { return m_lookup_name; }
925 void SetLookupName(ConstString name) { m_lookup_name = name; }
927 lldb::FunctionNameType GetNameTypeMask() const { return m_name_type_mask; }
929 void SetNameTypeMask(lldb::FunctionNameType mask) {
930 m_name_type_mask = mask;
933 void Prune(SymbolContextList &sc_list, size_t start_idx) const;
936 /// What the user originally typed
939 /// The actual name will lookup when calling in the object or symbol file
940 ConstString m_lookup_name;
942 /// Limit matches to only be for this language
943 lldb::LanguageType m_language = lldb::eLanguageTypeUnknown;
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;
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;
954 /// Get a unique hash for this module.
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
970 /// Get a unique cache key for the current module.
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();
980 /// Get the global index file cache.
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.
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();
993 mutable std::recursive_mutex m_mutex; ///< A mutex to keep this object happy
994 /// in multi-threaded environments.
996 /// The modification time for this module when it was created.
997 llvm::sys::TimePoint<> m_mod_time;
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
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
1012 ConstString m_object_name; ///< The name an object within this module that is
1013 /// selected, or empty of the module is represented
1015 uint64_t m_object_offset = 0;
1016 llvm::sys::TimePoint<> m_object_mod_time;
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;
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();
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
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;
1062 std::once_flag m_optimization_warning;
1063 std::once_flag m_language_warning;
1065 /// Resolve a file or load virtual address.
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.
1073 /// \param[in] vm_addr
1074 /// The load virtual address to resolve.
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.
1080 /// \param[in] resolve_scope
1081 /// The scope that should be resolved (see
1082 /// SymbolContext::Scope).
1084 /// \param[out] so_addr
1085 /// The section offset based address that got resolved if
1086 /// any bits are returned.
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.
1093 /// A integer that contains SymbolContext::Scope bits set for
1094 /// each item that was successfully resolved.
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);
1102 void SymbolIndicesToSymbolContextList(Symtab *symtab,
1103 std::vector<uint32_t> &symbol_indexes,
1104 SymbolContextList &sc_list);
1106 bool SetArchitecture(const ArchSpec &new_arch);
1108 void SetUUID(const lldb_private::UUID &uuid);
1110 SectionList *GetUnifiedSectionList();
1112 friend class ModuleList;
1113 friend class ObjectFile;
1114 friend class SymbolFile;
1117 Module(); // Only used internally by CreateJITModule ()
1119 void FindTypes_Impl(
1120 ConstString name, const CompilerDeclContext &parent_decl_ctx,
1122 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
1125 Module(const Module &) = delete;
1126 const Module &operator=(const Module &) = delete;
1129 } // namespace lldb_private
1131 #endif // LLDB_CORE_MODULE_H