1 //===-- Module.h ------------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_Module_h_
11 #define liblldb_Module_h_
13 #include "lldb/Core/Address.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/Utility/ArchSpec.h"
20 #include "lldb/Utility/ConstString.h"
21 #include "lldb/Utility/FileSpec.h"
22 #include "lldb/Utility/Status.h"
23 #include "lldb/Utility/UUID.h"
24 #include "lldb/lldb-defines.h"
25 #include "lldb/lldb-enumerations.h"
26 #include "lldb/lldb-forward.h"
27 #include "lldb/lldb-types.h"
29 #include "llvm/ADT/DenseSet.h"
30 #include "llvm/ADT/StringRef.h"
31 #include "llvm/Support/Chrono.h"
41 namespace lldb_private {
42 class CompilerDeclContext;
44 namespace lldb_private {
47 namespace lldb_private {
50 namespace lldb_private {
53 namespace lldb_private {
54 class RegularExpression;
56 namespace lldb_private {
59 namespace lldb_private {
62 namespace lldb_private {
65 namespace lldb_private {
68 namespace lldb_private {
69 class SymbolContextList;
71 namespace lldb_private {
74 namespace lldb_private {
77 namespace lldb_private {
80 namespace lldb_private {
83 namespace lldb_private {
86 namespace lldb_private {
89 namespace lldb_private {
93 namespace lldb_private {
95 //----------------------------------------------------------------------
96 /// @class Module Module.h "lldb/Core/Module.h"
97 /// A class that describes an executable image and its associated
98 /// object and symbol files.
100 /// The module is designed to be able to select a single slice of an
101 /// executable image as it would appear on disk and during program execution.
103 /// Modules control when and if information is parsed according to which
104 /// accessors are called. For example the object file (ObjectFile)
105 /// representation will only be parsed if the object file is requested using
106 /// the Module::GetObjectFile() is called. The debug symbols will only be
107 /// parsed if the symbol vendor (SymbolVendor) is requested using the
108 /// Module::GetSymbolVendor() is called.
110 /// The module will parse more detailed information as more queries are made.
111 //----------------------------------------------------------------------
112 class Module : public std::enable_shared_from_this<Module>,
113 public SymbolContextScope {
115 // Static functions that can track the lifetime of module objects. This is
116 // handy because we might have Module objects that are in shared pointers
117 // that aren't in the global module list (from ModuleList). If this is the
118 // case we need to know about it. The modules in the global list maintained
119 // by these functions can be viewed using the "target modules list" command
120 // using the "--global" (-g for short).
121 static size_t GetNumberAllocatedModules();
123 static Module *GetAllocatedModuleAtIndex(size_t idx);
125 static std::recursive_mutex &GetAllocationModuleCollectionMutex();
127 //------------------------------------------------------------------
128 /// Construct with file specification and architecture.
130 /// Clients that wish to share modules with other targets should use
131 /// ModuleList::GetSharedModule().
133 /// @param[in] file_spec
134 /// The file specification for the on disk representation of
135 /// this executable image.
138 /// The architecture to set as the current architecture in
141 /// @param[in] object_name
142 /// The name of an object in a module used to extract a module
143 /// within a module (.a files and modules that contain multiple
146 /// @param[in] object_offset
147 /// The offset within an existing module used to extract a
148 /// module within a module (.a files and modules that contain
149 /// multiple architectures).
150 //------------------------------------------------------------------
152 const FileSpec &file_spec, const ArchSpec &arch,
153 const ConstString *object_name = nullptr,
154 lldb::offset_t object_offset = 0,
155 const llvm::sys::TimePoint<> &object_mod_time = llvm::sys::TimePoint<>());
157 Module(const ModuleSpec &module_spec);
159 template <typename ObjFilePlugin, typename... Args>
160 static lldb::ModuleSP CreateModuleFromObjectFile(Args &&... args) {
161 // Must create a module and place it into a shared pointer before we can
162 // create an object file since it has a std::weak_ptr back to the module,
163 // so we need to control the creation carefully in this static function
164 lldb::ModuleSP module_sp(new Module());
165 module_sp->m_objfile_sp =
166 std::make_shared<ObjFilePlugin>(module_sp, std::forward<Args>(args)...);
168 // Once we get the object file, update our module with the object file's
169 // architecture since it might differ in vendor/os if some parts were
171 if (ArchSpec arch = module_sp->m_objfile_sp->GetArchitecture()) {
172 module_sp->m_arch = arch;
178 //------------------------------------------------------------------
180 //------------------------------------------------------------------
183 bool MatchesModuleSpec(const ModuleSpec &module_ref);
185 //------------------------------------------------------------------
186 /// Set the load address for all sections in a module to be the file address
189 /// Many times a module will be loaded in a target with a constant offset
190 /// applied to all top level sections. This function can set the load
191 /// address for all top level sections to be the section file address +
194 /// @param[in] target
195 /// The target in which to apply the section load addresses.
198 /// if \a value_is_offset is true, then value is the offset to
199 /// apply to all file addresses for all top level sections in
200 /// the object file as each section load address is being set.
201 /// If \a value_is_offset is false, then "value" is the new
202 /// absolute base address for the image.
204 /// @param[in] value_is_offset
205 /// If \b true, then \a value is an offset to apply to each
206 /// file address of each top level section.
207 /// If \b false, then \a value is the image base address that
208 /// will be used to rigidly slide all loadable sections.
210 /// @param[out] changed
211 /// If any section load addresses were changed in \a target,
212 /// then \a changed will be set to \b true. Else \a changed
213 /// will be set to false. This allows this function to be
214 /// called multiple times on the same module for the same
215 /// target. If the module hasn't moved, then \a changed will
216 /// be false and no module updated notification will need to
220 /// /b True if any sections were successfully loaded in \a target,
221 /// /b false otherwise.
222 //------------------------------------------------------------------
223 bool SetLoadAddress(Target &target, lldb::addr_t value, bool value_is_offset,
226 //------------------------------------------------------------------
227 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
229 /// @see SymbolContextScope
230 //------------------------------------------------------------------
231 void CalculateSymbolContext(SymbolContext *sc) override;
233 lldb::ModuleSP CalculateSymbolContextModule() override;
236 GetDescription(Stream *s,
237 lldb::DescriptionLevel level = lldb::eDescriptionLevelFull);
239 //------------------------------------------------------------------
240 /// Get the module path and object name.
242 /// Modules can refer to object files. In this case the specification is
243 /// simple and would return the path to the file:
245 /// "/usr/lib/foo.dylib"
247 /// Modules can be .o files inside of a BSD archive (.a file). In this case,
248 /// the object specification will look like:
250 /// "/usr/lib/foo.a(bar.o)"
252 /// There are many places where logging wants to log this fully qualified
253 /// specification, so we centralize this functionality here.
256 /// The object path + object name if there is one.
257 //------------------------------------------------------------------
258 std::string GetSpecificationDescription() const;
260 //------------------------------------------------------------------
261 /// Dump a description of this object to a Stream.
263 /// Dump a description of the contents of this object to the supplied stream
264 /// \a s. The dumped content will be only what has been loaded or parsed up
265 /// to this point at which this function is called, so this is a good way to
266 /// see what has been parsed in a module.
269 /// The stream to which to dump the object description.
270 //------------------------------------------------------------------
271 void Dump(Stream *s);
273 //------------------------------------------------------------------
274 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
276 /// @see SymbolContextScope
277 //------------------------------------------------------------------
278 void DumpSymbolContext(Stream *s) override;
280 //------------------------------------------------------------------
281 /// Find a symbol in the object file's symbol table.
284 /// The name of the symbol that we are looking for.
286 /// @param[in] symbol_type
287 /// If set to eSymbolTypeAny, find a symbol of any type that
288 /// has a name that matches \a name. If set to any other valid
289 /// SymbolType enumeration value, then search only for
290 /// symbols that match \a symbol_type.
293 /// Returns a valid symbol pointer if a symbol was found,
294 /// nullptr otherwise.
295 //------------------------------------------------------------------
296 const Symbol *FindFirstSymbolWithNameAndType(
297 const ConstString &name,
298 lldb::SymbolType symbol_type = lldb::eSymbolTypeAny);
300 size_t FindSymbolsWithNameAndType(const ConstString &name,
301 lldb::SymbolType symbol_type,
302 SymbolContextList &sc_list);
304 size_t FindSymbolsMatchingRegExAndType(const RegularExpression ®ex,
305 lldb::SymbolType symbol_type,
306 SymbolContextList &sc_list);
308 //------------------------------------------------------------------
309 /// Find a function symbols in the object file's symbol table.
312 /// The name of the symbol that we are looking for.
314 /// @param[in] name_type_mask
315 /// A mask that has one or more bitwise OR'ed values from the
316 /// lldb::FunctionNameType enumeration type that indicate what
317 /// kind of names we are looking for.
319 /// @param[out] sc_list
320 /// A list to append any matching symbol contexts to.
323 /// The number of symbol contexts that were added to \a sc_list
324 //------------------------------------------------------------------
325 size_t FindFunctionSymbols(const ConstString &name, uint32_t name_type_mask,
326 SymbolContextList &sc_list);
328 //------------------------------------------------------------------
329 /// Find compile units by partial or full path.
331 /// Finds all compile units that match \a path in all of the modules and
332 /// returns the results in \a sc_list.
335 /// The name of the function we are looking for.
337 /// @param[in] append
338 /// If \b true, then append any compile units that were found
339 /// to \a sc_list. If \b false, then the \a sc_list is cleared
340 /// and the contents of \a sc_list are replaced.
342 /// @param[out] sc_list
343 /// A symbol context list that gets filled in with all of the
347 /// The number of matches added to \a sc_list.
348 //------------------------------------------------------------------
349 size_t FindCompileUnits(const FileSpec &path, bool append,
350 SymbolContextList &sc_list);
352 //------------------------------------------------------------------
353 /// Find functions by name.
355 /// If the function is an inlined function, it will have a block,
356 /// representing the inlined function, and the function will be the
357 /// containing function. If it is not inlined, then the block will be NULL.
360 /// The name of the compile unit we are looking for.
362 /// @param[in] namespace_decl
363 /// If valid, a namespace to search in.
365 /// @param[in] name_type_mask
366 /// A bit mask of bits that indicate what kind of names should
367 /// be used when doing the lookup. Bits include fully qualified
368 /// names, base names, C++ methods, or ObjC selectors.
369 /// See FunctionNameType for more details.
371 /// @param[in] append
372 /// If \b true, any matches will be appended to \a sc_list, else
373 /// matches replace the contents of \a sc_list.
375 /// @param[out] sc_list
376 /// A symbol context list that gets filled in with all of the
380 /// The number of matches added to \a sc_list.
381 //------------------------------------------------------------------
382 size_t FindFunctions(const ConstString &name,
383 const CompilerDeclContext *parent_decl_ctx,
384 lldb::FunctionNameType name_type_mask, bool symbols_ok,
385 bool inlines_ok, bool append,
386 SymbolContextList &sc_list);
388 //------------------------------------------------------------------
389 /// Find functions by name.
391 /// If the function is an inlined function, it will have a block,
392 /// representing the inlined function, and the function will be the
393 /// containing function. If it is not inlined, then the block will be NULL.
396 /// A regular expression to use when matching the name.
398 /// @param[in] append
399 /// If \b true, any matches will be appended to \a sc_list, else
400 /// matches replace the contents of \a sc_list.
402 /// @param[out] sc_list
403 /// A symbol context list that gets filled in with all of the
407 /// The number of matches added to \a sc_list.
408 //------------------------------------------------------------------
409 size_t FindFunctions(const RegularExpression ®ex, bool symbols_ok,
410 bool inlines_ok, bool append,
411 SymbolContextList &sc_list);
413 //------------------------------------------------------------------
414 /// Find addresses by file/line
416 /// @param[in] target_sp
417 /// The target the addresses are desired for.
420 /// Source file to locate.
423 /// Source line to locate.
425 /// @param[in] function
426 /// Optional filter function. Addresses within this function will be
427 /// added to the 'local' list. All others will be added to the 'extern'
430 /// @param[out] output_local
431 /// All matching addresses within 'function'
433 /// @param[out] output_extern
434 /// All matching addresses not within 'function'
435 void FindAddressesForLine(const lldb::TargetSP target_sp,
436 const FileSpec &file, uint32_t line,
438 std::vector<Address> &output_local,
439 std::vector<Address> &output_extern);
441 //------------------------------------------------------------------
442 /// Find global and static variables by name.
445 /// The name of the global or static variable we are looking
448 /// @param[in] parent_decl_ctx
449 /// If valid, a decl context that results must exist within
451 /// @param[in] max_matches
452 /// Allow the number of matches to be limited to \a
453 /// max_matches. Specify UINT32_MAX to get all possible matches.
455 /// @param[in] variable_list
456 /// A list of variables that gets the matches appended to.
459 /// The number of matches added to \a variable_list.
460 //------------------------------------------------------------------
461 size_t FindGlobalVariables(const ConstString &name,
462 const CompilerDeclContext *parent_decl_ctx,
463 size_t max_matches, VariableList &variable_list);
465 //------------------------------------------------------------------
466 /// Find global and static variables by regular expression.
469 /// A regular expression to use when matching the name.
471 /// @param[in] max_matches
472 /// Allow the number of matches to be limited to \a
473 /// max_matches. Specify UINT32_MAX to get all possible matches.
475 /// @param[in] variable_list
476 /// A list of variables that gets the matches appended to.
479 /// The number of matches added to \a variable_list.
480 //------------------------------------------------------------------
481 size_t FindGlobalVariables(const RegularExpression ®ex, size_t max_matches,
482 VariableList &variable_list);
484 //------------------------------------------------------------------
485 /// Find types by name.
487 /// Type lookups in modules go through the SymbolVendor (which will use one
488 /// or more SymbolFile subclasses). The SymbolFile needs to be able to
489 /// lookup types by basename and not the fully qualified typename. This
490 /// allows the type accelerator tables to stay small, even with heavily
491 /// templatized C++. The type search will then narrow down the search
492 /// results. If "exact_match" is true, then the type search will only match
493 /// exact type name matches. If "exact_match" is false, the type will match
494 /// as long as the base typename matches and as long as any immediate
495 /// containing namespaces/class scopes that are specified match. So to
496 /// search for a type "d" in "b::c", the name "b::c::d" can be specified and
497 /// it will match any class/namespace "b" which contains a class/namespace
498 /// "c" which contains type "d". We do this to allow users to not always
499 /// have to specify complete scoping on all expressions, but it also allows
500 /// for exact matching when required.
502 /// @param[in] type_name
503 /// The name of the type we are looking for that is a fully
504 /// or partially qualified type name.
506 /// @param[in] exact_match
507 /// If \b true, \a type_name is fully qualified and must match
508 /// exactly. If \b false, \a type_name is a partially qualified
509 /// name where the leading namespaces or classes can be
510 /// omitted to make finding types that a user may type
513 /// @param[out] type_list
514 /// A type list gets populated with any matches.
517 /// The number of matches added to \a type_list.
518 //------------------------------------------------------------------
520 FindTypes(const ConstString &type_name, bool exact_match, size_t max_matches,
521 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
524 lldb::TypeSP FindFirstType(const SymbolContext &sc,
525 const ConstString &type_name, bool exact_match);
527 //------------------------------------------------------------------
528 /// Find types by name that are in a namespace. This function is used by the
529 /// expression parser when searches need to happen in an exact namespace
532 /// @param[in] type_name
533 /// The name of a type within a namespace that should not include
534 /// any qualifying namespaces (just a type basename).
536 /// @param[in] namespace_decl
537 /// The namespace declaration that this type must exist in.
539 /// @param[out] type_list
540 /// A type list gets populated with any matches.
543 /// The number of matches added to \a type_list.
544 //------------------------------------------------------------------
545 size_t FindTypesInNamespace(const ConstString &type_name,
546 const CompilerDeclContext *parent_decl_ctx,
547 size_t max_matches, TypeList &type_list);
549 //------------------------------------------------------------------
550 /// Get const accessor for the module architecture.
553 /// A const reference to the architecture object.
554 //------------------------------------------------------------------
555 const ArchSpec &GetArchitecture() const;
557 //------------------------------------------------------------------
558 /// Get const accessor for the module file specification.
560 /// This function returns the file for the module on the host system that is
561 /// running LLDB. This can differ from the path on the platform since we
562 /// might be doing remote debugging.
565 /// A const reference to the file specification object.
566 //------------------------------------------------------------------
567 const FileSpec &GetFileSpec() const { return m_file; }
569 //------------------------------------------------------------------
570 /// Get accessor for the module platform file specification.
572 /// Platform file refers to the path of the module as it is known on the
573 /// remote system on which it is being debugged. For local debugging this is
574 /// always the same as Module::GetFileSpec(). But remote debugging might
575 /// mention a file "/usr/lib/liba.dylib" which might be locally downloaded
576 /// and cached. In this case the platform file could be something like:
577 /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" The
578 /// file could also be cached in a local developer kit directory.
581 /// A const reference to the file specification object.
582 //------------------------------------------------------------------
583 const FileSpec &GetPlatformFileSpec() const {
585 return m_platform_file;
589 void SetPlatformFileSpec(const FileSpec &file) { m_platform_file = file; }
591 const FileSpec &GetRemoteInstallFileSpec() const {
592 return m_remote_install_file;
595 void SetRemoteInstallFileSpec(const FileSpec &file) {
596 m_remote_install_file = file;
599 const FileSpec &GetSymbolFileFileSpec() const { return m_symfile_spec; }
601 void PreloadSymbols();
603 void SetSymbolFileFileSpec(const FileSpec &file);
605 const llvm::sys::TimePoint<> &GetModificationTime() const {
609 const llvm::sys::TimePoint<> &GetObjectModificationTime() const {
610 return m_object_mod_time;
613 void SetObjectModificationTime(const llvm::sys::TimePoint<> &mod_time) {
614 m_mod_time = mod_time;
617 //------------------------------------------------------------------
618 /// Tells whether this module is capable of being the main executable for a
622 /// \b true if it is, \b false otherwise.
623 //------------------------------------------------------------------
626 //------------------------------------------------------------------
627 /// Tells whether this module has been loaded in the target passed in. This
628 /// call doesn't distinguish between whether the module is loaded by the
629 /// dynamic loader, or by a "target module add" type call.
631 /// @param[in] target
632 /// The target to check whether this is loaded in.
635 /// \b true if it is, \b false otherwise.
636 //------------------------------------------------------------------
637 bool IsLoadedInTarget(Target *target);
639 bool LoadScriptingResourceInTarget(Target *target, Status &error,
640 Stream *feedback_stream = nullptr);
642 //------------------------------------------------------------------
643 /// Get the number of compile units for this module.
646 /// The number of compile units that the symbol vendor plug-in
648 //------------------------------------------------------------------
649 size_t GetNumCompileUnits();
651 lldb::CompUnitSP GetCompileUnitAtIndex(size_t idx);
653 const ConstString &GetObjectName() const;
655 uint64_t GetObjectOffset() const { return m_object_offset; }
657 //------------------------------------------------------------------
658 /// Get the object file representation for the current architecture.
660 /// If the object file has not been located or parsed yet, this function
661 /// will find the best ObjectFile plug-in that can parse Module::m_file.
664 /// If Module::m_file does not exist, or no plug-in was found
665 /// that can parse the file, or the object file doesn't contain
666 /// the current architecture in Module::m_arch, nullptr will be
667 /// returned, else a valid object file interface will be
668 /// returned. The returned pointer is owned by this object and
669 /// remains valid as long as the object is around.
670 //------------------------------------------------------------------
671 virtual ObjectFile *GetObjectFile();
673 //------------------------------------------------------------------
674 /// Get the unified section list for the module. This is the section list
675 /// created by the module's object file and any debug info and symbol files
676 /// created by the symbol vendor.
678 /// If the symbol vendor has not been loaded yet, this function will return
679 /// the section list for the object file.
682 /// Unified module section list.
683 //------------------------------------------------------------------
684 virtual SectionList *GetSectionList();
686 //------------------------------------------------------------------
687 /// Notify the module that the file addresses for the Sections have been
690 /// If the Section file addresses for a module are updated, this method
691 /// should be called. Any parts of the module, object file, or symbol file
692 /// that has cached those file addresses must invalidate or update its
694 //------------------------------------------------------------------
695 virtual void SectionFileAddressesChanged();
697 llvm::VersionTuple GetVersion();
699 //------------------------------------------------------------------
700 /// Load an object file from memory.
702 /// If available, the size of the object file in memory may be passed to
703 /// avoid additional round trips to process memory. If the size is not
704 /// provided, a default value is used. This value should be large enough to
705 /// enable the ObjectFile plugins to read the header of the object file
706 /// without going back to the process.
709 /// The object file loaded from memory or nullptr, if the operation
710 /// failed (see the `error` for more information in that case).
711 //------------------------------------------------------------------
712 ObjectFile *GetMemoryObjectFile(const lldb::ProcessSP &process_sp,
713 lldb::addr_t header_addr, Status &error,
714 size_t size_to_read = 512);
715 //------------------------------------------------------------------
716 /// Get the symbol vendor interface for the current architecture.
718 /// If the symbol vendor file has not been located yet, this function will
719 /// find the best SymbolVendor plug-in that can use the current object file.
722 /// If this module does not have a valid object file, or no
723 /// plug-in can be found that can use the object file, nullptr will
724 /// be returned, else a valid symbol vendor plug-in interface
725 /// will be returned. The returned pointer is owned by this
726 /// object and remains valid as long as the object is around.
727 //------------------------------------------------------------------
728 virtual SymbolVendor *
729 GetSymbolVendor(bool can_create = true,
730 lldb_private::Stream *feedback_strm = nullptr);
732 //------------------------------------------------------------------
733 /// Get accessor the type list for this module.
736 /// A valid type list pointer, or nullptr if there is no valid
737 /// symbol vendor for this module.
738 //------------------------------------------------------------------
739 TypeList *GetTypeList();
741 //------------------------------------------------------------------
742 /// Get a reference to the UUID value contained in this object.
744 /// If the executable image file doesn't not have a UUID value built into
745 /// the file format, an MD5 checksum of the entire file, or slice of the
746 /// file for the current architecture should be used.
749 /// A const pointer to the internal copy of the UUID value in
750 /// this module if this module has a valid UUID value, NULL
752 //------------------------------------------------------------------
753 const lldb_private::UUID &GetUUID();
755 //------------------------------------------------------------------
756 /// A debugging function that will cause everything in a module to
759 /// All compile units will be parsed, along with all globals and static
760 /// variables and all functions for those compile units. All types, scopes,
761 /// local variables, static variables, global variables, and line tables
762 /// will be parsed. This can be used prior to dumping a module to see a
763 /// complete list of the resulting debug information that gets parsed, or as
764 /// a debug function to ensure that the module can consume all of the debug
765 /// data the symbol vendor provides.
766 //------------------------------------------------------------------
767 void ParseAllDebugSymbols();
769 bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr);
771 //------------------------------------------------------------------
772 /// Resolve the symbol context for the given address.
774 /// Tries to resolve the matching symbol context based on a lookup from the
775 /// current symbol vendor. If the lazy lookup fails, an attempt is made to
776 /// parse the eh_frame section to handle stripped symbols. If this fails,
777 /// an attempt is made to resolve the symbol to the previous address to
778 /// handle the case of a function with a tail call.
780 /// Use properties of the modified SymbolContext to inspect any resolved
781 /// target, module, compilation unit, symbol, function, function block or
782 /// line entry. Use the return value to determine which of these properties
783 /// have been modified.
785 /// @param[in] so_addr
786 /// A load address to resolve.
788 /// @param[in] resolve_scope
789 /// The scope that should be resolved (see SymbolContext::Scope).
790 /// A combination of flags from the enumeration SymbolContextItem
791 /// requesting a resolution depth. Note that the flags that are
792 /// actually resolved may be a superset of the requested flags.
793 /// For instance, eSymbolContextSymbol requires resolution of
794 /// eSymbolContextModule, and eSymbolContextFunction requires
795 /// eSymbolContextSymbol.
798 /// The SymbolContext that is modified based on symbol resolution.
800 /// @param[in] resolve_tail_call_address
801 /// Determines if so_addr should resolve to a symbol in the case
802 /// of a function whose last instruction is a call. In this case,
803 /// the PC can be one past the address range of the function.
806 /// The scope that has been resolved (see SymbolContext::Scope).
808 /// @see SymbolContext::Scope
809 //------------------------------------------------------------------
810 uint32_t ResolveSymbolContextForAddress(
811 const Address &so_addr, lldb::SymbolContextItem resolve_scope,
812 SymbolContext &sc, bool resolve_tail_call_address = false);
814 //------------------------------------------------------------------
815 /// Resolve items in the symbol context for a given file and line.
817 /// Tries to resolve \a file_path and \a line to a list of matching symbol
820 /// The line table entries contains addresses that can be used to further
821 /// resolve the values in each match: the function, block, symbol. Care
822 /// should be taken to minimize the amount of information that is requested
823 /// to only what is needed -- typically the module, compile unit, line table
824 /// and line table entry are sufficient.
826 /// @param[in] file_path
827 /// A path to a source file to match. If \a file_path does not
828 /// specify a directory, then this query will match all files
829 /// whose base filename matches. If \a file_path does specify
830 /// a directory, the fullpath to the file must match.
833 /// The source line to match, or zero if just the compile unit
834 /// should be resolved.
836 /// @param[in] check_inlines
837 /// Check for inline file and line number matches. This option
838 /// should be used sparingly as it will cause all line tables
839 /// for every compile unit to be parsed and searched for
840 /// matching inline file entries.
842 /// @param[in] resolve_scope
843 /// The scope that should be resolved (see
844 /// SymbolContext::Scope).
846 /// @param[out] sc_list
847 /// A symbol context list that gets matching symbols contexts
851 /// The number of matches that were added to \a sc_list.
853 /// @see SymbolContext::Scope
854 //------------------------------------------------------------------
855 uint32_t ResolveSymbolContextForFilePath(
856 const char *file_path, uint32_t line, bool check_inlines,
857 lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list);
859 //------------------------------------------------------------------
860 /// Resolve items in the symbol context for a given file and line.
862 /// Tries to resolve \a file_spec and \a line to a list of matching symbol
865 /// The line table entries contains addresses that can be used to further
866 /// resolve the values in each match: the function, block, symbol. Care
867 /// should be taken to minimize the amount of information that is requested
868 /// to only what is needed -- typically the module, compile unit, line table
869 /// and line table entry are sufficient.
871 /// @param[in] file_spec
872 /// A file spec to a source file to match. If \a file_path does
873 /// not specify a directory, then this query will match all
874 /// files whose base filename matches. If \a file_path does
875 /// specify a directory, the fullpath to the file must match.
878 /// The source line to match, or zero if just the compile unit
879 /// should be resolved.
881 /// @param[in] check_inlines
882 /// Check for inline file and line number matches. This option
883 /// should be used sparingly as it will cause all line tables
884 /// for every compile unit to be parsed and searched for
885 /// matching inline file entries.
887 /// @param[in] resolve_scope
888 /// The scope that should be resolved (see
889 /// SymbolContext::Scope).
891 /// @param[out] sc_list
892 /// A symbol context list that gets filled in with all of the
896 /// A integer that contains SymbolContext::Scope bits set for
897 /// each item that was successfully resolved.
899 /// @see SymbolContext::Scope
900 //------------------------------------------------------------------
901 uint32_t ResolveSymbolContextsForFileSpec(
902 const FileSpec &file_spec, uint32_t line, bool check_inlines,
903 lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list);
905 void SetFileSpecAndObjectName(const FileSpec &file,
906 const ConstString &object_name);
908 bool GetIsDynamicLinkEditor();
910 TypeSystem *GetTypeSystemForLanguage(lldb::LanguageType language);
912 // Special error functions that can do printf style formatting that will
913 // prepend the message with something appropriate for this module (like the
914 // architecture, path and object name (if any)). This centralizes code so
915 // that everyone doesn't need to format their error and log messages on their
916 // own and keeps the output a bit more consistent.
917 void LogMessage(Log *log, const char *format, ...)
918 __attribute__((format(printf, 3, 4)));
920 void LogMessageVerboseBacktrace(Log *log, const char *format, ...)
921 __attribute__((format(printf, 3, 4)));
923 void ReportWarning(const char *format, ...)
924 __attribute__((format(printf, 2, 3)));
926 void ReportError(const char *format, ...)
927 __attribute__((format(printf, 2, 3)));
929 // Only report an error once when the module is first detected to be modified
930 // so we don't spam the console with many messages.
931 void ReportErrorIfModifyDetected(const char *format, ...)
932 __attribute__((format(printf, 2, 3)));
934 //------------------------------------------------------------------
935 // Return true if the file backing this module has changed since the module
936 // was originally created since we saved the initial file modification time
937 // when the module first gets created.
938 //------------------------------------------------------------------
939 bool FileHasChanged() const;
941 //------------------------------------------------------------------
942 // SymbolVendor, SymbolFile and ObjectFile member objects should lock the
943 // module mutex to avoid deadlocks.
944 //------------------------------------------------------------------
945 std::recursive_mutex &GetMutex() const { return m_mutex; }
947 PathMappingList &GetSourceMappingList() { return m_source_mappings; }
949 const PathMappingList &GetSourceMappingList() const {
950 return m_source_mappings;
953 //------------------------------------------------------------------
954 /// Finds a source file given a file spec using the module source path
955 /// remappings (if any).
957 /// Tries to resolve \a orig_spec by checking the module source path
958 /// remappings. It makes sure the file exists, so this call can be expensive
959 /// if the remappings are on a network file system, so use this function
960 /// sparingly (not in a tight debug info parsing loop).
962 /// @param[in] orig_spec
963 /// The original source file path to try and remap.
965 /// @param[out] new_spec
966 /// The newly remapped filespec that is guaranteed to exist.
969 /// /b true if \a orig_spec was successfully located and
970 /// \a new_spec is filled in with an existing file spec,
971 /// \b false otherwise.
972 //------------------------------------------------------------------
973 bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
975 //------------------------------------------------------------------
976 /// Remaps a source file given \a path into \a new_path.
978 /// Remaps \a path if any source remappings match. This function does NOT
979 /// stat the file system so it can be used in tight loops where debug info
983 /// The original source file path to try and remap.
985 /// @param[out] new_path
986 /// The newly remapped filespec that is may or may not exist.
989 /// /b true if \a path was successfully located and \a new_path
990 /// is filled in with a new source path, \b false otherwise.
991 //------------------------------------------------------------------
992 bool RemapSourceFile(llvm::StringRef path, std::string &new_path) const;
993 bool RemapSourceFile(const char *, std::string &) const = delete;
995 //----------------------------------------------------------------------
996 /// @class LookupInfo Module.h "lldb/Core/Module.h"
997 /// A class that encapsulates name lookup information.
999 /// Users can type a wide variety of partial names when setting breakpoints
1000 /// by name or when looking for functions by name. SymbolVendor and
1001 /// SymbolFile objects are only required to implement name lookup for
1002 /// function basenames and for fully mangled names. This means if the user
1003 /// types in a partial name, we must reduce this to a name lookup that will
1004 /// work with all SymbolFile objects. So we might reduce a name lookup to
1005 /// look for a basename, and then prune out any results that don't match.
1007 /// The "m_name" member variable represents the name as it was typed by the
1008 /// user. "m_lookup_name" will be the name we actually search for through
1009 /// the symbol or objects files. Lanaguage is included in case we need to
1010 /// filter results by language at a later date. The "m_name_type_mask"
1011 /// member variable tells us what kinds of names we are looking for and can
1012 /// help us prune out unwanted results.
1014 /// Function lookups are done in Module.cpp, ModuleList.cpp and in
1015 /// BreakpointResolverName.cpp and they all now use this class to do lookups
1017 //----------------------------------------------------------------------
1021 : m_name(), m_lookup_name(), m_language(lldb::eLanguageTypeUnknown),
1022 m_name_type_mask(lldb::eFunctionNameTypeNone),
1023 m_match_name_after_lookup(false) {}
1025 LookupInfo(const ConstString &name, lldb::FunctionNameType name_type_mask,
1026 lldb::LanguageType language);
1028 const ConstString &GetName() const { return m_name; }
1030 void SetName(const ConstString &name) { m_name = name; }
1032 const ConstString &GetLookupName() const { return m_lookup_name; }
1034 void SetLookupName(const ConstString &name) { m_lookup_name = name; }
1036 lldb::FunctionNameType GetNameTypeMask() const { return m_name_type_mask; }
1038 void SetNameTypeMask(lldb::FunctionNameType mask) {
1039 m_name_type_mask = mask;
1042 void Prune(SymbolContextList &sc_list, size_t start_idx) const;
1045 /// What the user originally typed
1048 /// The actual name will lookup when calling in the object or symbol file
1049 ConstString m_lookup_name;
1051 /// Limit matches to only be for this language
1052 lldb::LanguageType m_language;
1054 /// One or more bits from lldb::FunctionNameType that indicate what kind of
1055 /// names we are looking for
1056 lldb::FunctionNameType m_name_type_mask;
1058 ///< If \b true, then demangled names that match will need to contain
1059 ///< "m_name" in order to be considered a match
1060 bool m_match_name_after_lookup;
1064 //------------------------------------------------------------------
1066 //------------------------------------------------------------------
1067 mutable std::recursive_mutex m_mutex; ///< A mutex to keep this object happy
1068 ///in multi-threaded environments.
1070 /// The modification time for this module when it was created.
1071 llvm::sys::TimePoint<> m_mod_time;
1073 ArchSpec m_arch; ///< The architecture for this module.
1074 UUID m_uuid; ///< Each module is assumed to have a unique identifier to help
1075 ///match it up to debug symbols.
1076 FileSpec m_file; ///< The file representation on disk for this module (if
1078 FileSpec m_platform_file; ///< The path to the module on the platform on which
1079 ///it is being debugged
1080 FileSpec m_remote_install_file; ///< If set when debugging on remote
1081 ///platforms, this module will be installed at
1083 FileSpec m_symfile_spec; ///< If this path is valid, then this is the file
1084 ///that _will_ be used as the symbol file for this
1086 ConstString m_object_name; ///< The name an object within this module that is
1087 ///selected, or empty of the module is represented
1089 uint64_t m_object_offset;
1090 llvm::sys::TimePoint<> m_object_mod_time;
1091 lldb::ObjectFileSP m_objfile_sp; ///< A shared pointer to the object file
1092 ///parser for this module as it may or may
1093 ///not be shared with the SymbolFile
1094 lldb::SymbolVendorUP
1095 m_symfile_ap; ///< A pointer to the symbol vendor for this module.
1096 std::vector<lldb::SymbolVendorUP>
1097 m_old_symfiles; ///< If anyone calls Module::SetSymbolFileFileSpec() and
1098 ///changes the symbol file,
1099 ///< we need to keep all old symbol files around in case anyone has type
1100 ///references to them
1101 TypeSystemMap m_type_system_map; ///< A map of any type systems associated
1103 PathMappingList m_source_mappings; ///< Module specific source remappings for
1104 ///when you have debug info for a module
1105 ///that doesn't match where the sources
1107 lldb::SectionListUP m_sections_ap; ///< Unified section list for module that
1108 ///is used by the ObjectFile and and
1109 ///ObjectFile instances for the debug info
1111 std::atomic<bool> m_did_load_objfile{false};
1112 std::atomic<bool> m_did_load_symbol_vendor{false};
1113 std::atomic<bool> m_did_set_uuid{false};
1114 mutable bool m_file_has_changed : 1,
1115 m_first_file_changed_log : 1; /// See if the module was modified after it
1116 /// was initially opened.
1118 //------------------------------------------------------------------
1119 /// Resolve a file or load virtual address.
1121 /// Tries to resolve \a vm_addr as a file address (if \a
1122 /// vm_addr_is_file_addr is true) or as a load address if \a
1123 /// vm_addr_is_file_addr is false) in the symbol vendor. \a resolve_scope
1124 /// indicates what clients wish to resolve and can be used to limit the
1125 /// scope of what is parsed.
1127 /// @param[in] vm_addr
1128 /// The load virtual address to resolve.
1130 /// @param[in] vm_addr_is_file_addr
1131 /// If \b true, \a vm_addr is a file address, else \a vm_addr
1132 /// if a load address.
1134 /// @param[in] resolve_scope
1135 /// The scope that should be resolved (see
1136 /// SymbolContext::Scope).
1138 /// @param[out] so_addr
1139 /// The section offset based address that got resolved if
1140 /// any bits are returned.
1143 // The symbol context that has objects filled in. Each bit
1144 /// in the \a resolve_scope pertains to a member in the \a sc.
1147 /// A integer that contains SymbolContext::Scope bits set for
1148 /// each item that was successfully resolved.
1150 /// @see SymbolContext::Scope
1151 //------------------------------------------------------------------
1152 uint32_t ResolveSymbolContextForAddress(lldb::addr_t vm_addr,
1153 bool vm_addr_is_file_addr,
1154 lldb::SymbolContextItem resolve_scope,
1155 Address &so_addr, SymbolContext &sc);
1157 void SymbolIndicesToSymbolContextList(Symtab *symtab,
1158 std::vector<uint32_t> &symbol_indexes,
1159 SymbolContextList &sc_list);
1161 bool SetArchitecture(const ArchSpec &new_arch);
1163 void SetUUID(const lldb_private::UUID &uuid);
1165 SectionList *GetUnifiedSectionList();
1167 friend class ModuleList;
1168 friend class ObjectFile;
1169 friend class SymbolFile;
1172 Module(); // Only used internally by CreateJITModule ()
1174 size_t FindTypes_Impl(
1175 const ConstString &name, const CompilerDeclContext *parent_decl_ctx,
1176 bool append, size_t max_matches,
1177 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
1180 DISALLOW_COPY_AND_ASSIGN(Module);
1183 } // namespace lldb_private
1185 #endif // liblldb_Module_h_