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/ModuleSpec.h" // for ModuleSpec
15 #include "lldb/Symbol/ObjectFile.h" // for ObjectFile
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" // for ConstString
21 #include "lldb/Utility/FileSpec.h"
22 #include "lldb/Utility/Status.h" // for Status
23 #include "lldb/Utility/UUID.h"
24 #include "lldb/lldb-defines.h" // for DISALLOW_COPY_AND_ASSIGN
25 #include "lldb/lldb-enumerations.h" // for LanguageType, SymbolType
26 #include "lldb/lldb-forward.h"
27 #include "lldb/lldb-types.h" // for addr_t, offset_t
29 #include "llvm/ADT/DenseSet.h"
30 #include "llvm/ADT/StringRef.h"
31 #include "llvm/Support/Chrono.h"
34 #include <memory> // for enable_shared_from_this
36 #include <stddef.h> // for size_t
37 #include <stdint.h> // for uint32_t, uint64_t
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 (!module_sp->m_objfile_sp->GetArchitecture(module_sp->m_arch))
177 //------------------------------------------------------------------
179 //------------------------------------------------------------------
182 bool MatchesModuleSpec(const ModuleSpec &module_ref);
184 //------------------------------------------------------------------
185 /// Set the load address for all sections in a module to be the file address
188 /// Many times a module will be loaded in a target with a constant offset
189 /// applied to all top level sections. This function can set the load
190 /// address for all top level sections to be the section file address +
193 /// @param[in] target
194 /// The target in which to apply the section load addresses.
197 /// if \a value_is_offset is true, then value is the offset to
198 /// apply to all file addresses for all top level sections in
199 /// the object file as each section load address is being set.
200 /// If \a value_is_offset is false, then "value" is the new
201 /// absolute base address for the image.
203 /// @param[in] value_is_offset
204 /// If \b true, then \a value is an offset to apply to each
205 /// file address of each top level section.
206 /// If \b false, then \a value is the image base address that
207 /// will be used to rigidly slide all loadable sections.
209 /// @param[out] changed
210 /// If any section load addresses were changed in \a target,
211 /// then \a changed will be set to \b true. Else \a changed
212 /// will be set to false. This allows this function to be
213 /// called multiple times on the same module for the same
214 /// target. If the module hasn't moved, then \a changed will
215 /// be false and no module updated notification will need to
219 /// /b True if any sections were successfully loaded in \a target,
220 /// /b false otherwise.
221 //------------------------------------------------------------------
222 bool SetLoadAddress(Target &target, lldb::addr_t value, bool value_is_offset,
225 //------------------------------------------------------------------
226 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
228 /// @see SymbolContextScope
229 //------------------------------------------------------------------
230 void CalculateSymbolContext(SymbolContext *sc) override;
232 lldb::ModuleSP CalculateSymbolContextModule() override;
235 GetDescription(Stream *s,
236 lldb::DescriptionLevel level = lldb::eDescriptionLevelFull);
238 //------------------------------------------------------------------
239 /// Get the module path and object name.
241 /// Modules can refer to object files. In this case the specification is
242 /// simple and would return the path to the file:
244 /// "/usr/lib/foo.dylib"
246 /// Modules can be .o files inside of a BSD archive (.a file). In this case,
247 /// the object specification will look like:
249 /// "/usr/lib/foo.a(bar.o)"
251 /// There are many places where logging wants to log this fully qualified
252 /// specification, so we centralize this functionality here.
255 /// The object path + object name if there is one.
256 //------------------------------------------------------------------
257 std::string GetSpecificationDescription() const;
259 //------------------------------------------------------------------
260 /// Dump a description of this object to a Stream.
262 /// Dump a description of the contents of this object to the supplied stream
263 /// \a s. The dumped content will be only what has been loaded or parsed up
264 /// to this point at which this function is called, so this is a good way to
265 /// see what has been parsed in a module.
268 /// The stream to which to dump the object description.
269 //------------------------------------------------------------------
270 void Dump(Stream *s);
272 //------------------------------------------------------------------
273 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
275 /// @see SymbolContextScope
276 //------------------------------------------------------------------
277 void DumpSymbolContext(Stream *s) override;
279 //------------------------------------------------------------------
280 /// Find a symbol in the object file's symbol table.
283 /// The name of the symbol that we are looking for.
285 /// @param[in] symbol_type
286 /// If set to eSymbolTypeAny, find a symbol of any type that
287 /// has a name that matches \a name. If set to any other valid
288 /// SymbolType enumeration value, then search only for
289 /// symbols that match \a symbol_type.
292 /// Returns a valid symbol pointer if a symbol was found,
293 /// nullptr otherwise.
294 //------------------------------------------------------------------
295 const Symbol *FindFirstSymbolWithNameAndType(
296 const ConstString &name,
297 lldb::SymbolType symbol_type = lldb::eSymbolTypeAny);
299 size_t FindSymbolsWithNameAndType(const ConstString &name,
300 lldb::SymbolType symbol_type,
301 SymbolContextList &sc_list);
303 size_t FindSymbolsMatchingRegExAndType(const RegularExpression ®ex,
304 lldb::SymbolType symbol_type,
305 SymbolContextList &sc_list);
307 //------------------------------------------------------------------
308 /// Find a function symbols in the object file's symbol table.
311 /// The name of the symbol that we are looking for.
313 /// @param[in] name_type_mask
314 /// A mask that has one or more bitwise OR'ed values from the
315 /// lldb::FunctionNameType enumeration type that indicate what
316 /// kind of names we are looking for.
318 /// @param[out] sc_list
319 /// A list to append any matching symbol contexts to.
322 /// The number of symbol contexts that were added to \a sc_list
323 //------------------------------------------------------------------
324 size_t FindFunctionSymbols(const ConstString &name, uint32_t name_type_mask,
325 SymbolContextList &sc_list);
327 //------------------------------------------------------------------
328 /// Find compile units by partial or full path.
330 /// Finds all compile units that match \a path in all of the modules and
331 /// returns the results in \a sc_list.
334 /// The name of the function we are looking for.
336 /// @param[in] append
337 /// If \b true, then append any compile units that were found
338 /// to \a sc_list. If \b false, then the \a sc_list is cleared
339 /// and the contents of \a sc_list are replaced.
341 /// @param[out] sc_list
342 /// A symbol context list that gets filled in with all of the
346 /// The number of matches added to \a sc_list.
347 //------------------------------------------------------------------
348 size_t FindCompileUnits(const FileSpec &path, bool append,
349 SymbolContextList &sc_list);
351 //------------------------------------------------------------------
352 /// Find functions by name.
354 /// If the function is an inlined function, it will have a block,
355 /// representing the inlined function, and the function will be the
356 /// containing function. If it is not inlined, then the block will be NULL.
359 /// The name of the compile unit we are looking for.
361 /// @param[in] namespace_decl
362 /// If valid, a namespace to search in.
364 /// @param[in] name_type_mask
365 /// A bit mask of bits that indicate what kind of names should
366 /// be used when doing the lookup. Bits include fully qualified
367 /// names, base names, C++ methods, or ObjC selectors.
368 /// See FunctionNameType for more details.
370 /// @param[in] append
371 /// If \b true, any matches will be appended to \a sc_list, else
372 /// matches replace the contents of \a sc_list.
374 /// @param[out] sc_list
375 /// A symbol context list that gets filled in with all of the
379 /// The number of matches added to \a sc_list.
380 //------------------------------------------------------------------
381 size_t FindFunctions(const ConstString &name,
382 const CompilerDeclContext *parent_decl_ctx,
383 uint32_t name_type_mask, bool symbols_ok,
384 bool inlines_ok, bool append,
385 SymbolContextList &sc_list);
387 //------------------------------------------------------------------
388 /// Find functions by name.
390 /// If the function is an inlined function, it will have a block,
391 /// representing the inlined function, and the function will be the
392 /// containing function. If it is not inlined, then the block will be NULL.
395 /// A regular expression to use when matching the name.
397 /// @param[in] append
398 /// If \b true, any matches will be appended to \a sc_list, else
399 /// matches replace the contents of \a sc_list.
401 /// @param[out] sc_list
402 /// A symbol context list that gets filled in with all of the
406 /// The number of matches added to \a sc_list.
407 //------------------------------------------------------------------
408 size_t FindFunctions(const RegularExpression ®ex, bool symbols_ok,
409 bool inlines_ok, bool append,
410 SymbolContextList &sc_list);
412 //------------------------------------------------------------------
413 /// Find addresses by file/line
415 /// @param[in] target_sp
416 /// The target the addresses are desired for.
419 /// Source file to locate.
422 /// Source line to locate.
424 /// @param[in] function
425 /// Optional filter function. Addresses within this function will be
426 /// added to the 'local' list. All others will be added to the 'extern'
429 /// @param[out] output_local
430 /// All matching addresses within 'function'
432 /// @param[out] output_extern
433 /// All matching addresses not within 'function'
434 void FindAddressesForLine(const lldb::TargetSP target_sp,
435 const FileSpec &file, uint32_t line,
437 std::vector<Address> &output_local,
438 std::vector<Address> &output_extern);
440 //------------------------------------------------------------------
441 /// Find global and static variables by name.
444 /// The name of the global or static variable we are looking
447 /// @param[in] parent_decl_ctx
448 /// If valid, a decl context that results must exist within
450 /// @param[in] max_matches
451 /// Allow the number of matches to be limited to \a
452 /// max_matches. Specify UINT32_MAX to get all possible matches.
454 /// @param[in] variable_list
455 /// A list of variables that gets the matches appended to.
458 /// The number of matches added to \a variable_list.
459 //------------------------------------------------------------------
460 size_t FindGlobalVariables(const ConstString &name,
461 const CompilerDeclContext *parent_decl_ctx,
462 size_t max_matches, VariableList &variable_list);
464 //------------------------------------------------------------------
465 /// Find global and static variables by regular expression.
468 /// A regular expression to use when matching the name.
470 /// @param[in] max_matches
471 /// Allow the number of matches to be limited to \a
472 /// max_matches. Specify UINT32_MAX to get all possible matches.
474 /// @param[in] variable_list
475 /// A list of variables that gets the matches appended to.
478 /// The number of matches added to \a variable_list.
479 //------------------------------------------------------------------
480 size_t FindGlobalVariables(const RegularExpression ®ex, size_t max_matches,
481 VariableList &variable_list);
483 //------------------------------------------------------------------
484 /// Find types by name.
486 /// Type lookups in modules go through the SymbolVendor (which will use one
487 /// or more SymbolFile subclasses). The SymbolFile needs to be able to
488 /// lookup types by basename and not the fully qualified typename. This
489 /// allows the type accelerator tables to stay small, even with heavily
490 /// templatized C++. The type search will then narrow down the search
491 /// results. If "exact_match" is true, then the type search will only match
492 /// exact type name matches. If "exact_match" is false, the type will match
493 /// as long as the base typename matches and as long as any immediate
494 /// containing namespaces/class scopes that are specified match. So to
495 /// search for a type "d" in "b::c", the name "b::c::d" can be specified and
496 /// it will match any class/namespace "b" which contains a class/namespace
497 /// "c" which contains type "d". We do this to allow users to not always
498 /// have to specify complete scoping on all expressions, but it also allows
499 /// for exact matching when required.
502 /// A symbol context that scopes where to extract a type list
505 /// @param[in] type_name
506 /// The name of the type we are looking for that is a fully
507 /// or partially qualified type name.
509 /// @param[in] exact_match
510 /// If \b true, \a type_name is fully qualified and must match
511 /// exactly. If \b false, \a type_name is a partially qualified
512 /// name where the leading namespaces or classes can be
513 /// omitted to make finding types that a user may type
516 /// @param[out] type_list
517 /// A type list gets populated with any matches.
520 /// The number of matches added to \a type_list.
521 //------------------------------------------------------------------
523 FindTypes(const SymbolContext &sc, const ConstString &type_name,
524 bool exact_match, size_t max_matches,
525 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
528 lldb::TypeSP FindFirstType(const SymbolContext &sc,
529 const ConstString &type_name, bool exact_match);
531 //------------------------------------------------------------------
532 /// Find types by name that are in a namespace. This function is used by the
533 /// expression parser when searches need to happen in an exact namespace
537 /// A symbol context that scopes where to extract a type list
540 /// @param[in] type_name
541 /// The name of a type within a namespace that should not include
542 /// any qualifying namespaces (just a type basename).
544 /// @param[in] namespace_decl
545 /// The namespace declaration that this type must exist in.
547 /// @param[out] type_list
548 /// A type list gets populated with any matches.
551 /// The number of matches added to \a type_list.
552 //------------------------------------------------------------------
553 size_t FindTypesInNamespace(const SymbolContext &sc,
554 const ConstString &type_name,
555 const CompilerDeclContext *parent_decl_ctx,
556 size_t max_matches, TypeList &type_list);
558 //------------------------------------------------------------------
559 /// Get const accessor for the module architecture.
562 /// A const reference to the architecture object.
563 //------------------------------------------------------------------
564 const ArchSpec &GetArchitecture() const;
566 //------------------------------------------------------------------
567 /// Get const accessor for the module file specification.
569 /// This function returns the file for the module on the host system that is
570 /// running LLDB. This can differ from the path on the platform since we
571 /// might be doing remote debugging.
574 /// A const reference to the file specification object.
575 //------------------------------------------------------------------
576 const FileSpec &GetFileSpec() const { return m_file; }
578 //------------------------------------------------------------------
579 /// Get accessor for the module platform file specification.
581 /// Platform file refers to the path of the module as it is known on the
582 /// remote system on which it is being debugged. For local debugging this is
583 /// always the same as Module::GetFileSpec(). But remote debugging might
584 /// mention a file "/usr/lib/liba.dylib" which might be locally downloaded
585 /// and cached. In this case the platform file could be something like:
586 /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" The
587 /// file could also be cached in a local developer kit directory.
590 /// A const reference to the file specification object.
591 //------------------------------------------------------------------
592 const FileSpec &GetPlatformFileSpec() const {
594 return m_platform_file;
598 void SetPlatformFileSpec(const FileSpec &file) { m_platform_file = file; }
600 const FileSpec &GetRemoteInstallFileSpec() const {
601 return m_remote_install_file;
604 void SetRemoteInstallFileSpec(const FileSpec &file) {
605 m_remote_install_file = file;
608 const FileSpec &GetSymbolFileFileSpec() const { return m_symfile_spec; }
610 void PreloadSymbols();
612 void SetSymbolFileFileSpec(const FileSpec &file);
614 const llvm::sys::TimePoint<> &GetModificationTime() const {
618 const llvm::sys::TimePoint<> &GetObjectModificationTime() const {
619 return m_object_mod_time;
622 void SetObjectModificationTime(const llvm::sys::TimePoint<> &mod_time) {
623 m_mod_time = mod_time;
626 //------------------------------------------------------------------
627 /// Tells whether this module is capable of being the main executable for a
631 /// \b true if it is, \b false otherwise.
632 //------------------------------------------------------------------
635 //------------------------------------------------------------------
636 /// Tells whether this module has been loaded in the target passed in. This
637 /// call doesn't distinguish between whether the module is loaded by the
638 /// dynamic loader, or by a "target module add" type call.
640 /// @param[in] target
641 /// The target to check whether this is loaded in.
644 /// \b true if it is, \b false otherwise.
645 //------------------------------------------------------------------
646 bool IsLoadedInTarget(Target *target);
648 bool LoadScriptingResourceInTarget(Target *target, Status &error,
649 Stream *feedback_stream = nullptr);
651 //------------------------------------------------------------------
652 /// Get the number of compile units for this module.
655 /// The number of compile units that the symbol vendor plug-in
657 //------------------------------------------------------------------
658 size_t GetNumCompileUnits();
660 lldb::CompUnitSP GetCompileUnitAtIndex(size_t idx);
662 const ConstString &GetObjectName() const;
664 uint64_t GetObjectOffset() const { return m_object_offset; }
666 //------------------------------------------------------------------
667 /// Get the object file representation for the current architecture.
669 /// If the object file has not been located or parsed yet, this function
670 /// will find the best ObjectFile plug-in that can parse Module::m_file.
673 /// If Module::m_file does not exist, or no plug-in was found
674 /// that can parse the file, or the object file doesn't contain
675 /// the current architecture in Module::m_arch, nullptr will be
676 /// returned, else a valid object file interface will be
677 /// returned. The returned pointer is owned by this object and
678 /// remains valid as long as the object is around.
679 //------------------------------------------------------------------
680 virtual ObjectFile *GetObjectFile();
682 //------------------------------------------------------------------
683 /// Get the unified section list for the module. This is the section list
684 /// created by the module's object file and any debug info and symbol files
685 /// created by the symbol vendor.
687 /// If the symbol vendor has not been loaded yet, this function will return
688 /// the section list for the object file.
691 /// Unified module section list.
692 //------------------------------------------------------------------
693 virtual SectionList *GetSectionList();
695 //------------------------------------------------------------------
696 /// Notify the module that the file addresses for the Sections have been
699 /// If the Section file addresses for a module are updated, this method
700 /// should be called. Any parts of the module, object file, or symbol file
701 /// that has cached those file addresses must invalidate or update its
703 //------------------------------------------------------------------
704 virtual void SectionFileAddressesChanged();
706 llvm::VersionTuple GetVersion();
708 //------------------------------------------------------------------
709 /// Load an object file from memory.
711 /// If available, the size of the object file in memory may be passed to
712 /// avoid additional round trips to process memory. If the size is not
713 /// provided, a default value is used. This value should be large enough to
714 /// enable the ObjectFile plugins to read the header of the object file
715 /// without going back to the process.
718 /// The object file loaded from memory or nullptr, if the operation
719 /// failed (see the `error` for more information in that case).
720 //------------------------------------------------------------------
721 ObjectFile *GetMemoryObjectFile(const lldb::ProcessSP &process_sp,
722 lldb::addr_t header_addr, Status &error,
723 size_t size_to_read = 512);
724 //------------------------------------------------------------------
725 /// Get the symbol vendor interface for the current architecture.
727 /// If the symbol vendor file has not been located yet, this function will
728 /// find the best SymbolVendor plug-in that can use the current object file.
731 /// If this module does not have a valid object file, or no
732 /// plug-in can be found that can use the object file, nullptr will
733 /// be returned, else a valid symbol vendor plug-in interface
734 /// will be returned. The returned pointer is owned by this
735 /// object and remains valid as long as the object is around.
736 //------------------------------------------------------------------
737 virtual SymbolVendor *
738 GetSymbolVendor(bool can_create = true,
739 lldb_private::Stream *feedback_strm = nullptr);
741 //------------------------------------------------------------------
742 /// Get accessor the type list for this module.
745 /// A valid type list pointer, or nullptr if there is no valid
746 /// symbol vendor for this module.
747 //------------------------------------------------------------------
748 TypeList *GetTypeList();
750 //------------------------------------------------------------------
751 /// Get a reference to the UUID value contained in this object.
753 /// If the executable image file doesn't not have a UUID value built into
754 /// the file format, an MD5 checksum of the entire file, or slice of the
755 /// file for the current architecture should be used.
758 /// A const pointer to the internal copy of the UUID value in
759 /// this module if this module has a valid UUID value, NULL
761 //------------------------------------------------------------------
762 const lldb_private::UUID &GetUUID();
764 //------------------------------------------------------------------
765 /// A debugging function that will cause everything in a module to
768 /// All compile units will be parsed, along with all globals and static
769 /// variables and all functions for those compile units. All types, scopes,
770 /// local variables, static variables, global variables, and line tables
771 /// will be parsed. This can be used prior to dumping a module to see a
772 /// complete list of the resulting debug information that gets parsed, or as
773 /// a debug function to ensure that the module can consume all of the debug
774 /// data the symbol vendor provides.
775 //------------------------------------------------------------------
776 void ParseAllDebugSymbols();
778 bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr);
780 //------------------------------------------------------------------
781 /// Resolve the symbol context for the given address.
783 /// Tries to resolve the matching symbol context based on a lookup from the
784 /// current symbol vendor. If the lazy lookup fails, an attempt is made to
785 /// parse the eh_frame section to handle stripped symbols. If this fails,
786 /// an attempt is made to resolve the symbol to the previous address to
787 /// handle the case of a function with a tail call.
789 /// Use properties of the modified SymbolContext to inspect any resolved
790 /// target, module, compilation unit, symbol, function, function block or
791 /// line entry. Use the return value to determine which of these properties
792 /// have been modified.
794 /// @param[in] so_addr
795 /// A load address to resolve.
797 /// @param[in] resolve_scope
798 /// The scope that should be resolved (see SymbolContext::Scope).
799 /// A combination of flags from the enumeration SymbolContextItem
800 /// requesting a resolution depth. Note that the flags that are
801 /// actually resolved may be a superset of the requested flags.
802 /// For instance, eSymbolContextSymbol requires resolution of
803 /// eSymbolContextModule, and eSymbolContextFunction requires
804 /// eSymbolContextSymbol.
807 /// The SymbolContext that is modified based on symbol resolution.
809 /// @param[in] resolve_tail_call_address
810 /// Determines if so_addr should resolve to a symbol in the case
811 /// of a function whose last instruction is a call. In this case,
812 /// the PC can be one past the address range of the function.
815 /// The scope that has been resolved (see SymbolContext::Scope).
817 /// @see SymbolContext::Scope
818 //------------------------------------------------------------------
820 ResolveSymbolContextForAddress(const Address &so_addr, uint32_t resolve_scope,
822 bool resolve_tail_call_address = false);
824 //------------------------------------------------------------------
825 /// Resolve items in the symbol context for a given file and line.
827 /// Tries to resolve \a file_path and \a line to a list of matching symbol
830 /// The line table entries contains addresses that can be used to further
831 /// resolve the values in each match: the function, block, symbol. Care
832 /// should be taken to minimize the amount of information that is requested
833 /// to only what is needed -- typically the module, compile unit, line table
834 /// and line table entry are sufficient.
836 /// @param[in] file_path
837 /// A path to a source file to match. If \a file_path does not
838 /// specify a directory, then this query will match all files
839 /// whose base filename matches. If \a file_path does specify
840 /// a directory, the fullpath to the file must match.
843 /// The source line to match, or zero if just the compile unit
844 /// should be resolved.
846 /// @param[in] check_inlines
847 /// Check for inline file and line number matches. This option
848 /// should be used sparingly as it will cause all line tables
849 /// for every compile unit to be parsed and searched for
850 /// matching inline file entries.
852 /// @param[in] resolve_scope
853 /// The scope that should be resolved (see
854 /// SymbolContext::Scope).
856 /// @param[out] sc_list
857 /// A symbol context list that gets matching symbols contexts
861 /// The number of matches that were added to \a sc_list.
863 /// @see SymbolContext::Scope
864 //------------------------------------------------------------------
865 uint32_t ResolveSymbolContextForFilePath(const char *file_path, uint32_t line,
867 uint32_t resolve_scope,
868 SymbolContextList &sc_list);
870 //------------------------------------------------------------------
871 /// Resolve items in the symbol context for a given file and line.
873 /// Tries to resolve \a file_spec and \a line to a list of matching symbol
876 /// The line table entries contains addresses that can be used to further
877 /// resolve the values in each match: the function, block, symbol. Care
878 /// should be taken to minimize the amount of information that is requested
879 /// to only what is needed -- typically the module, compile unit, line table
880 /// and line table entry are sufficient.
882 /// @param[in] file_spec
883 /// A file spec to a source file to match. If \a file_path does
884 /// not specify a directory, then this query will match all
885 /// files whose base filename matches. If \a file_path does
886 /// specify a directory, the fullpath to the file must match.
889 /// The source line to match, or zero if just the compile unit
890 /// should be resolved.
892 /// @param[in] check_inlines
893 /// Check for inline file and line number matches. This option
894 /// should be used sparingly as it will cause all line tables
895 /// for every compile unit to be parsed and searched for
896 /// matching inline file entries.
898 /// @param[in] resolve_scope
899 /// The scope that should be resolved (see
900 /// SymbolContext::Scope).
902 /// @param[out] sc_list
903 /// A symbol context list that gets filled in with all of the
907 /// A integer that contains SymbolContext::Scope bits set for
908 /// each item that was successfully resolved.
910 /// @see SymbolContext::Scope
911 //------------------------------------------------------------------
912 uint32_t ResolveSymbolContextsForFileSpec(const FileSpec &file_spec,
913 uint32_t line, bool check_inlines,
914 uint32_t resolve_scope,
915 SymbolContextList &sc_list);
917 void SetFileSpecAndObjectName(const FileSpec &file,
918 const ConstString &object_name);
920 bool GetIsDynamicLinkEditor();
922 TypeSystem *GetTypeSystemForLanguage(lldb::LanguageType language);
924 // Special error functions that can do printf style formatting that will
925 // prepend the message with something appropriate for this module (like the
926 // architecture, path and object name (if any)). This centralizes code so
927 // that everyone doesn't need to format their error and log messages on their
928 // own and keeps the output a bit more consistent.
929 void LogMessage(Log *log, const char *format, ...)
930 __attribute__((format(printf, 3, 4)));
932 void LogMessageVerboseBacktrace(Log *log, const char *format, ...)
933 __attribute__((format(printf, 3, 4)));
935 void ReportWarning(const char *format, ...)
936 __attribute__((format(printf, 2, 3)));
938 void ReportError(const char *format, ...)
939 __attribute__((format(printf, 2, 3)));
941 // Only report an error once when the module is first detected to be modified
942 // so we don't spam the console with many messages.
943 void ReportErrorIfModifyDetected(const char *format, ...)
944 __attribute__((format(printf, 2, 3)));
946 //------------------------------------------------------------------
947 // Return true if the file backing this module has changed since the module
948 // was originally created since we saved the initial file modification time
949 // when the module first gets created.
950 //------------------------------------------------------------------
951 bool FileHasChanged() const;
953 //------------------------------------------------------------------
954 // SymbolVendor, SymbolFile and ObjectFile member objects should lock the
955 // module mutex to avoid deadlocks.
956 //------------------------------------------------------------------
957 std::recursive_mutex &GetMutex() const { return m_mutex; }
959 PathMappingList &GetSourceMappingList() { return m_source_mappings; }
961 const PathMappingList &GetSourceMappingList() const {
962 return m_source_mappings;
965 //------------------------------------------------------------------
966 /// Finds a source file given a file spec using the module source path
967 /// remappings (if any).
969 /// Tries to resolve \a orig_spec by checking the module source path
970 /// remappings. It makes sure the file exists, so this call can be expensive
971 /// if the remappings are on a network file system, so use this function
972 /// sparingly (not in a tight debug info parsing loop).
974 /// @param[in] orig_spec
975 /// The original source file path to try and remap.
977 /// @param[out] new_spec
978 /// The newly remapped filespec that is guaranteed to exist.
981 /// /b true if \a orig_spec was successfully located and
982 /// \a new_spec is filled in with an existing file spec,
983 /// \b false otherwise.
984 //------------------------------------------------------------------
985 bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
987 //------------------------------------------------------------------
988 /// Remaps a source file given \a path into \a new_path.
990 /// Remaps \a path if any source remappings match. This function does NOT
991 /// stat the file system so it can be used in tight loops where debug info
995 /// The original source file path to try and remap.
997 /// @param[out] new_path
998 /// The newly remapped filespec that is may or may not exist.
1001 /// /b true if \a path was successfully located and \a new_path
1002 /// is filled in with a new source path, \b false otherwise.
1003 //------------------------------------------------------------------
1004 bool RemapSourceFile(llvm::StringRef path, std::string &new_path) const;
1005 bool RemapSourceFile(const char *, std::string &) const = delete;
1007 //----------------------------------------------------------------------
1008 /// @class LookupInfo Module.h "lldb/Core/Module.h"
1009 /// A class that encapsulates name lookup information.
1011 /// Users can type a wide variety of partial names when setting breakpoints
1012 /// by name or when looking for functions by name. SymbolVendor and
1013 /// SymbolFile objects are only required to implement name lookup for
1014 /// function basenames and for fully mangled names. This means if the user
1015 /// types in a partial name, we must reduce this to a name lookup that will
1016 /// work with all SymbolFile objects. So we might reduce a name lookup to
1017 /// look for a basename, and then prune out any results that don't match.
1019 /// The "m_name" member variable represents the name as it was typed by the
1020 /// user. "m_lookup_name" will be the name we actually search for through
1021 /// the symbol or objects files. Lanaguage is included in case we need to
1022 /// filter results by language at a later date. The "m_name_type_mask"
1023 /// member variable tells us what kinds of names we are looking for and can
1024 /// help us prune out unwanted results.
1026 /// Function lookups are done in Module.cpp, ModuleList.cpp and in
1027 /// BreakpointResolverName.cpp and they all now use this class to do lookups
1029 //----------------------------------------------------------------------
1033 : m_name(), m_lookup_name(), m_language(lldb::eLanguageTypeUnknown),
1034 m_name_type_mask(0), m_match_name_after_lookup(false) {}
1036 LookupInfo(const ConstString &name, uint32_t name_type_mask,
1037 lldb::LanguageType language);
1039 const ConstString &GetName() const { return m_name; }
1041 void SetName(const ConstString &name) { m_name = name; }
1043 const ConstString &GetLookupName() const { return m_lookup_name; }
1045 void SetLookupName(const ConstString &name) { m_lookup_name = name; }
1047 uint32_t GetNameTypeMask() const { return m_name_type_mask; }
1049 void SetNameTypeMask(uint32_t mask) { m_name_type_mask = mask; }
1051 void Prune(SymbolContextList &sc_list, size_t start_idx) const;
1054 ConstString m_name; ///< What the user originally typed
1055 ConstString m_lookup_name; ///< The actual name will lookup when calling in
1056 ///the object or symbol file
1058 m_language; ///< Limit matches to only be for this language
1059 uint32_t m_name_type_mask; ///< One or more bits from lldb::FunctionNameType
1060 ///that indicate what kind of names we are
1062 bool m_match_name_after_lookup; ///< If \b true, then demangled names that
1063 ///match will need to contain "m_name" in
1064 ///order to be considered a match
1068 //------------------------------------------------------------------
1070 //------------------------------------------------------------------
1071 mutable std::recursive_mutex m_mutex; ///< A mutex to keep this object happy
1072 ///in multi-threaded environments.
1074 /// The modification time for this module when it was created.
1075 llvm::sys::TimePoint<> m_mod_time;
1077 ArchSpec m_arch; ///< The architecture for this module.
1078 UUID m_uuid; ///< Each module is assumed to have a unique identifier to help
1079 ///match it up to debug symbols.
1080 FileSpec m_file; ///< The file representation on disk for this module (if
1082 FileSpec m_platform_file; ///< The path to the module on the platform on which
1083 ///it is being debugged
1084 FileSpec m_remote_install_file; ///< If set when debugging on remote
1085 ///platforms, this module will be installed at
1087 FileSpec m_symfile_spec; ///< If this path is valid, then this is the file
1088 ///that _will_ be used as the symbol file for this
1090 ConstString m_object_name; ///< The name an object within this module that is
1091 ///selected, or empty of the module is represented
1093 uint64_t m_object_offset;
1094 llvm::sys::TimePoint<> m_object_mod_time;
1095 lldb::ObjectFileSP m_objfile_sp; ///< A shared pointer to the object file
1096 ///parser for this module as it may or may
1097 ///not be shared with the SymbolFile
1098 lldb::SymbolVendorUP
1099 m_symfile_ap; ///< A pointer to the symbol vendor for this module.
1100 std::vector<lldb::SymbolVendorUP>
1101 m_old_symfiles; ///< If anyone calls Module::SetSymbolFileFileSpec() and
1102 ///changes the symbol file,
1103 ///< we need to keep all old symbol files around in case anyone has type
1104 ///references to them
1105 TypeSystemMap m_type_system_map; ///< A map of any type systems associated
1107 PathMappingList m_source_mappings; ///< Module specific source remappings for
1108 ///when you have debug info for a module
1109 ///that doesn't match where the sources
1111 lldb::SectionListUP m_sections_ap; ///< Unified section list for module that
1112 ///is used by the ObjectFile and and
1113 ///ObjectFile instances for the debug info
1115 std::atomic<bool> m_did_load_objfile{false};
1116 std::atomic<bool> m_did_load_symbol_vendor{false};
1117 std::atomic<bool> m_did_set_uuid{false};
1118 mutable bool m_file_has_changed : 1,
1119 m_first_file_changed_log : 1; /// See if the module was modified after it
1120 /// was initially opened.
1122 //------------------------------------------------------------------
1123 /// Resolve a file or load virtual address.
1125 /// Tries to resolve \a vm_addr as a file address (if \a
1126 /// vm_addr_is_file_addr is true) or as a load address if \a
1127 /// vm_addr_is_file_addr is false) in the symbol vendor. \a resolve_scope
1128 /// indicates what clients wish to resolve and can be used to limit the
1129 /// scope of what is parsed.
1131 /// @param[in] vm_addr
1132 /// The load virtual address to resolve.
1134 /// @param[in] vm_addr_is_file_addr
1135 /// If \b true, \a vm_addr is a file address, else \a vm_addr
1136 /// if a load address.
1138 /// @param[in] resolve_scope
1139 /// The scope that should be resolved (see
1140 /// SymbolContext::Scope).
1142 /// @param[out] so_addr
1143 /// The section offset based address that got resolved if
1144 /// any bits are returned.
1147 // The symbol context that has objects filled in. Each bit
1148 /// in the \a resolve_scope pertains to a member in the \a sc.
1151 /// A integer that contains SymbolContext::Scope bits set for
1152 /// each item that was successfully resolved.
1154 /// @see SymbolContext::Scope
1155 //------------------------------------------------------------------
1156 uint32_t ResolveSymbolContextForAddress(lldb::addr_t vm_addr,
1157 bool vm_addr_is_file_addr,
1158 uint32_t resolve_scope,
1159 Address &so_addr, SymbolContext &sc);
1161 void SymbolIndicesToSymbolContextList(Symtab *symtab,
1162 std::vector<uint32_t> &symbol_indexes,
1163 SymbolContextList &sc_list);
1165 bool SetArchitecture(const ArchSpec &new_arch);
1167 void SetUUID(const lldb_private::UUID &uuid);
1169 SectionList *GetUnifiedSectionList();
1171 friend class ModuleList;
1172 friend class ObjectFile;
1173 friend class SymbolFile;
1176 Module(); // Only used internally by CreateJITModule ()
1178 size_t FindTypes_Impl(
1179 const SymbolContext &sc, const ConstString &name,
1180 const CompilerDeclContext *parent_decl_ctx, bool append,
1182 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
1185 DISALLOW_COPY_AND_ASSIGN(Module);
1188 } // namespace lldb_private
1190 #endif // liblldb_Module_h_