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 liblldb_Module_h_
10 #define liblldb_Module_h_
12 #include "lldb/Core/Address.h"
13 #include "lldb/Core/ModuleSpec.h"
14 #include "lldb/Symbol/ObjectFile.h"
15 #include "lldb/Symbol/SymbolContextScope.h"
16 #include "lldb/Symbol/TypeSystem.h"
17 #include "lldb/Target/PathMappingList.h"
18 #include "lldb/Utility/ArchSpec.h"
19 #include "lldb/Utility/ConstString.h"
20 #include "lldb/Utility/FileSpec.h"
21 #include "lldb/Utility/Status.h"
22 #include "lldb/Utility/UUID.h"
23 #include "lldb/lldb-defines.h"
24 #include "lldb/lldb-enumerations.h"
25 #include "lldb/lldb-forward.h"
26 #include "lldb/lldb-types.h"
28 #include "llvm/ADT/DenseSet.h"
29 #include "llvm/ADT/StringRef.h"
30 #include "llvm/Support/Chrono.h"
40 namespace lldb_private {
41 class CompilerDeclContext;
45 class RegularExpression;
50 class SymbolContextList;
59 /// \class Module Module.h "lldb/Core/Module.h"
60 /// A class that describes an executable image and its associated
61 /// object and symbol files.
63 /// The module is designed to be able to select a single slice of an
64 /// executable image as it would appear on disk and during program execution.
66 /// Modules control when and if information is parsed according to which
67 /// accessors are called. For example the object file (ObjectFile)
68 /// representation will only be parsed if the object file is requested using
69 /// the Module::GetObjectFile() is called. The debug symbols will only be
70 /// parsed if the symbol vendor (SymbolVendor) is requested using the
71 /// Module::GetSymbolVendor() is called.
73 /// The module will parse more detailed information as more queries are made.
74 class Module : public std::enable_shared_from_this<Module>,
75 public SymbolContextScope {
77 // Static functions that can track the lifetime of module objects. This is
78 // handy because we might have Module objects that are in shared pointers
79 // that aren't in the global module list (from ModuleList). If this is the
80 // case we need to know about it. The modules in the global list maintained
81 // by these functions can be viewed using the "target modules list" command
82 // using the "--global" (-g for short).
83 static size_t GetNumberAllocatedModules();
85 static Module *GetAllocatedModuleAtIndex(size_t idx);
87 static std::recursive_mutex &GetAllocationModuleCollectionMutex();
89 /// Construct with file specification and architecture.
91 /// Clients that wish to share modules with other targets should use
92 /// ModuleList::GetSharedModule().
94 /// \param[in] file_spec
95 /// The file specification for the on disk representation of
96 /// this executable image.
99 /// The architecture to set as the current architecture in
102 /// \param[in] object_name
103 /// The name of an object in a module used to extract a module
104 /// within a module (.a files and modules that contain multiple
107 /// \param[in] object_offset
108 /// The offset within an existing module used to extract a
109 /// module within a module (.a files and modules that contain
110 /// multiple architectures).
112 const FileSpec &file_spec, const ArchSpec &arch,
113 const ConstString *object_name = nullptr,
114 lldb::offset_t object_offset = 0,
115 const llvm::sys::TimePoint<> &object_mod_time = llvm::sys::TimePoint<>());
117 Module(const ModuleSpec &module_spec);
119 template <typename ObjFilePlugin, typename... Args>
120 static lldb::ModuleSP CreateModuleFromObjectFile(Args &&... args) {
121 // Must create a module and place it into a shared pointer before we can
122 // create an object file since it has a std::weak_ptr back to the module,
123 // so we need to control the creation carefully in this static function
124 lldb::ModuleSP module_sp(new Module());
125 module_sp->m_objfile_sp =
126 std::make_shared<ObjFilePlugin>(module_sp, std::forward<Args>(args)...);
127 module_sp->m_did_load_objfile.store(true, std::memory_order_relaxed);
129 // Once we get the object file, set module ArchSpec to the one we get from
130 // the object file. If the object file does not have an architecture, we
131 // consider the creation a failure.
132 ArchSpec arch = module_sp->m_objfile_sp->GetArchitecture();
135 module_sp->m_arch = arch;
137 // Also copy the object file's FileSpec.
138 module_sp->m_file = module_sp->m_objfile_sp->GetFileSpec();
145 bool MatchesModuleSpec(const ModuleSpec &module_ref);
147 /// Set the load address for all sections in a module to be the file address
150 /// Many times a module will be loaded in a target with a constant offset
151 /// applied to all top level sections. This function can set the load
152 /// address for all top level sections to be the section file address +
155 /// \param[in] target
156 /// The target in which to apply the section load addresses.
159 /// if \a value_is_offset is true, then value is the offset to
160 /// apply to all file addresses for all top level sections in
161 /// the object file as each section load address is being set.
162 /// If \a value_is_offset is false, then "value" is the new
163 /// absolute base address for the image.
165 /// \param[in] value_is_offset
166 /// If \b true, then \a value is an offset to apply to each
167 /// file address of each top level section.
168 /// If \b false, then \a value is the image base address that
169 /// will be used to rigidly slide all loadable sections.
171 /// \param[out] changed
172 /// If any section load addresses were changed in \a target,
173 /// then \a changed will be set to \b true. Else \a changed
174 /// will be set to false. This allows this function to be
175 /// called multiple times on the same module for the same
176 /// target. If the module hasn't moved, then \a changed will
177 /// be false and no module updated notification will need to
181 /// /b True if any sections were successfully loaded in \a target,
182 /// /b false otherwise.
183 bool SetLoadAddress(Target &target, lldb::addr_t value, bool value_is_offset,
186 /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
188 /// \see SymbolContextScope
189 void CalculateSymbolContext(SymbolContext *sc) override;
191 lldb::ModuleSP CalculateSymbolContextModule() override;
194 GetDescription(Stream *s,
195 lldb::DescriptionLevel level = lldb::eDescriptionLevelFull);
197 /// Get the module path and object name.
199 /// Modules can refer to object files. In this case the specification is
200 /// simple and would return the path to the file:
202 /// "/usr/lib/foo.dylib"
204 /// Modules can be .o files inside of a BSD archive (.a file). In this case,
205 /// the object specification will look like:
207 /// "/usr/lib/foo.a(bar.o)"
209 /// There are many places where logging wants to log this fully qualified
210 /// specification, so we centralize this functionality here.
213 /// The object path + object name if there is one.
214 std::string GetSpecificationDescription() const;
216 /// Dump a description of this object to a Stream.
218 /// Dump a description of the contents of this object to the supplied stream
219 /// \a s. The dumped content will be only what has been loaded or parsed up
220 /// to this point at which this function is called, so this is a good way to
221 /// see what has been parsed in a module.
224 /// The stream to which to dump the object description.
225 void Dump(Stream *s);
227 /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
229 /// \see SymbolContextScope
230 void DumpSymbolContext(Stream *s) override;
232 /// Find a symbol in the object file's symbol table.
235 /// The name of the symbol that we are looking for.
237 /// \param[in] symbol_type
238 /// If set to eSymbolTypeAny, find a symbol of any type that
239 /// has a name that matches \a name. If set to any other valid
240 /// SymbolType enumeration value, then search only for
241 /// symbols that match \a symbol_type.
244 /// Returns a valid symbol pointer if a symbol was found,
245 /// nullptr otherwise.
246 const Symbol *FindFirstSymbolWithNameAndType(
248 lldb::SymbolType symbol_type = lldb::eSymbolTypeAny);
250 size_t FindSymbolsWithNameAndType(ConstString name,
251 lldb::SymbolType symbol_type,
252 SymbolContextList &sc_list);
254 size_t FindSymbolsMatchingRegExAndType(const RegularExpression ®ex,
255 lldb::SymbolType symbol_type,
256 SymbolContextList &sc_list);
258 /// Find a function symbols in the object file's symbol table.
261 /// The name of the symbol that we are looking for.
263 /// \param[in] name_type_mask
264 /// A mask that has one or more bitwise OR'ed values from the
265 /// lldb::FunctionNameType enumeration type that indicate what
266 /// kind of names we are looking for.
268 /// \param[out] sc_list
269 /// A list to append any matching symbol contexts to.
272 /// The number of symbol contexts that were added to \a sc_list
273 size_t FindFunctionSymbols(ConstString name, uint32_t name_type_mask,
274 SymbolContextList &sc_list);
276 /// Find compile units by partial or full path.
278 /// Finds all compile units that match \a path in all of the modules and
279 /// returns the results in \a sc_list.
282 /// The name of the function we are looking for.
284 /// \param[in] append
285 /// If \b true, then append any compile units that were found
286 /// to \a sc_list. If \b false, then the \a sc_list is cleared
287 /// and the contents of \a sc_list are replaced.
289 /// \param[out] sc_list
290 /// A symbol context list that gets filled in with all of the
294 /// The number of matches added to \a sc_list.
295 size_t FindCompileUnits(const FileSpec &path, bool append,
296 SymbolContextList &sc_list);
298 /// Find functions by name.
300 /// If the function is an inlined function, it will have a block,
301 /// representing the inlined function, and the function will be the
302 /// containing function. If it is not inlined, then the block will be NULL.
305 /// The name of the compile unit we are looking for.
307 /// \param[in] namespace_decl
308 /// If valid, a namespace to search in.
310 /// \param[in] name_type_mask
311 /// A bit mask of bits that indicate what kind of names should
312 /// be used when doing the lookup. Bits include fully qualified
313 /// names, base names, C++ methods, or ObjC selectors.
314 /// See FunctionNameType for more details.
316 /// \param[in] append
317 /// If \b true, any matches will be appended to \a sc_list, else
318 /// matches replace the contents of \a sc_list.
320 /// \param[out] sc_list
321 /// A symbol context list that gets filled in with all of the
325 /// The number of matches added to \a sc_list.
326 size_t FindFunctions(ConstString name,
327 const CompilerDeclContext *parent_decl_ctx,
328 lldb::FunctionNameType name_type_mask, bool symbols_ok,
329 bool inlines_ok, bool append,
330 SymbolContextList &sc_list);
332 /// Find functions by name.
334 /// If the function is an inlined function, it will have a block,
335 /// representing the inlined function, and the function will be the
336 /// containing function. If it is not inlined, then the block will be NULL.
339 /// A regular expression to use when matching the name.
341 /// \param[in] append
342 /// If \b true, any matches will be appended to \a sc_list, else
343 /// matches replace the contents of \a sc_list.
345 /// \param[out] sc_list
346 /// A symbol context list that gets filled in with all of the
350 /// The number of matches added to \a sc_list.
351 size_t FindFunctions(const RegularExpression ®ex, bool symbols_ok,
352 bool inlines_ok, bool append,
353 SymbolContextList &sc_list);
355 /// Find addresses by file/line
357 /// \param[in] target_sp
358 /// The target the addresses are desired for.
361 /// Source file to locate.
364 /// Source line to locate.
366 /// \param[in] function
367 /// Optional filter function. Addresses within this function will be
368 /// added to the 'local' list. All others will be added to the 'extern'
371 /// \param[out] output_local
372 /// All matching addresses within 'function'
374 /// \param[out] output_extern
375 /// All matching addresses not within 'function'
376 void FindAddressesForLine(const lldb::TargetSP target_sp,
377 const FileSpec &file, uint32_t line,
379 std::vector<Address> &output_local,
380 std::vector<Address> &output_extern);
382 /// Find global and static variables by name.
385 /// The name of the global or static variable we are looking
388 /// \param[in] parent_decl_ctx
389 /// If valid, a decl context that results must exist within
391 /// \param[in] max_matches
392 /// Allow the number of matches to be limited to \a
393 /// max_matches. Specify UINT32_MAX to get all possible matches.
395 /// \param[in] variable_list
396 /// A list of variables that gets the matches appended to.
399 /// The number of matches added to \a variable_list.
400 size_t FindGlobalVariables(ConstString name,
401 const CompilerDeclContext *parent_decl_ctx,
402 size_t max_matches, VariableList &variable_list);
404 /// Find global and static variables by regular expression.
407 /// A regular expression to use when matching the name.
409 /// \param[in] max_matches
410 /// Allow the number of matches to be limited to \a
411 /// max_matches. Specify UINT32_MAX to get all possible matches.
413 /// \param[in] variable_list
414 /// A list of variables that gets the matches appended to.
417 /// The number of matches added to \a variable_list.
418 size_t FindGlobalVariables(const RegularExpression ®ex, size_t max_matches,
419 VariableList &variable_list);
421 /// Find types by name.
423 /// Type lookups in modules go through the SymbolVendor (which will use one
424 /// or more SymbolFile subclasses). The SymbolFile needs to be able to
425 /// lookup types by basename and not the fully qualified typename. This
426 /// allows the type accelerator tables to stay small, even with heavily
427 /// templatized C++. The type search will then narrow down the search
428 /// results. If "exact_match" is true, then the type search will only match
429 /// exact type name matches. If "exact_match" is false, the type will match
430 /// as long as the base typename matches and as long as any immediate
431 /// containing namespaces/class scopes that are specified match. So to
432 /// search for a type "d" in "b::c", the name "b::c::d" can be specified and
433 /// it will match any class/namespace "b" which contains a class/namespace
434 /// "c" which contains type "d". We do this to allow users to not always
435 /// have to specify complete scoping on all expressions, but it also allows
436 /// for exact matching when required.
438 /// \param[in] type_name
439 /// The name of the type we are looking for that is a fully
440 /// or partially qualified type name.
442 /// \param[in] exact_match
443 /// If \b true, \a type_name is fully qualified and must match
444 /// exactly. If \b false, \a type_name is a partially qualified
445 /// name where the leading namespaces or classes can be
446 /// omitted to make finding types that a user may type
449 /// \param[out] type_list
450 /// A type list gets populated with any matches.
453 /// The number of matches added to \a type_list.
455 FindTypes(ConstString type_name, bool exact_match, size_t max_matches,
456 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
459 lldb::TypeSP FindFirstType(const SymbolContext &sc,
460 ConstString type_name, bool exact_match);
462 /// Find types by name that are in a namespace. This function is used by the
463 /// expression parser when searches need to happen in an exact namespace
466 /// \param[in] type_name
467 /// The name of a type within a namespace that should not include
468 /// any qualifying namespaces (just a type basename).
470 /// \param[in] namespace_decl
471 /// The namespace declaration that this type must exist in.
473 /// \param[out] type_list
474 /// A type list gets populated with any matches.
477 /// The number of matches added to \a type_list.
478 size_t FindTypesInNamespace(ConstString type_name,
479 const CompilerDeclContext *parent_decl_ctx,
480 size_t max_matches, TypeList &type_list);
482 /// Get const accessor for the module architecture.
485 /// A const reference to the architecture object.
486 const ArchSpec &GetArchitecture() const;
488 /// Get const accessor for the module file specification.
490 /// This function returns the file for the module on the host system that is
491 /// running LLDB. This can differ from the path on the platform since we
492 /// might be doing remote debugging.
495 /// A const reference to the file specification object.
496 const FileSpec &GetFileSpec() const { return m_file; }
498 /// Get accessor for the module platform file specification.
500 /// Platform file refers to the path of the module as it is known on the
501 /// remote system on which it is being debugged. For local debugging this is
502 /// always the same as Module::GetFileSpec(). But remote debugging might
503 /// mention a file "/usr/lib/liba.dylib" which might be locally downloaded
504 /// and cached. In this case the platform file could be something like:
505 /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" The
506 /// file could also be cached in a local developer kit directory.
509 /// A const reference to the file specification object.
510 const FileSpec &GetPlatformFileSpec() const {
512 return m_platform_file;
516 void SetPlatformFileSpec(const FileSpec &file) { m_platform_file = file; }
518 const FileSpec &GetRemoteInstallFileSpec() const {
519 return m_remote_install_file;
522 void SetRemoteInstallFileSpec(const FileSpec &file) {
523 m_remote_install_file = file;
526 const FileSpec &GetSymbolFileFileSpec() const { return m_symfile_spec; }
528 void PreloadSymbols();
530 void SetSymbolFileFileSpec(const FileSpec &file);
532 const llvm::sys::TimePoint<> &GetModificationTime() const {
536 const llvm::sys::TimePoint<> &GetObjectModificationTime() const {
537 return m_object_mod_time;
540 void SetObjectModificationTime(const llvm::sys::TimePoint<> &mod_time) {
541 m_mod_time = mod_time;
544 /// Tells whether this module is capable of being the main executable for a
548 /// \b true if it is, \b false otherwise.
551 /// Tells whether this module has been loaded in the target passed in. This
552 /// call doesn't distinguish between whether the module is loaded by the
553 /// dynamic loader, or by a "target module add" type call.
555 /// \param[in] target
556 /// The target to check whether this is loaded in.
559 /// \b true if it is, \b false otherwise.
560 bool IsLoadedInTarget(Target *target);
562 bool LoadScriptingResourceInTarget(Target *target, Status &error,
563 Stream *feedback_stream = nullptr);
565 /// Get the number of compile units for this module.
568 /// The number of compile units that the symbol vendor plug-in
570 size_t GetNumCompileUnits();
572 lldb::CompUnitSP GetCompileUnitAtIndex(size_t idx);
574 ConstString GetObjectName() const;
576 uint64_t GetObjectOffset() const { return m_object_offset; }
578 /// Get the object file representation for the current architecture.
580 /// If the object file has not been located or parsed yet, this function
581 /// will find the best ObjectFile plug-in that can parse Module::m_file.
584 /// If Module::m_file does not exist, or no plug-in was found
585 /// that can parse the file, or the object file doesn't contain
586 /// the current architecture in Module::m_arch, nullptr will be
587 /// returned, else a valid object file interface will be
588 /// returned. The returned pointer is owned by this object and
589 /// remains valid as long as the object is around.
590 virtual ObjectFile *GetObjectFile();
592 /// Get the unified section list for the module. This is the section list
593 /// created by the module's object file and any debug info and symbol files
594 /// created by the symbol vendor.
596 /// If the symbol vendor has not been loaded yet, this function will return
597 /// the section list for the object file.
600 /// Unified module section list.
601 virtual SectionList *GetSectionList();
603 /// Notify the module that the file addresses for the Sections have been
606 /// If the Section file addresses for a module are updated, this method
607 /// should be called. Any parts of the module, object file, or symbol file
608 /// that has cached those file addresses must invalidate or update its
610 virtual void SectionFileAddressesChanged();
612 /// Returns a reference to the UnwindTable for this Module
614 /// The UnwindTable contains FuncUnwinders objects for any function in this
615 /// Module. If a FuncUnwinders object hasn't been created yet (i.e. the
616 /// function has yet to be unwound in a stack walk), it will be created when
617 /// requested. Specifically, we do not create FuncUnwinders objects for
618 /// functions until they are needed.
621 /// Returns the unwind table for this module. If this object has no
622 /// associated object file, an empty UnwindTable is returned.
623 UnwindTable &GetUnwindTable();
625 llvm::VersionTuple GetVersion();
627 /// Load an object file from memory.
629 /// If available, the size of the object file in memory may be passed to
630 /// avoid additional round trips to process memory. If the size is not
631 /// provided, a default value is used. This value should be large enough to
632 /// enable the ObjectFile plugins to read the header of the object file
633 /// without going back to the process.
636 /// The object file loaded from memory or nullptr, if the operation
637 /// failed (see the `error` for more information in that case).
638 ObjectFile *GetMemoryObjectFile(const lldb::ProcessSP &process_sp,
639 lldb::addr_t header_addr, Status &error,
640 size_t size_to_read = 512);
641 /// Get the symbol vendor interface for the current architecture.
643 /// If the symbol vendor file has not been located yet, this function will
644 /// find the best SymbolVendor plug-in that can use the current object file.
647 /// If this module does not have a valid object file, or no
648 /// plug-in can be found that can use the object file, nullptr will
649 /// be returned, else a valid symbol vendor plug-in interface
650 /// will be returned. The returned pointer is owned by this
651 /// object and remains valid as long as the object is around.
652 virtual SymbolVendor *
653 GetSymbolVendor(bool can_create = true,
654 lldb_private::Stream *feedback_strm = nullptr);
656 /// Get accessor the type list for this module.
659 /// A valid type list pointer, or nullptr if there is no valid
660 /// symbol vendor for this module.
661 TypeList *GetTypeList();
663 /// Get a reference to the UUID value contained in this object.
665 /// If the executable image file doesn't not have a UUID value built into
666 /// the file format, an MD5 checksum of the entire file, or slice of the
667 /// file for the current architecture should be used.
670 /// A const pointer to the internal copy of the UUID value in
671 /// this module if this module has a valid UUID value, NULL
673 const lldb_private::UUID &GetUUID();
675 /// A debugging function that will cause everything in a module to
678 /// All compile units will be parsed, along with all globals and static
679 /// variables and all functions for those compile units. All types, scopes,
680 /// local variables, static variables, global variables, and line tables
681 /// will be parsed. This can be used prior to dumping a module to see a
682 /// complete list of the resulting debug information that gets parsed, or as
683 /// a debug function to ensure that the module can consume all of the debug
684 /// data the symbol vendor provides.
685 void ParseAllDebugSymbols();
687 bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr);
689 /// Resolve the symbol context for the given address.
691 /// Tries to resolve the matching symbol context based on a lookup from the
692 /// current symbol vendor. If the lazy lookup fails, an attempt is made to
693 /// parse the eh_frame section to handle stripped symbols. If this fails,
694 /// an attempt is made to resolve the symbol to the previous address to
695 /// handle the case of a function with a tail call.
697 /// Use properties of the modified SymbolContext to inspect any resolved
698 /// target, module, compilation unit, symbol, function, function block or
699 /// line entry. Use the return value to determine which of these properties
700 /// have been modified.
702 /// \param[in] so_addr
703 /// A load address to resolve.
705 /// \param[in] resolve_scope
706 /// The scope that should be resolved (see SymbolContext::Scope).
707 /// A combination of flags from the enumeration SymbolContextItem
708 /// requesting a resolution depth. Note that the flags that are
709 /// actually resolved may be a superset of the requested flags.
710 /// For instance, eSymbolContextSymbol requires resolution of
711 /// eSymbolContextModule, and eSymbolContextFunction requires
712 /// eSymbolContextSymbol.
715 /// The SymbolContext that is modified based on symbol resolution.
717 /// \param[in] resolve_tail_call_address
718 /// Determines if so_addr should resolve to a symbol in the case
719 /// of a function whose last instruction is a call. In this case,
720 /// the PC can be one past the address range of the function.
723 /// The scope that has been resolved (see SymbolContext::Scope).
725 /// \see SymbolContext::Scope
726 uint32_t ResolveSymbolContextForAddress(
727 const Address &so_addr, lldb::SymbolContextItem resolve_scope,
728 SymbolContext &sc, bool resolve_tail_call_address = false);
730 /// Resolve items in the symbol context for a given file and line.
732 /// Tries to resolve \a file_path and \a line to a list of matching symbol
735 /// The line table entries contains addresses that can be used to further
736 /// resolve the values in each match: the function, block, symbol. Care
737 /// should be taken to minimize the amount of information that is requested
738 /// to only what is needed -- typically the module, compile unit, line table
739 /// and line table entry are sufficient.
741 /// \param[in] file_path
742 /// A path to a source file to match. If \a file_path does not
743 /// specify a directory, then this query will match all files
744 /// whose base filename matches. If \a file_path does specify
745 /// a directory, the fullpath to the file must match.
748 /// The source line to match, or zero if just the compile unit
749 /// should be resolved.
751 /// \param[in] check_inlines
752 /// Check for inline file and line number matches. This option
753 /// should be used sparingly as it will cause all line tables
754 /// for every compile unit to be parsed and searched for
755 /// matching inline file entries.
757 /// \param[in] resolve_scope
758 /// The scope that should be resolved (see
759 /// SymbolContext::Scope).
761 /// \param[out] sc_list
762 /// A symbol context list that gets matching symbols contexts
766 /// The number of matches that were added to \a sc_list.
768 /// \see SymbolContext::Scope
769 uint32_t ResolveSymbolContextForFilePath(
770 const char *file_path, uint32_t line, bool check_inlines,
771 lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list);
773 /// Resolve items in the symbol context for a given file and line.
775 /// Tries to resolve \a file_spec and \a line to a list of matching symbol
778 /// The line table entries contains addresses that can be used to further
779 /// resolve the values in each match: the function, block, symbol. Care
780 /// should be taken to minimize the amount of information that is requested
781 /// to only what is needed -- typically the module, compile unit, line table
782 /// and line table entry are sufficient.
784 /// \param[in] file_spec
785 /// A file spec to a source file to match. If \a file_path does
786 /// not specify a directory, then this query will match all
787 /// files whose base filename matches. If \a file_path does
788 /// specify a directory, the fullpath to the file must match.
791 /// The source line to match, or zero if just the compile unit
792 /// should be resolved.
794 /// \param[in] check_inlines
795 /// Check for inline file and line number matches. This option
796 /// should be used sparingly as it will cause all line tables
797 /// for every compile unit to be parsed and searched for
798 /// matching inline file entries.
800 /// \param[in] resolve_scope
801 /// The scope that should be resolved (see
802 /// SymbolContext::Scope).
804 /// \param[out] sc_list
805 /// A symbol context list that gets filled in with all of the
809 /// A integer that contains SymbolContext::Scope bits set for
810 /// each item that was successfully resolved.
812 /// \see SymbolContext::Scope
813 uint32_t ResolveSymbolContextsForFileSpec(
814 const FileSpec &file_spec, uint32_t line, bool check_inlines,
815 lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list);
817 void SetFileSpecAndObjectName(const FileSpec &file,
818 ConstString object_name);
820 bool GetIsDynamicLinkEditor();
822 TypeSystem *GetTypeSystemForLanguage(lldb::LanguageType language);
824 // Special error functions that can do printf style formatting that will
825 // prepend the message with something appropriate for this module (like the
826 // architecture, path and object name (if any)). This centralizes code so
827 // that everyone doesn't need to format their error and log messages on their
828 // own and keeps the output a bit more consistent.
829 void LogMessage(Log *log, const char *format, ...)
830 __attribute__((format(printf, 3, 4)));
832 void LogMessageVerboseBacktrace(Log *log, const char *format, ...)
833 __attribute__((format(printf, 3, 4)));
835 void ReportWarning(const char *format, ...)
836 __attribute__((format(printf, 2, 3)));
838 void ReportError(const char *format, ...)
839 __attribute__((format(printf, 2, 3)));
841 // Only report an error once when the module is first detected to be modified
842 // so we don't spam the console with many messages.
843 void ReportErrorIfModifyDetected(const char *format, ...)
844 __attribute__((format(printf, 2, 3)));
846 // Return true if the file backing this module has changed since the module
847 // was originally created since we saved the initial file modification time
848 // when the module first gets created.
849 bool FileHasChanged() const;
851 // SymbolVendor, SymbolFile and ObjectFile member objects should lock the
852 // module mutex to avoid deadlocks.
853 std::recursive_mutex &GetMutex() const { return m_mutex; }
855 PathMappingList &GetSourceMappingList() { return m_source_mappings; }
857 const PathMappingList &GetSourceMappingList() const {
858 return m_source_mappings;
861 /// Finds a source file given a file spec using the module source path
862 /// remappings (if any).
864 /// Tries to resolve \a orig_spec by checking the module source path
865 /// remappings. It makes sure the file exists, so this call can be expensive
866 /// if the remappings are on a network file system, so use this function
867 /// sparingly (not in a tight debug info parsing loop).
869 /// \param[in] orig_spec
870 /// The original source file path to try and remap.
872 /// \param[out] new_spec
873 /// The newly remapped filespec that is guaranteed to exist.
876 /// /b true if \a orig_spec was successfully located and
877 /// \a new_spec is filled in with an existing file spec,
878 /// \b false otherwise.
879 bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
881 /// Remaps a source file given \a path into \a new_path.
883 /// Remaps \a path if any source remappings match. This function does NOT
884 /// stat the file system so it can be used in tight loops where debug info
888 /// The original source file path to try and remap.
890 /// \param[out] new_path
891 /// The newly remapped filespec that is may or may not exist.
894 /// /b true if \a path was successfully located and \a new_path
895 /// is filled in with a new source path, \b false otherwise.
896 bool RemapSourceFile(llvm::StringRef path, std::string &new_path) const;
897 bool RemapSourceFile(const char *, std::string &) const = delete;
899 /// \class LookupInfo Module.h "lldb/Core/Module.h"
900 /// A class that encapsulates name lookup information.
902 /// Users can type a wide variety of partial names when setting breakpoints
903 /// by name or when looking for functions by name. SymbolVendor and
904 /// SymbolFile objects are only required to implement name lookup for
905 /// function basenames and for fully mangled names. This means if the user
906 /// types in a partial name, we must reduce this to a name lookup that will
907 /// work with all SymbolFile objects. So we might reduce a name lookup to
908 /// look for a basename, and then prune out any results that don't match.
910 /// The "m_name" member variable represents the name as it was typed by the
911 /// user. "m_lookup_name" will be the name we actually search for through
912 /// the symbol or objects files. Lanaguage is included in case we need to
913 /// filter results by language at a later date. The "m_name_type_mask"
914 /// member variable tells us what kinds of names we are looking for and can
915 /// help us prune out unwanted results.
917 /// Function lookups are done in Module.cpp, ModuleList.cpp and in
918 /// BreakpointResolverName.cpp and they all now use this class to do lookups
923 : m_name(), m_lookup_name(), m_language(lldb::eLanguageTypeUnknown),
924 m_name_type_mask(lldb::eFunctionNameTypeNone),
925 m_match_name_after_lookup(false) {}
927 LookupInfo(ConstString name, lldb::FunctionNameType name_type_mask,
928 lldb::LanguageType language);
930 ConstString GetName() const { return m_name; }
932 void SetName(ConstString name) { m_name = name; }
934 ConstString GetLookupName() const { return m_lookup_name; }
936 void SetLookupName(ConstString name) { m_lookup_name = name; }
938 lldb::FunctionNameType GetNameTypeMask() const { return m_name_type_mask; }
940 void SetNameTypeMask(lldb::FunctionNameType mask) {
941 m_name_type_mask = mask;
944 void Prune(SymbolContextList &sc_list, size_t start_idx) const;
947 /// What the user originally typed
950 /// The actual name will lookup when calling in the object or symbol file
951 ConstString m_lookup_name;
953 /// Limit matches to only be for this language
954 lldb::LanguageType m_language;
956 /// One or more bits from lldb::FunctionNameType that indicate what kind of
957 /// names we are looking for
958 lldb::FunctionNameType m_name_type_mask;
960 ///< If \b true, then demangled names that match will need to contain
961 ///< "m_name" in order to be considered a match
962 bool m_match_name_after_lookup;
967 mutable std::recursive_mutex m_mutex; ///< A mutex to keep this object happy
968 ///in multi-threaded environments.
970 /// The modification time for this module when it was created.
971 llvm::sys::TimePoint<> m_mod_time;
973 ArchSpec m_arch; ///< The architecture for this module.
974 UUID m_uuid; ///< Each module is assumed to have a unique identifier to help
975 ///match it up to debug symbols.
976 FileSpec m_file; ///< The file representation on disk for this module (if
978 FileSpec m_platform_file; ///< The path to the module on the platform on which
979 ///it is being debugged
980 FileSpec m_remote_install_file; ///< If set when debugging on remote
981 ///platforms, this module will be installed at
983 FileSpec m_symfile_spec; ///< If this path is valid, then this is the file
984 ///that _will_ be used as the symbol file for this
986 ConstString m_object_name; ///< The name an object within this module that is
987 ///selected, or empty of the module is represented
989 uint64_t m_object_offset;
990 llvm::sys::TimePoint<> m_object_mod_time;
991 lldb::ObjectFileSP m_objfile_sp; ///< A shared pointer to the object file
992 ///parser for this module as it may or may
993 ///not be shared with the SymbolFile
994 llvm::Optional<UnwindTable> m_unwind_table; ///< Table of FuncUnwinders
995 /// objects created for this
996 /// Module's functions
998 m_symfile_up; ///< A pointer to the symbol vendor for this module.
999 std::vector<lldb::SymbolVendorUP>
1000 m_old_symfiles; ///< If anyone calls Module::SetSymbolFileFileSpec() and
1001 ///changes the symbol file,
1002 ///< we need to keep all old symbol files around in case anyone has type
1003 ///references to them
1004 TypeSystemMap m_type_system_map; ///< A map of any type systems associated
1006 PathMappingList m_source_mappings; ///< Module specific source remappings for
1007 ///when you have debug info for a module
1008 ///that doesn't match where the sources
1010 lldb::SectionListUP m_sections_up; ///< Unified section list for module that
1011 /// is used by the ObjectFile and and
1012 /// ObjectFile instances for the debug info
1014 std::atomic<bool> m_did_load_objfile{false};
1015 std::atomic<bool> m_did_load_symbol_vendor{false};
1016 std::atomic<bool> m_did_set_uuid{false};
1017 mutable bool m_file_has_changed : 1,
1018 m_first_file_changed_log : 1; /// See if the module was modified after it
1019 /// was initially opened.
1021 /// Resolve a file or load virtual address.
1023 /// Tries to resolve \a vm_addr as a file address (if \a
1024 /// vm_addr_is_file_addr is true) or as a load address if \a
1025 /// vm_addr_is_file_addr is false) in the symbol vendor. \a resolve_scope
1026 /// indicates what clients wish to resolve and can be used to limit the
1027 /// scope of what is parsed.
1029 /// \param[in] vm_addr
1030 /// The load virtual address to resolve.
1032 /// \param[in] vm_addr_is_file_addr
1033 /// If \b true, \a vm_addr is a file address, else \a vm_addr
1034 /// if a load address.
1036 /// \param[in] resolve_scope
1037 /// The scope that should be resolved (see
1038 /// SymbolContext::Scope).
1040 /// \param[out] so_addr
1041 /// The section offset based address that got resolved if
1042 /// any bits are returned.
1045 // The symbol context that has objects filled in. Each bit
1046 /// in the \a resolve_scope pertains to a member in the \a sc.
1049 /// A integer that contains SymbolContext::Scope bits set for
1050 /// each item that was successfully resolved.
1052 /// \see SymbolContext::Scope
1053 uint32_t ResolveSymbolContextForAddress(lldb::addr_t vm_addr,
1054 bool vm_addr_is_file_addr,
1055 lldb::SymbolContextItem resolve_scope,
1056 Address &so_addr, SymbolContext &sc);
1058 void SymbolIndicesToSymbolContextList(Symtab *symtab,
1059 std::vector<uint32_t> &symbol_indexes,
1060 SymbolContextList &sc_list);
1062 bool SetArchitecture(const ArchSpec &new_arch);
1064 void SetUUID(const lldb_private::UUID &uuid);
1066 SectionList *GetUnifiedSectionList();
1068 friend class ModuleList;
1069 friend class ObjectFile;
1070 friend class SymbolFile;
1073 Module(); // Only used internally by CreateJITModule ()
1075 size_t FindTypes_Impl(
1076 ConstString name, const CompilerDeclContext *parent_decl_ctx,
1077 bool append, size_t max_matches,
1078 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
1081 DISALLOW_COPY_AND_ASSIGN(Module);
1084 } // namespace lldb_private
1086 #endif // liblldb_Module_h_