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" // for Address
14 #include "lldb/Core/ArchSpec.h"
15 #include "lldb/Core/ModuleSpec.h" // for ModuleSpec
16 #include "lldb/Symbol/SymbolContextScope.h"
17 #include "lldb/Symbol/TypeSystem.h"
18 #include "lldb/Target/PathMappingList.h"
19 #include "lldb/Utility/ConstString.h" // for ConstString
20 #include "lldb/Utility/FileSpec.h"
21 #include "lldb/Utility/Status.h" // for Status
22 #include "lldb/Utility/UUID.h"
23 #include "lldb/lldb-defines.h" // for DISALLOW_COPY_AND_ASSIGN
24 #include "lldb/lldb-enumerations.h" // for LanguageType, SymbolType
25 #include "lldb/lldb-forward.h"
26 #include "lldb/lldb-types.h" // for addr_t, offset_t
28 #include "llvm/ADT/DenseSet.h"
29 #include "llvm/ADT/StringRef.h"
30 #include "llvm/Support/Chrono.h"
33 #include <memory> // for enable_shared_from_this
35 #include <stddef.h> // for size_t
36 #include <stdint.h> // for uint32_t, uint64_t
40 namespace lldb_private {
41 class CompilerDeclContext;
43 namespace lldb_private {
46 namespace lldb_private {
49 namespace lldb_private {
52 namespace lldb_private {
53 class RegularExpression;
55 namespace lldb_private {
58 namespace lldb_private {
61 namespace lldb_private {
64 namespace lldb_private {
67 namespace lldb_private {
68 class SymbolContextList;
70 namespace lldb_private {
73 namespace lldb_private {
76 namespace lldb_private {
79 namespace lldb_private {
82 namespace lldb_private {
85 namespace lldb_private {
88 namespace lldb_private {
92 namespace lldb_private {
94 //----------------------------------------------------------------------
95 /// @class Module Module.h "lldb/Core/Module.h"
96 /// @brief A class that describes an executable image and its associated
97 /// object and symbol files.
99 /// The module is designed to be able to select a single slice of an
100 /// executable image as it would appear on disk and during program
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
106 /// using the Module::GetObjectFile() is called. The debug symbols
107 /// will only be parsed if the symbol vendor (SymbolVendor) is
108 /// requested using the Module::GetSymbolVendor() is called.
110 /// The module will parse more detailed information as more queries are
112 //----------------------------------------------------------------------
113 class Module : public std::enable_shared_from_this<Module>,
114 public SymbolContextScope {
116 // Static functions that can track the lifetime of module objects.
117 // This is handy because we might have Module objects that are in
118 // shared pointers that aren't in the global module list (from
119 // ModuleList). If this is the case we need to know about it.
120 // The modules in the global list maintained by these functions
121 // can be viewed using the "target modules list" command using the
122 // "--global" (-g for short).
123 static size_t GetNumberAllocatedModules();
125 static Module *GetAllocatedModuleAtIndex(size_t idx);
127 static std::recursive_mutex &GetAllocationModuleCollectionMutex();
129 //------------------------------------------------------------------
130 /// Construct with file specification and architecture.
132 /// Clients that wish to share modules with other targets should
133 /// use ModuleList::GetSharedModule().
135 /// @param[in] file_spec
136 /// The file specification for the on disk representation of
137 /// this executable image.
140 /// The architecture to set as the current architecture in
143 /// @param[in] object_name
144 /// The name of an object in a module used to extract a module
145 /// within a module (.a files and modules that contain multiple
148 /// @param[in] object_offset
149 /// The offset within an existing module used to extract a
150 /// module within a module (.a files and modules that contain
151 /// multiple architectures).
152 //------------------------------------------------------------------
154 const FileSpec &file_spec, const ArchSpec &arch,
155 const ConstString *object_name = nullptr,
156 lldb::offset_t object_offset = 0,
157 const llvm::sys::TimePoint<> &object_mod_time = llvm::sys::TimePoint<>());
159 Module(const ModuleSpec &module_spec);
161 static lldb::ModuleSP
162 CreateJITModule(const lldb::ObjectFileJITDelegateSP &delegate_sp);
164 //------------------------------------------------------------------
166 //------------------------------------------------------------------
169 bool MatchesModuleSpec(const ModuleSpec &module_ref);
171 //------------------------------------------------------------------
172 /// Set the load address for all sections in a module to be the
173 /// file address plus \a slide.
175 /// Many times a module will be loaded in a target with a constant
176 /// offset applied to all top level sections. This function can
177 /// set the load address for all top level sections to be the
178 /// section file address + offset.
180 /// @param[in] target
181 /// The target in which to apply the section load addresses.
184 /// if \a value_is_offset is true, then value is the offset to
185 /// apply to all file addresses for all top level sections in
186 /// the object file as each section load address is being set.
187 /// If \a value_is_offset is false, then "value" is the new
188 /// absolute base address for the image.
190 /// @param[in] value_is_offset
191 /// If \b true, then \a value is an offset to apply to each
192 /// file address of each top level section.
193 /// If \b false, then \a value is the image base address that
194 /// will be used to rigidly slide all loadable sections.
196 /// @param[out] changed
197 /// If any section load addresses were changed in \a target,
198 /// then \a changed will be set to \b true. Else \a changed
199 /// will be set to false. This allows this function to be
200 /// called multiple times on the same module for the same
201 /// target. If the module hasn't moved, then \a changed will
202 /// be false and no module updated notification will need to
206 /// /b True if any sections were successfully loaded in \a target,
207 /// /b false otherwise.
208 //------------------------------------------------------------------
209 bool SetLoadAddress(Target &target, lldb::addr_t value, bool value_is_offset,
212 //------------------------------------------------------------------
213 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
215 /// @see SymbolContextScope
216 //------------------------------------------------------------------
217 void CalculateSymbolContext(SymbolContext *sc) override;
219 lldb::ModuleSP CalculateSymbolContextModule() override;
222 GetDescription(Stream *s,
223 lldb::DescriptionLevel level = lldb::eDescriptionLevelFull);
225 //------------------------------------------------------------------
226 /// Get the module path and object name.
228 /// Modules can refer to object files. In this case the specification
229 /// is simple and would return the path to the file:
231 /// "/usr/lib/foo.dylib"
233 /// Modules can be .o files inside of a BSD archive (.a file). In
234 /// this case, the object specification will look like:
236 /// "/usr/lib/foo.a(bar.o)"
238 /// There are many places where logging wants to log this fully
239 /// qualified specification, so we centralize this functionality
243 /// The object path + object name if there is one.
244 //------------------------------------------------------------------
245 std::string GetSpecificationDescription() const;
247 //------------------------------------------------------------------
248 /// Dump a description of this object to a Stream.
250 /// Dump a description of the contents of this object to the
251 /// supplied stream \a s. The dumped content will be only what has
252 /// been loaded or parsed up to this point at which this function
253 /// is called, so this is a good way to see what has been parsed
257 /// The stream to which to dump the object description.
258 //------------------------------------------------------------------
259 void Dump(Stream *s);
261 //------------------------------------------------------------------
262 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
264 /// @see SymbolContextScope
265 //------------------------------------------------------------------
266 void DumpSymbolContext(Stream *s) override;
268 //------------------------------------------------------------------
269 /// Find a symbol in the object file's symbol table.
272 /// The name of the symbol that we are looking for.
274 /// @param[in] symbol_type
275 /// If set to eSymbolTypeAny, find a symbol of any type that
276 /// has a name that matches \a name. If set to any other valid
277 /// SymbolType enumeration value, then search only for
278 /// symbols that match \a symbol_type.
281 /// Returns a valid symbol pointer if a symbol was found,
282 /// nullptr otherwise.
283 //------------------------------------------------------------------
284 const Symbol *FindFirstSymbolWithNameAndType(
285 const ConstString &name,
286 lldb::SymbolType symbol_type = lldb::eSymbolTypeAny);
288 size_t FindSymbolsWithNameAndType(const ConstString &name,
289 lldb::SymbolType symbol_type,
290 SymbolContextList &sc_list);
292 size_t FindSymbolsMatchingRegExAndType(const RegularExpression ®ex,
293 lldb::SymbolType symbol_type,
294 SymbolContextList &sc_list);
296 //------------------------------------------------------------------
297 /// Find a function symbols in the object file's symbol table.
300 /// The name of the symbol that we are looking for.
302 /// @param[in] name_type_mask
303 /// A mask that has one or more bitwise OR'ed values from the
304 /// lldb::FunctionNameType enumeration type that indicate what
305 /// kind of names we are looking for.
307 /// @param[out] sc_list
308 /// A list to append any matching symbol contexts to.
311 /// The number of symbol contexts that were added to \a sc_list
312 //------------------------------------------------------------------
313 size_t FindFunctionSymbols(const ConstString &name, uint32_t name_type_mask,
314 SymbolContextList &sc_list);
316 //------------------------------------------------------------------
317 /// Find compile units by partial or full path.
319 /// Finds all compile units that match \a path in all of the modules
320 /// and returns the results in \a sc_list.
323 /// The name of the function we are looking for.
325 /// @param[in] append
326 /// If \b true, then append any compile units that were found
327 /// to \a sc_list. If \b false, then the \a sc_list is cleared
328 /// and the contents of \a sc_list are replaced.
330 /// @param[out] sc_list
331 /// A symbol context list that gets filled in with all of the
335 /// The number of matches added to \a sc_list.
336 //------------------------------------------------------------------
337 size_t FindCompileUnits(const FileSpec &path, bool append,
338 SymbolContextList &sc_list);
340 //------------------------------------------------------------------
341 /// Find functions by name.
343 /// If the function is an inlined function, it will have a block,
344 /// representing the inlined function, and the function will be the
345 /// containing function. If it is not inlined, then the block will
349 /// The name of the compile unit we are looking for.
351 /// @param[in] namespace_decl
352 /// If valid, a namespace to search in.
354 /// @param[in] name_type_mask
355 /// A bit mask of bits that indicate what kind of names should
356 /// be used when doing the lookup. Bits include fully qualified
357 /// names, base names, C++ methods, or ObjC selectors.
358 /// See FunctionNameType for more details.
360 /// @param[in] append
361 /// If \b true, any matches will be appended to \a sc_list, else
362 /// matches replace the contents of \a sc_list.
364 /// @param[out] sc_list
365 /// A symbol context list that gets filled in with all of the
369 /// The number of matches added to \a sc_list.
370 //------------------------------------------------------------------
371 size_t FindFunctions(const ConstString &name,
372 const CompilerDeclContext *parent_decl_ctx,
373 uint32_t name_type_mask, bool symbols_ok,
374 bool inlines_ok, bool append,
375 SymbolContextList &sc_list);
377 //------------------------------------------------------------------
378 /// Find functions by name.
380 /// If the function is an inlined function, it will have a block,
381 /// representing the inlined function, and the function will be the
382 /// containing function. If it is not inlined, then the block will
386 /// A regular expression to use when matching the name.
388 /// @param[in] append
389 /// If \b true, any matches will be appended to \a sc_list, else
390 /// matches replace the contents of \a sc_list.
392 /// @param[out] sc_list
393 /// A symbol context list that gets filled in with all of the
397 /// The number of matches added to \a sc_list.
398 //------------------------------------------------------------------
399 size_t FindFunctions(const RegularExpression ®ex, bool symbols_ok,
400 bool inlines_ok, bool append,
401 SymbolContextList &sc_list);
403 //------------------------------------------------------------------
404 /// Find addresses by file/line
406 /// @param[in] target_sp
407 /// The target the addresses are desired for.
410 /// Source file to locate.
413 /// Source line to locate.
415 /// @param[in] function
416 /// Optional filter function. Addresses within this function will be
417 /// added to the 'local' list. All others will be added to the 'extern'
420 /// @param[out] output_local
421 /// All matching addresses within 'function'
423 /// @param[out] output_extern
424 /// All matching addresses not within 'function'
425 void FindAddressesForLine(const lldb::TargetSP target_sp,
426 const FileSpec &file, uint32_t line,
428 std::vector<Address> &output_local,
429 std::vector<Address> &output_extern);
431 //------------------------------------------------------------------
432 /// Find global and static variables by name.
435 /// The name of the global or static variable we are looking
438 /// @param[in] parent_decl_ctx
439 /// If valid, a decl context that results must exist within
441 /// @param[in] append
442 /// If \b true, any matches will be appended to \a
443 /// variable_list, else matches replace the contents of
444 /// \a variable_list.
446 /// @param[in] max_matches
447 /// Allow the number of matches to be limited to \a
448 /// max_matches. Specify UINT32_MAX to get all possible matches.
450 /// @param[in] variable_list
451 /// A list of variables that gets the matches appended to (if
452 /// \a append it \b true), or replace (if \a append is \b false).
455 /// The number of matches added to \a variable_list.
456 //------------------------------------------------------------------
457 size_t FindGlobalVariables(const ConstString &name,
458 const CompilerDeclContext *parent_decl_ctx,
459 bool append, size_t max_matches,
460 VariableList &variable_list);
462 //------------------------------------------------------------------
463 /// Find global and static variables by regular expression.
466 /// A regular expression to use when matching the name.
468 /// @param[in] append
469 /// If \b true, any matches will be appended to \a
470 /// variable_list, else matches replace the contents of
471 /// \a variable_list.
473 /// @param[in] max_matches
474 /// Allow the number of matches to be limited to \a
475 /// max_matches. Specify UINT32_MAX to get all possible matches.
477 /// @param[in] variable_list
478 /// A list of variables that gets the matches appended to (if
479 /// \a append it \b true), or replace (if \a append is \b false).
482 /// The number of matches added to \a variable_list.
483 //------------------------------------------------------------------
484 size_t FindGlobalVariables(const RegularExpression ®ex, bool append,
485 size_t max_matches, VariableList &variable_list);
487 //------------------------------------------------------------------
488 /// Find types by name.
490 /// Type lookups in modules go through the SymbolVendor (which will
491 /// use one or more SymbolFile subclasses). The SymbolFile needs to
492 /// be able to lookup types by basename and not the fully qualified
493 /// typename. This allows the type accelerator tables to stay small,
494 /// even with heavily templatized C++. The type search will then
495 /// narrow down the search results. If "exact_match" is true, then
496 /// the type search will only match exact type name matches. If
497 /// "exact_match" is false, the type will match as long as the base
498 /// typename matches and as long as any immediate containing
499 /// namespaces/class scopes that are specified match. So to search
500 /// for a type "d" in "b::c", the name "b::c::d" can be specified
501 /// and it will match any class/namespace "b" which contains a
502 /// class/namespace "c" which contains type "d". We do this to
503 /// allow users to not always have to specify complete scoping on
504 /// all expressions, but it also allows for exact matching when
508 /// A symbol context that scopes where to extract a type list
511 /// @param[in] type_name
512 /// The name of the type we are looking for that is a fully
513 /// or partially qualified type name.
515 /// @param[in] exact_match
516 /// If \b true, \a type_name is fully qualified and must match
517 /// exactly. If \b false, \a type_name is a partially qualified
518 /// name where the leading namespaces or classes can be
519 /// omitted to make finding types that a user may type
522 /// @param[out] type_list
523 /// A type list gets populated with any matches.
526 /// The number of matches added to \a type_list.
527 //------------------------------------------------------------------
529 FindTypes(const SymbolContext &sc, const ConstString &type_name,
530 bool exact_match, size_t max_matches,
531 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
534 lldb::TypeSP FindFirstType(const SymbolContext &sc,
535 const ConstString &type_name, bool exact_match);
537 //------------------------------------------------------------------
538 /// Find types by name that are in a namespace. This function is
539 /// used by the expression parser when searches need to happen in
540 /// an exact namespace scope.
543 /// A symbol context that scopes where to extract a type list
546 /// @param[in] type_name
547 /// The name of a type within a namespace that should not include
548 /// any qualifying namespaces (just a type basename).
550 /// @param[in] namespace_decl
551 /// The namespace declaration that this type must exist in.
553 /// @param[out] type_list
554 /// A type list gets populated with any matches.
557 /// The number of matches added to \a type_list.
558 //------------------------------------------------------------------
559 size_t FindTypesInNamespace(const SymbolContext &sc,
560 const ConstString &type_name,
561 const CompilerDeclContext *parent_decl_ctx,
562 size_t max_matches, TypeList &type_list);
564 //------------------------------------------------------------------
565 /// Get const accessor for the module architecture.
568 /// A const reference to the architecture object.
569 //------------------------------------------------------------------
570 const ArchSpec &GetArchitecture() const;
572 //------------------------------------------------------------------
573 /// Get const accessor for the module file specification.
575 /// This function returns the file for the module on the host system
576 /// that is running LLDB. This can differ from the path on the
577 /// platform since we might be doing remote debugging.
580 /// A const reference to the file specification object.
581 //------------------------------------------------------------------
582 const FileSpec &GetFileSpec() const { return m_file; }
584 //------------------------------------------------------------------
585 /// Get accessor for the module platform file specification.
587 /// Platform file refers to the path of the module as it is known on
588 /// the remote system on which it is being debugged. For local
589 /// debugging this is always the same as Module::GetFileSpec(). But
590 /// remote debugging might mention a file "/usr/lib/liba.dylib"
591 /// which might be locally downloaded and cached. In this case the
592 /// platform file could be something like:
593 /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib"
594 /// The file could also be cached in a local developer kit directory.
597 /// A const reference to the file specification object.
598 //------------------------------------------------------------------
599 const FileSpec &GetPlatformFileSpec() const {
601 return m_platform_file;
605 void SetPlatformFileSpec(const FileSpec &file) { m_platform_file = file; }
607 const FileSpec &GetRemoteInstallFileSpec() const {
608 return m_remote_install_file;
611 void SetRemoteInstallFileSpec(const FileSpec &file) {
612 m_remote_install_file = file;
615 const FileSpec &GetSymbolFileFileSpec() const { return m_symfile_spec; }
617 void PreloadSymbols();
619 void SetSymbolFileFileSpec(const FileSpec &file);
621 const llvm::sys::TimePoint<> &GetModificationTime() const {
625 const llvm::sys::TimePoint<> &GetObjectModificationTime() const {
626 return m_object_mod_time;
629 void SetObjectModificationTime(const llvm::sys::TimePoint<> &mod_time) {
630 m_mod_time = mod_time;
633 //------------------------------------------------------------------
634 /// Tells whether this module is capable of being the main executable
638 /// \b true if it is, \b false otherwise.
639 //------------------------------------------------------------------
642 //------------------------------------------------------------------
643 /// Tells whether this module has been loaded in the target passed in.
644 /// This call doesn't distinguish between whether the module is loaded
645 /// by the dynamic loader, or by a "target module add" type call.
647 /// @param[in] target
648 /// The target to check whether this is loaded in.
651 /// \b true if it is, \b false otherwise.
652 //------------------------------------------------------------------
653 bool IsLoadedInTarget(Target *target);
655 bool LoadScriptingResourceInTarget(Target *target, Status &error,
656 Stream *feedback_stream = nullptr);
658 //------------------------------------------------------------------
659 /// Get the number of compile units for this module.
662 /// The number of compile units that the symbol vendor plug-in
664 //------------------------------------------------------------------
665 size_t GetNumCompileUnits();
667 lldb::CompUnitSP GetCompileUnitAtIndex(size_t idx);
669 const ConstString &GetObjectName() const;
671 uint64_t GetObjectOffset() const { return m_object_offset; }
673 //------------------------------------------------------------------
674 /// Get the object file representation for the current architecture.
676 /// If the object file has not been located or parsed yet, this
677 /// function will find the best ObjectFile plug-in that can parse
681 /// If Module::m_file does not exist, or no plug-in was found
682 /// that can parse the file, or the object file doesn't contain
683 /// the current architecture in Module::m_arch, nullptr will be
684 /// returned, else a valid object file interface will be
685 /// returned. The returned pointer is owned by this object and
686 /// remains valid as long as the object is around.
687 //------------------------------------------------------------------
688 virtual ObjectFile *GetObjectFile();
690 //------------------------------------------------------------------
691 /// Get the unified section list for the module. This is the section
692 /// list created by the module's object file and any debug info and
693 /// symbol files created by the symbol vendor.
695 /// If the symbol vendor has not been loaded yet, this function
696 /// will return the section list for the object file.
699 /// Unified module section list.
700 //------------------------------------------------------------------
701 virtual SectionList *GetSectionList();
703 //------------------------------------------------------------------
704 /// Notify the module that the file addresses for the Sections have
707 /// If the Section file addresses for a module are updated, this
708 /// method should be called. Any parts of the module, object file,
709 /// or symbol file that has cached those file addresses must invalidate
710 /// or update its cache.
711 //------------------------------------------------------------------
712 virtual void SectionFileAddressesChanged();
714 uint32_t GetVersion(uint32_t *versions, uint32_t num_versions);
716 //------------------------------------------------------------------
717 /// Load an object file from memory.
719 /// If available, the size of the object file in memory may be
720 /// passed to avoid additional round trips to process memory.
721 /// If the size is not provided, a default value is used. This
722 /// value should be large enough to enable the ObjectFile plugins
723 /// to read the header of the object file without going back to the
727 /// The object file loaded from memory or nullptr, if the operation
728 /// failed (see the `error` for more information in that case).
729 //------------------------------------------------------------------
730 ObjectFile *GetMemoryObjectFile(const lldb::ProcessSP &process_sp,
731 lldb::addr_t header_addr, Status &error,
732 size_t size_to_read = 512);
733 //------------------------------------------------------------------
734 /// Get the symbol vendor interface for the current architecture.
736 /// If the symbol vendor file has not been located yet, this
737 /// function will find the best SymbolVendor plug-in that can
738 /// use the current object file.
741 /// If this module does not have a valid object file, or no
742 /// plug-in can be found that can use the object file, nullptr will
743 /// be returned, else a valid symbol vendor plug-in interface
744 /// will be returned. The returned pointer is owned by this
745 /// object and remains valid as long as the object is around.
746 //------------------------------------------------------------------
747 virtual SymbolVendor *
748 GetSymbolVendor(bool can_create = true,
749 lldb_private::Stream *feedback_strm = nullptr);
751 //------------------------------------------------------------------
752 /// Get accessor the type list for this module.
755 /// A valid type list pointer, or nullptr if there is no valid
756 /// symbol vendor for this module.
757 //------------------------------------------------------------------
758 TypeList *GetTypeList();
760 //------------------------------------------------------------------
761 /// Get a pointer to the UUID value contained in this object.
763 /// If the executable image file doesn't not have a UUID value built
764 /// into the file format, an MD5 checksum of the entire file, or
765 /// slice of the file for the current architecture should be used.
768 /// A const pointer to the internal copy of the UUID value in
769 /// this module if this module has a valid UUID value, NULL
771 //------------------------------------------------------------------
772 const lldb_private::UUID &GetUUID();
774 //------------------------------------------------------------------
775 /// A debugging function that will cause everything in a module to
778 /// All compile units will be parsed, along with all globals and
779 /// static variables and all functions for those compile units.
780 /// All types, scopes, local variables, static variables, global
781 /// variables, and line tables will be parsed. This can be used
782 /// prior to dumping a module to see a complete list of the
783 /// resulting debug information that gets parsed, or as a debug
784 /// function to ensure that the module can consume all of the
785 /// debug data the symbol vendor provides.
786 //------------------------------------------------------------------
787 void ParseAllDebugSymbols();
789 bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr);
791 //------------------------------------------------------------------
792 /// Resolve the symbol context for the given address.
794 /// Tries to resolve the matching symbol context based on a lookup
795 /// from the current symbol vendor. If the lazy lookup fails,
796 /// an attempt is made to parse the eh_frame section to handle
797 /// stripped symbols. If this fails, an attempt is made to resolve
798 /// the symbol to the previous address to handle the case of a
799 /// function with a tail call.
801 /// Use properties of the modified SymbolContext to inspect any
802 /// resolved target, module, compilation unit, symbol, function,
803 /// function block or line entry. Use the return value to determine
804 /// which of these properties have been modified.
806 /// @param[in] so_addr
807 /// A load address to resolve.
809 /// @param[in] resolve_scope
810 /// The scope that should be resolved (see SymbolContext::Scope).
811 /// A combination of flags from the enumeration SymbolContextItem
812 /// requesting a resolution depth. Note that the flags that are
813 /// actually resolved may be a superset of the requested flags.
814 /// For instance, eSymbolContextSymbol requires resolution of
815 /// eSymbolContextModule, and eSymbolContextFunction requires
816 /// eSymbolContextSymbol.
819 /// The SymbolContext that is modified based on symbol resolution.
821 /// @param[in] resolve_tail_call_address
822 /// Determines if so_addr should resolve to a symbol in the case
823 /// of a function whose last instruction is a call. In this case,
824 /// the PC can be one past the address range of the function.
827 /// The scope that has been resolved (see SymbolContext::Scope).
829 /// @see SymbolContext::Scope
830 //------------------------------------------------------------------
832 ResolveSymbolContextForAddress(const Address &so_addr, uint32_t resolve_scope,
834 bool resolve_tail_call_address = false);
836 //------------------------------------------------------------------
837 /// Resolve items in the symbol context for a given file and line.
839 /// Tries to resolve \a file_path and \a line to a list of matching
842 /// The line table entries contains addresses that can be used to
843 /// further resolve the values in each match: the function, block,
844 /// symbol. Care should be taken to minimize the amount of
845 /// information that is requested to only what is needed --
846 /// typically the module, compile unit, line table and line table
847 /// entry are sufficient.
849 /// @param[in] file_path
850 /// A path to a source file to match. If \a file_path does not
851 /// specify a directory, then this query will match all files
852 /// whose base filename matches. If \a file_path does specify
853 /// a directory, the fullpath to the file must match.
856 /// The source line to match, or zero if just the compile unit
857 /// should be resolved.
859 /// @param[in] check_inlines
860 /// Check for inline file and line number matches. This option
861 /// should be used sparingly as it will cause all line tables
862 /// for every compile unit to be parsed and searched for
863 /// matching inline file entries.
865 /// @param[in] resolve_scope
866 /// The scope that should be resolved (see
867 /// SymbolContext::Scope).
869 /// @param[out] sc_list
870 /// A symbol context list that gets matching symbols contexts
874 /// The number of matches that were added to \a sc_list.
876 /// @see SymbolContext::Scope
877 //------------------------------------------------------------------
878 uint32_t ResolveSymbolContextForFilePath(const char *file_path, uint32_t line,
880 uint32_t resolve_scope,
881 SymbolContextList &sc_list);
883 //------------------------------------------------------------------
884 /// Resolve items in the symbol context for a given file and line.
886 /// Tries to resolve \a file_spec and \a line to a list of matching
889 /// The line table entries contains addresses that can be used to
890 /// further resolve the values in each match: the function, block,
891 /// symbol. Care should be taken to minimize the amount of
892 /// information that is requested to only what is needed --
893 /// typically the module, compile unit, line table and line table
894 /// entry are sufficient.
896 /// @param[in] file_spec
897 /// A file spec to a source file to match. If \a file_path does
898 /// not specify a directory, then this query will match all
899 /// files whose base filename matches. If \a file_path does
900 /// specify a directory, the fullpath to the file must match.
903 /// The source line to match, or zero if just the compile unit
904 /// should be resolved.
906 /// @param[in] check_inlines
907 /// Check for inline file and line number matches. This option
908 /// should be used sparingly as it will cause all line tables
909 /// for every compile unit to be parsed and searched for
910 /// matching inline file entries.
912 /// @param[in] resolve_scope
913 /// The scope that should be resolved (see
914 /// SymbolContext::Scope).
916 /// @param[out] sc_list
917 /// A symbol context list that gets filled in with all of the
921 /// A integer that contains SymbolContext::Scope bits set for
922 /// each item that was successfully resolved.
924 /// @see SymbolContext::Scope
925 //------------------------------------------------------------------
926 uint32_t ResolveSymbolContextsForFileSpec(const FileSpec &file_spec,
927 uint32_t line, bool check_inlines,
928 uint32_t resolve_scope,
929 SymbolContextList &sc_list);
931 void SetFileSpecAndObjectName(const FileSpec &file,
932 const ConstString &object_name);
934 bool GetIsDynamicLinkEditor();
936 TypeSystem *GetTypeSystemForLanguage(lldb::LanguageType language);
938 // Special error functions that can do printf style formatting that will
939 // prepend the message with
940 // something appropriate for this module (like the architecture, path and
941 // object name (if any)).
942 // This centralizes code so that everyone doesn't need to format their error
943 // and log messages on
944 // their own and keeps the output a bit more consistent.
945 void LogMessage(Log *log, const char *format, ...)
946 __attribute__((format(printf, 3, 4)));
948 void LogMessageVerboseBacktrace(Log *log, const char *format, ...)
949 __attribute__((format(printf, 3, 4)));
951 void ReportWarning(const char *format, ...)
952 __attribute__((format(printf, 2, 3)));
954 void ReportError(const char *format, ...)
955 __attribute__((format(printf, 2, 3)));
957 // Only report an error once when the module is first detected to be modified
958 // so we don't spam the console with many messages.
959 void ReportErrorIfModifyDetected(const char *format, ...)
960 __attribute__((format(printf, 2, 3)));
962 //------------------------------------------------------------------
963 // Return true if the file backing this module has changed since the
964 // module was originally created since we saved the initial file
965 // modification time when the module first gets created.
966 //------------------------------------------------------------------
967 bool FileHasChanged() const;
969 //------------------------------------------------------------------
970 // SymbolVendor, SymbolFile and ObjectFile member objects should
971 // lock the module mutex to avoid deadlocks.
972 //------------------------------------------------------------------
973 std::recursive_mutex &GetMutex() const { return m_mutex; }
975 PathMappingList &GetSourceMappingList() { return m_source_mappings; }
977 const PathMappingList &GetSourceMappingList() const {
978 return m_source_mappings;
981 //------------------------------------------------------------------
982 /// Finds a source file given a file spec using the module source
983 /// path remappings (if any).
985 /// Tries to resolve \a orig_spec by checking the module source path
986 /// remappings. It makes sure the file exists, so this call can be
987 /// expensive if the remappings are on a network file system, so
988 /// use this function sparingly (not in a tight debug info parsing
991 /// @param[in] orig_spec
992 /// The original source file path to try and remap.
994 /// @param[out] new_spec
995 /// The newly remapped filespec that is guaranteed to exist.
998 /// /b true if \a orig_spec was successfully located and
999 /// \a new_spec is filled in with an existing file spec,
1000 /// \b false otherwise.
1001 //------------------------------------------------------------------
1002 bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
1004 //------------------------------------------------------------------
1005 /// Remaps a source file given \a path into \a new_path.
1007 /// Remaps \a path if any source remappings match. This function
1008 /// does NOT stat the file system so it can be used in tight loops
1009 /// where debug info is being parsed.
1012 /// The original source file path to try and remap.
1014 /// @param[out] new_path
1015 /// The newly remapped filespec that is may or may not exist.
1018 /// /b true if \a path was successfully located and \a new_path
1019 /// is filled in with a new source path, \b false otherwise.
1020 //------------------------------------------------------------------
1021 bool RemapSourceFile(llvm::StringRef path, std::string &new_path) const;
1022 bool RemapSourceFile(const char *, std::string &) const = delete;
1024 //------------------------------------------------------------------
1025 /// Loads this module to memory.
1027 /// Loads the bits needed to create an executable image to the memory.
1028 /// It is useful with bare-metal targets where target does not have the
1029 /// ability to start a process itself.
1031 /// @param[in] target
1032 /// Target where to load the module.
1035 //------------------------------------------------------------------
1036 Status LoadInMemory(Target &target, bool set_pc);
1038 //----------------------------------------------------------------------
1039 /// @class LookupInfo Module.h "lldb/Core/Module.h"
1040 /// @brief A class that encapsulates name lookup information.
1042 /// Users can type a wide variety of partial names when setting
1043 /// breakpoints by name or when looking for functions by name.
1044 /// SymbolVendor and SymbolFile objects are only required to implement
1045 /// name lookup for function basenames and for fully mangled names.
1046 /// This means if the user types in a partial name, we must reduce this
1047 /// to a name lookup that will work with all SymbolFile objects. So we
1048 /// might reduce a name lookup to look for a basename, and then prune
1049 /// out any results that don't match.
1051 /// The "m_name" member variable represents the name as it was typed
1052 /// by the user. "m_lookup_name" will be the name we actually search
1053 /// for through the symbol or objects files. Lanaguage is included in
1054 /// case we need to filter results by language at a later date. The
1055 /// "m_name_type_mask" member variable tells us what kinds of names we
1056 /// are looking for and can help us prune out unwanted results.
1058 /// Function lookups are done in Module.cpp, ModuleList.cpp and in
1059 /// BreakpointResolverName.cpp and they all now use this class to do
1060 /// lookups correctly.
1061 //----------------------------------------------------------------------
1065 : m_name(), m_lookup_name(), m_language(lldb::eLanguageTypeUnknown),
1066 m_name_type_mask(0), m_match_name_after_lookup(false) {}
1068 LookupInfo(const ConstString &name, uint32_t name_type_mask,
1069 lldb::LanguageType language);
1071 const ConstString &GetName() const { return m_name; }
1073 void SetName(const ConstString &name) { m_name = name; }
1075 const ConstString &GetLookupName() const { return m_lookup_name; }
1077 void SetLookupName(const ConstString &name) { m_lookup_name = name; }
1079 uint32_t GetNameTypeMask() const { return m_name_type_mask; }
1081 void SetNameTypeMask(uint32_t mask) { m_name_type_mask = mask; }
1083 void Prune(SymbolContextList &sc_list, size_t start_idx) const;
1086 ConstString m_name; ///< What the user originally typed
1087 ConstString m_lookup_name; ///< The actual name will lookup when calling in
1088 ///the object or symbol file
1090 m_language; ///< Limit matches to only be for this language
1091 uint32_t m_name_type_mask; ///< One or more bits from lldb::FunctionNameType
1092 ///that indicate what kind of names we are
1094 bool m_match_name_after_lookup; ///< If \b true, then demangled names that
1095 ///match will need to contain "m_name" in
1096 ///order to be considered a match
1100 //------------------------------------------------------------------
1102 //------------------------------------------------------------------
1103 mutable std::recursive_mutex m_mutex; ///< A mutex to keep this object happy
1104 ///in multi-threaded environments.
1106 /// The modification time for this module when it was created.
1107 llvm::sys::TimePoint<> m_mod_time;
1109 ArchSpec m_arch; ///< The architecture for this module.
1110 UUID m_uuid; ///< Each module is assumed to have a unique identifier to help
1111 ///match it up to debug symbols.
1112 FileSpec m_file; ///< The file representation on disk for this module (if
1114 FileSpec m_platform_file; ///< The path to the module on the platform on which
1115 ///it is being debugged
1116 FileSpec m_remote_install_file; ///< If set when debugging on remote
1117 ///platforms, this module will be installed at
1119 FileSpec m_symfile_spec; ///< If this path is valid, then this is the file
1120 ///that _will_ be used as the symbol file for this
1122 ConstString m_object_name; ///< The name an object within this module that is
1123 ///selected, or empty of the module is represented
1125 uint64_t m_object_offset;
1126 llvm::sys::TimePoint<> m_object_mod_time;
1127 lldb::ObjectFileSP m_objfile_sp; ///< A shared pointer to the object file
1128 ///parser for this module as it may or may
1129 ///not be shared with the SymbolFile
1130 lldb::SymbolVendorUP
1131 m_symfile_ap; ///< A pointer to the symbol vendor for this module.
1132 std::vector<lldb::SymbolVendorUP>
1133 m_old_symfiles; ///< If anyone calls Module::SetSymbolFileFileSpec() and
1134 ///changes the symbol file,
1135 ///< we need to keep all old symbol files around in case anyone has type
1136 ///references to them
1137 TypeSystemMap m_type_system_map; ///< A map of any type systems associated
1139 PathMappingList m_source_mappings; ///< Module specific source remappings for
1140 ///when you have debug info for a module
1141 ///that doesn't match where the sources
1143 lldb::SectionListUP m_sections_ap; ///< Unified section list for module that
1144 ///is used by the ObjectFile and and
1145 ///ObjectFile instances for the debug info
1147 std::atomic<bool> m_did_load_objfile{false};
1148 std::atomic<bool> m_did_load_symbol_vendor{false};
1149 std::atomic<bool> m_did_parse_uuid{false};
1150 mutable bool m_file_has_changed : 1,
1151 m_first_file_changed_log : 1; /// See if the module was modified after it
1152 /// was initially opened.
1154 //------------------------------------------------------------------
1155 /// Resolve a file or load virtual address.
1157 /// Tries to resolve \a vm_addr as a file address (if \a
1158 /// vm_addr_is_file_addr is true) or as a load address if \a
1159 /// vm_addr_is_file_addr is false) in the symbol vendor.
1160 /// \a resolve_scope indicates what clients wish to resolve
1161 /// and can be used to limit the scope of what is parsed.
1163 /// @param[in] vm_addr
1164 /// The load virtual address to resolve.
1166 /// @param[in] vm_addr_is_file_addr
1167 /// If \b true, \a vm_addr is a file address, else \a vm_addr
1168 /// if a load address.
1170 /// @param[in] resolve_scope
1171 /// The scope that should be resolved (see
1172 /// SymbolContext::Scope).
1174 /// @param[out] so_addr
1175 /// The section offset based address that got resolved if
1176 /// any bits are returned.
1179 // The symbol context that has objects filled in. Each bit
1180 /// in the \a resolve_scope pertains to a member in the \a sc.
1183 /// A integer that contains SymbolContext::Scope bits set for
1184 /// each item that was successfully resolved.
1186 /// @see SymbolContext::Scope
1187 //------------------------------------------------------------------
1188 uint32_t ResolveSymbolContextForAddress(lldb::addr_t vm_addr,
1189 bool vm_addr_is_file_addr,
1190 uint32_t resolve_scope,
1191 Address &so_addr, SymbolContext &sc);
1193 void SymbolIndicesToSymbolContextList(Symtab *symtab,
1194 std::vector<uint32_t> &symbol_indexes,
1195 SymbolContextList &sc_list);
1197 bool SetArchitecture(const ArchSpec &new_arch);
1199 SectionList *GetUnifiedSectionList();
1201 friend class ModuleList;
1202 friend class ObjectFile;
1203 friend class SymbolFile;
1206 Module(); // Only used internally by CreateJITModule ()
1208 size_t FindTypes_Impl(
1209 const SymbolContext &sc, const ConstString &name,
1210 const CompilerDeclContext *parent_decl_ctx, bool append,
1212 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
1215 DISALLOW_COPY_AND_ASSIGN(Module);
1218 } // namespace lldb_private
1220 #endif // liblldb_Module_h_