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_
20 // Other libraries and framework includes
22 #include "lldb/lldb-forward.h"
23 #include "lldb/Core/ArchSpec.h"
24 #include "lldb/Core/UUID.h"
25 #include "lldb/Host/FileSpec.h"
26 #include "lldb/Host/TimeValue.h"
27 #include "lldb/Symbol/SymbolContextScope.h"
28 #include "lldb/Symbol/TypeSystem.h"
29 #include "lldb/Target/PathMappingList.h"
30 #include "llvm/ADT/DenseSet.h"
32 namespace lldb_private {
34 //----------------------------------------------------------------------
35 /// @class Module Module.h "lldb/Core/Module.h"
36 /// @brief A class that describes an executable image and its associated
37 /// object and symbol files.
39 /// The module is designed to be able to select a single slice of an
40 /// executable image as it would appear on disk and during program
43 /// Modules control when and if information is parsed according to which
44 /// accessors are called. For example the object file (ObjectFile)
45 /// representation will only be parsed if the object file is requested
46 /// using the Module::GetObjectFile() is called. The debug symbols
47 /// will only be parsed if the symbol vendor (SymbolVendor) is
48 /// requested using the Module::GetSymbolVendor() is called.
50 /// The module will parse more detailed information as more queries are
52 //----------------------------------------------------------------------
54 public std::enable_shared_from_this<Module>,
55 public SymbolContextScope
58 // Static functions that can track the lifetime of module objects.
59 // This is handy because we might have Module objects that are in
60 // shared pointers that aren't in the global module list (from
61 // ModuleList). If this is the case we need to know about it.
62 // The modules in the global list maintained by these functions
63 // can be viewed using the "target modules list" command using the
64 // "--global" (-g for short).
66 GetNumberAllocatedModules ();
69 GetAllocatedModuleAtIndex (size_t idx);
71 static std::recursive_mutex &
72 GetAllocationModuleCollectionMutex();
74 //------------------------------------------------------------------
75 /// Construct with file specification and architecture.
77 /// Clients that wish to share modules with other targets should
78 /// use ModuleList::GetSharedModule().
80 /// @param[in] file_spec
81 /// The file specification for the on disk representation of
82 /// this executable image.
85 /// The architecture to set as the current architecture in
88 /// @param[in] object_name
89 /// The name of an object in a module used to extract a module
90 /// within a module (.a files and modules that contain multiple
93 /// @param[in] object_offset
94 /// The offset within an existing module used to extract a
95 /// module within a module (.a files and modules that contain
96 /// multiple architectures).
97 //------------------------------------------------------------------
98 Module(const FileSpec& file_spec,
100 const ConstString *object_name = nullptr,
101 lldb::offset_t object_offset = 0,
102 const TimeValue *object_mod_time_ptr = nullptr);
104 Module (const ModuleSpec &module_spec);
106 static lldb::ModuleSP
107 CreateJITModule (const lldb::ObjectFileJITDelegateSP &delegate_sp);
109 //------------------------------------------------------------------
111 //------------------------------------------------------------------
115 MatchesModuleSpec (const ModuleSpec &module_ref);
117 //------------------------------------------------------------------
118 /// Set the load address for all sections in a module to be the
119 /// file address plus \a slide.
121 /// Many times a module will be loaded in a target with a constant
122 /// offset applied to all top level sections. This function can
123 /// set the load address for all top level sections to be the
124 /// section file address + offset.
126 /// @param[in] target
127 /// The target in which to apply the section load addresses.
130 /// if \a value_is_offset is true, then value is the offset to
131 /// apply to all file addresses for all top level sections in
132 /// the object file as each section load address is being set.
133 /// If \a value_is_offset is false, then "value" is the new
134 /// absolute base address for the image.
136 /// @param[in] value_is_offset
137 /// If \b true, then \a value is an offset to apply to each
138 /// file address of each top level section.
139 /// If \b false, then \a value is the image base address that
140 /// will be used to rigidly slide all loadable sections.
142 /// @param[out] changed
143 /// If any section load addresses were changed in \a target,
144 /// then \a changed will be set to \b true. Else \a changed
145 /// will be set to false. This allows this function to be
146 /// called multiple times on the same module for the same
147 /// target. If the module hasn't moved, then \a changed will
148 /// be false and no module updated notification will need to
152 /// /b True if any sections were successfully loaded in \a target,
153 /// /b false otherwise.
154 //------------------------------------------------------------------
156 SetLoadAddress (Target &target,
158 bool value_is_offset,
161 //------------------------------------------------------------------
162 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
164 /// @see SymbolContextScope
165 //------------------------------------------------------------------
167 CalculateSymbolContext(SymbolContext* sc) override;
170 CalculateSymbolContextModule() override;
173 GetDescription (Stream *s,
174 lldb::DescriptionLevel level = lldb::eDescriptionLevelFull);
176 //------------------------------------------------------------------
177 /// Get the module path and object name.
179 /// Modules can refer to object files. In this case the specification
180 /// is simple and would return the path to the file:
182 /// "/usr/lib/foo.dylib"
184 /// Modules can be .o files inside of a BSD archive (.a file). In
185 /// this case, the object specification will look like:
187 /// "/usr/lib/foo.a(bar.o)"
189 /// There are many places where logging wants to log this fully
190 /// qualified specification, so we centralize this functionality
194 /// The object path + object name if there is one.
195 //------------------------------------------------------------------
197 GetSpecificationDescription () const;
199 //------------------------------------------------------------------
200 /// Dump a description of this object to a Stream.
202 /// Dump a description of the contents of this object to the
203 /// supplied stream \a s. The dumped content will be only what has
204 /// been loaded or parsed up to this point at which this function
205 /// is called, so this is a good way to see what has been parsed
209 /// The stream to which to dump the object description.
210 //------------------------------------------------------------------
214 //------------------------------------------------------------------
215 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
217 /// @see SymbolContextScope
218 //------------------------------------------------------------------
220 DumpSymbolContext(Stream *s) override;
222 //------------------------------------------------------------------
223 /// Find a symbol in the object file's symbol table.
226 /// The name of the symbol that we are looking for.
228 /// @param[in] symbol_type
229 /// If set to eSymbolTypeAny, find a symbol of any type that
230 /// has a name that matches \a name. If set to any other valid
231 /// SymbolType enumeration value, then search only for
232 /// symbols that match \a symbol_type.
235 /// Returns a valid symbol pointer if a symbol was found,
236 /// nullptr otherwise.
237 //------------------------------------------------------------------
239 FindFirstSymbolWithNameAndType (const ConstString &name,
240 lldb::SymbolType symbol_type = lldb::eSymbolTypeAny);
243 FindSymbolsWithNameAndType (const ConstString &name,
244 lldb::SymbolType symbol_type,
245 SymbolContextList &sc_list);
248 FindSymbolsMatchingRegExAndType (const RegularExpression ®ex,
249 lldb::SymbolType symbol_type,
250 SymbolContextList &sc_list);
252 //------------------------------------------------------------------
253 /// Find a funciton symbols in the object file's symbol table.
256 /// The name of the symbol that we are looking for.
258 /// @param[in] name_type_mask
259 /// A mask that has one or more bitwise OR'ed values from the
260 /// lldb::FunctionNameType enumeration type that indicate what
261 /// kind of names we are looking for.
263 /// @param[out] sc_list
264 /// A list to append any matching symbol contexts to.
267 /// The number of symbol contexts that were added to \a sc_list
268 //------------------------------------------------------------------
270 FindFunctionSymbols (const ConstString &name,
271 uint32_t name_type_mask,
272 SymbolContextList& sc_list);
274 //------------------------------------------------------------------
275 /// Find compile units by partial or full path.
277 /// Finds all compile units that match \a path in all of the modules
278 /// and returns the results in \a sc_list.
281 /// The name of the function we are looking for.
283 /// @param[in] append
284 /// If \b true, then append any compile units that were found
285 /// to \a sc_list. If \b false, then the \a sc_list is cleared
286 /// and the contents of \a sc_list are replaced.
288 /// @param[out] sc_list
289 /// A symbol context list that gets filled in with all of the
293 /// The number of matches added to \a sc_list.
294 //------------------------------------------------------------------
296 FindCompileUnits (const FileSpec &path,
298 SymbolContextList &sc_list);
300 //------------------------------------------------------------------
301 /// Find functions by name.
303 /// If the function is an inlined function, it will have a block,
304 /// representing the inlined function, and the function will be the
305 /// containing function. If it is not inlined, then the block will
309 /// The name of the compile unit we are looking for.
311 /// @param[in] namespace_decl
312 /// If valid, a namespace to search in.
314 /// @param[in] name_type_mask
315 /// A bit mask of bits that indicate what kind of names should
316 /// be used when doing the lookup. Bits include fully qualified
317 /// names, base names, C++ methods, or ObjC selectors.
318 /// See FunctionNameType for more details.
320 /// @param[in] append
321 /// If \b true, any matches will be appended to \a sc_list, else
322 /// matches replace the contents of \a sc_list.
324 /// @param[out] sc_list
325 /// A symbol context list that gets filled in with all of the
329 /// The number of matches added to \a sc_list.
330 //------------------------------------------------------------------
332 FindFunctions (const ConstString &name,
333 const CompilerDeclContext *parent_decl_ctx,
334 uint32_t name_type_mask,
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 /// A regular expression to use when matching the name.
351 /// @param[in] append
352 /// If \b true, any matches will be appended to \a sc_list, else
353 /// matches replace the contents of \a sc_list.
355 /// @param[out] sc_list
356 /// A symbol context list that gets filled in with all of the
360 /// The number of matches added to \a sc_list.
361 //------------------------------------------------------------------
363 FindFunctions (const RegularExpression& regex,
367 SymbolContextList& sc_list);
369 //------------------------------------------------------------------
370 /// Find addresses by file/line
372 /// @param[in] target_sp
373 /// The target the addresses are desired for.
376 /// Source file to locate.
379 /// Source line to locate.
381 /// @param[in] function
382 /// Optional filter function. Addresses within this function will be
383 /// added to the 'local' list. All others will be added to the 'extern' list.
385 /// @param[out] output_local
386 /// All matching addresses within 'function'
388 /// @param[out] output_extern
389 /// All matching addresses not within 'function'
390 void FindAddressesForLine (const lldb::TargetSP target_sp,
391 const FileSpec &file, uint32_t line,
393 std::vector<Address> &output_local, std::vector<Address> &output_extern);
395 //------------------------------------------------------------------
396 /// Find global and static variables by name.
399 /// The name of the global or static variable we are looking
402 /// @param[in] parent_decl_ctx
403 /// If valid, a decl context that results must exist within
405 /// @param[in] append
406 /// If \b true, any matches will be appended to \a
407 /// variable_list, else matches replace the contents of
408 /// \a variable_list.
410 /// @param[in] max_matches
411 /// Allow the number of matches to be limited to \a
412 /// max_matches. Specify UINT32_MAX to get all possible matches.
414 /// @param[in] variable_list
415 /// A list of variables that gets the matches appended to (if
416 /// \a append it \b true), or replace (if \a append is \b false).
419 /// The number of matches added to \a variable_list.
420 //------------------------------------------------------------------
422 FindGlobalVariables (const ConstString &name,
423 const CompilerDeclContext *parent_decl_ctx,
426 VariableList& variable_list);
428 //------------------------------------------------------------------
429 /// Find global and static variables by regular expression.
432 /// A regular expression to use when matching the name.
434 /// @param[in] append
435 /// If \b true, any matches will be appended to \a
436 /// variable_list, else matches replace the contents of
437 /// \a variable_list.
439 /// @param[in] max_matches
440 /// Allow the number of matches to be limited to \a
441 /// max_matches. Specify UINT32_MAX to get all possible matches.
443 /// @param[in] variable_list
444 /// A list of variables that gets the matches appended to (if
445 /// \a append it \b true), or replace (if \a append is \b false).
448 /// The number of matches added to \a variable_list.
449 //------------------------------------------------------------------
451 FindGlobalVariables (const RegularExpression& regex,
454 VariableList& variable_list);
456 //------------------------------------------------------------------
457 /// Find types by name.
459 /// Type lookups in modules go through the SymbolVendor (which will
460 /// use one or more SymbolFile subclasses). The SymbolFile needs to
461 /// be able to lookup types by basename and not the fully qualified
462 /// typename. This allows the type accelerator tables to stay small,
463 /// even with heavily templatized C++. The type search will then
464 /// narrow down the search results. If "exact_match" is true, then
465 /// the type search will only match exact type name matches. If
466 /// "exact_match" is false, the type will match as long as the base
467 /// typename matches and as long as any immediate containing
468 /// namespaces/class scopes that are specified match. So to search
469 /// for a type "d" in "b::c", the name "b::c::d" can be specified
470 /// and it will match any class/namespace "b" which contains a
471 /// class/namespace "c" which contains type "d". We do this to
472 /// allow users to not always have to specify complete scoping on
473 /// all expressions, but it also allows for exact matching when
477 /// A symbol context that scopes where to extract a type list
480 /// @param[in] type_name
481 /// The name of the type we are looking for that is a fully
482 /// or partially qualified type name.
484 /// @param[in] exact_match
485 /// If \b true, \a type_name is fully qualified and must match
486 /// exactly. If \b false, \a type_name is a partially qualified
487 /// name where the leading namespaces or classes can be
488 /// omitted to make finding types that a user may type
491 /// @param[out] type_list
492 /// A type list gets populated with any matches.
495 /// The number of matches added to \a type_list.
496 //------------------------------------------------------------------
498 FindTypes (const SymbolContext& sc,
499 const ConstString &type_name,
502 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
506 FindFirstType (const SymbolContext& sc,
507 const ConstString &type_name,
510 //------------------------------------------------------------------
511 /// Find types by name that are in a namespace. This function is
512 /// used by the expression parser when searches need to happen in
513 /// an exact namespace scope.
516 /// A symbol context that scopes where to extract a type list
519 /// @param[in] type_name
520 /// The name of a type within a namespace that should not include
521 /// any qualifying namespaces (just a type basename).
523 /// @param[in] namespace_decl
524 /// The namespace declaration that this type must exist in.
526 /// @param[out] type_list
527 /// A type list gets populated with any matches.
530 /// The number of matches added to \a type_list.
531 //------------------------------------------------------------------
533 FindTypesInNamespace (const SymbolContext& sc,
534 const ConstString &type_name,
535 const CompilerDeclContext *parent_decl_ctx,
537 TypeList& type_list);
539 //------------------------------------------------------------------
540 /// Get const accessor for the module architecture.
543 /// A const reference to the architecture object.
544 //------------------------------------------------------------------
546 GetArchitecture () const;
548 //------------------------------------------------------------------
549 /// Get const accessor for the module file specification.
551 /// This function returns the file for the module on the host system
552 /// that is running LLDB. This can differ from the path on the
553 /// platform since we might be doing remote debugging.
556 /// A const reference to the file specification object.
557 //------------------------------------------------------------------
564 //------------------------------------------------------------------
565 /// Get accessor for the module platform file specification.
567 /// Platform file refers to the path of the module as it is known on
568 /// the remote system on which it is being debugged. For local
569 /// debugging this is always the same as Module::GetFileSpec(). But
570 /// remote debugging might mention a file "/usr/lib/liba.dylib"
571 /// which might be locally downloaded and cached. In this case the
572 /// platform file could be something like:
573 /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib"
574 /// The file could also be cached in a local developer kit directory.
577 /// A const reference to the file specification object.
578 //------------------------------------------------------------------
580 GetPlatformFileSpec () const
583 return m_platform_file;
588 SetPlatformFileSpec (const FileSpec &file)
590 m_platform_file = file;
594 GetRemoteInstallFileSpec () const
596 return m_remote_install_file;
600 SetRemoteInstallFileSpec (const FileSpec &file)
602 m_remote_install_file = file;
606 GetSymbolFileFileSpec () const
608 return m_symfile_spec;
612 SetSymbolFileFileSpec (const FileSpec &file);
615 GetModificationTime () const
621 GetObjectModificationTime () const
623 return m_object_mod_time;
627 SetObjectModificationTime (const TimeValue &mod_time)
629 m_mod_time = mod_time;
632 //------------------------------------------------------------------
633 /// Tells whether this module is capable of being the main executable
637 /// \b true if it is, \b false otherwise.
638 //------------------------------------------------------------------
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 //------------------------------------------------------------------
654 IsLoadedInTarget (Target *target);
657 LoadScriptingResourceInTarget(Target *target,
659 Stream* feedback_stream = nullptr);
661 //------------------------------------------------------------------
662 /// Get the number of compile units for this module.
665 /// The number of compile units that the symbol vendor plug-in
667 //------------------------------------------------------------------
669 GetNumCompileUnits();
672 GetCompileUnitAtIndex (size_t idx);
675 GetObjectName() const;
678 GetObjectOffset() const
680 return m_object_offset;
683 //------------------------------------------------------------------
684 /// Get the object file representation for the current architecture.
686 /// If the object file has not been located or parsed yet, this
687 /// function will find the best ObjectFile plug-in that can parse
691 /// If Module::m_file does not exist, or no plug-in was found
692 /// that can parse the file, or the object file doesn't contain
693 /// the current architecture in Module::m_arch, nullptr will be
694 /// returned, else a valid object file interface will be
695 /// returned. The returned pointer is owned by this object and
696 /// remains valid as long as the object is around.
697 //------------------------------------------------------------------
701 //------------------------------------------------------------------
702 /// Get the unified section list for the module. This is the section
703 /// list created by the module's object file and any debug info and
704 /// symbol files created by the symbol vendor.
706 /// If the symbol vendor has not been loaded yet, this function
707 /// will return the section list for the object file.
710 /// Unified module section list.
711 //------------------------------------------------------------------
712 virtual SectionList *
715 //------------------------------------------------------------------
716 /// Notify the module that the file addresses for the Sections have
719 /// If the Section file addresses for a module are updated, this
720 /// method should be called. Any parts of the module, object file,
721 /// or symbol file that has cached those file addresses must invalidate
722 /// or update its cache.
723 //------------------------------------------------------------------
725 SectionFileAddressesChanged ();
728 GetVersion (uint32_t *versions, uint32_t num_versions);
730 //------------------------------------------------------------------
731 /// Load an object file from memory.
733 /// If available, the size of the object file in memory may be
734 /// passed to avoid additional round trips to process memory.
735 /// If the size is not provided, a default value is used. This
736 /// value should be large enough to enable the ObjectFile plugins
737 /// to read the header of the object file without going back to the
741 /// The object file loaded from memory or nullptr, if the operation
742 /// failed (see the `error` for more information in that case).
743 //------------------------------------------------------------------
745 GetMemoryObjectFile (const lldb::ProcessSP &process_sp,
746 lldb::addr_t header_addr,
748 size_t size_to_read = 512);
749 //------------------------------------------------------------------
750 /// Get the symbol vendor interface for the current architecture.
752 /// If the symbol vendor file has not been located yet, this
753 /// function will find the best SymbolVendor plug-in that can
754 /// use the current object file.
757 /// If this module does not have a valid object file, or no
758 /// plug-in can be found that can use the object file, nullptr will
759 /// be returned, else a valid symbol vendor plug-in interface
760 /// will be returned. The returned pointer is owned by this
761 /// object and remains valid as long as the object is around.
762 //------------------------------------------------------------------
763 virtual SymbolVendor*
764 GetSymbolVendor(bool can_create = true,
765 lldb_private::Stream *feedback_strm = nullptr);
767 //------------------------------------------------------------------
768 /// Get accessor the type list for this module.
771 /// A valid type list pointer, or nullptr if there is no valid
772 /// symbol vendor for this module.
773 //------------------------------------------------------------------
777 //------------------------------------------------------------------
778 /// Get a pointer to the UUID value contained in this object.
780 /// If the executable image file doesn't not have a UUID value built
781 /// into the file format, an MD5 checksum of the entire file, or
782 /// slice of the file for the current architecture should be used.
785 /// A const pointer to the internal copy of the UUID value in
786 /// this module if this module has a valid UUID value, NULL
788 //------------------------------------------------------------------
789 const lldb_private::UUID &
792 //------------------------------------------------------------------
793 /// A debugging function that will cause everything in a module to
796 /// All compile units will be parsed, along with all globals and
797 /// static variables and all functions for those compile units.
798 /// All types, scopes, local variables, static variables, global
799 /// variables, and line tables will be parsed. This can be used
800 /// prior to dumping a module to see a complete list of the
801 /// resulting debug information that gets parsed, or as a debug
802 /// function to ensure that the module can consume all of the
803 /// debug data the symbol vendor provides.
804 //------------------------------------------------------------------
806 ParseAllDebugSymbols();
809 ResolveFileAddress (lldb::addr_t vm_addr, Address& so_addr);
811 //------------------------------------------------------------------
812 /// Resolve the symbol context for the given address.
814 /// Tries to resolve the matching symbol context based on a lookup
815 /// from the current symbol vendor. If the lazy lookup fails,
816 /// an attempt is made to parse the eh_frame section to handle
817 /// stripped symbols. If this fails, an attempt is made to resolve
818 /// the symbol to the previous address to handle the case of a
819 /// function with a tail call.
821 /// Use properties of the modified SymbolContext to inspect any
822 /// resolved target, module, compilation unit, symbol, function,
823 /// function block or line entry. Use the return value to determine
824 /// which of these properties have been modified.
826 /// @param[in] so_addr
827 /// A load address to resolve.
829 /// @param[in] resolve_scope
830 /// The scope that should be resolved (see SymbolContext::Scope).
831 /// A combination of flags from the enumeration SymbolContextItem
832 /// requesting a resolution depth. Note that the flags that are
833 /// actually resolved may be a superset of the requested flags.
834 /// For instance, eSymbolContextSymbol requires resolution of
835 /// eSymbolContextModule, and eSymbolContextFunction requires
836 /// eSymbolContextSymbol.
839 /// The SymbolContext that is modified based on symbol resolution.
841 /// @param[in] resolve_tail_call_address
842 /// Determines if so_addr should resolve to a symbol in the case
843 /// of a function whose last instruction is a call. In this case,
844 /// the PC can be one past the address range of the function.
847 /// The scope that has been resolved (see SymbolContext::Scope).
849 /// @see SymbolContext::Scope
850 //------------------------------------------------------------------
852 ResolveSymbolContextForAddress (const Address& so_addr, uint32_t resolve_scope,
853 SymbolContext& sc, bool resolve_tail_call_address = false);
855 //------------------------------------------------------------------
856 /// Resolve items in the symbol context for a given file and line.
858 /// Tries to resolve \a file_path and \a line to a list of matching
861 /// The line table entries contains addresses that can be used to
862 /// further resolve the values in each match: the function, block,
863 /// symbol. Care should be taken to minimize the amount of
864 /// information that is requested to only what is needed --
865 /// typically the module, compile unit, line table and line table
866 /// entry are sufficient.
868 /// @param[in] file_path
869 /// A path to a source file to match. If \a file_path does not
870 /// specify a directory, then this query will match all files
871 /// whose base filename matches. If \a file_path does specify
872 /// a directory, the fullpath to the file must match.
875 /// The source line to match, or zero if just the compile unit
876 /// should be resolved.
878 /// @param[in] check_inlines
879 /// Check for inline file and line number matches. This option
880 /// should be used sparingly as it will cause all line tables
881 /// for every compile unit to be parsed and searched for
882 /// matching inline file entries.
884 /// @param[in] resolve_scope
885 /// The scope that should be resolved (see
886 /// SymbolContext::Scope).
888 /// @param[out] sc_list
889 /// A symbol context list that gets matching symbols contexts
893 /// The number of matches that were added to \a sc_list.
895 /// @see SymbolContext::Scope
896 //------------------------------------------------------------------
898 ResolveSymbolContextForFilePath (const char *file_path, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list);
900 //------------------------------------------------------------------
901 /// Resolve items in the symbol context for a given file and line.
903 /// Tries to resolve \a file_spec and \a line to a list of matching
906 /// The line table entries contains addresses that can be used to
907 /// further resolve the values in each match: the function, block,
908 /// symbol. Care should be taken to minimize the amount of
909 /// information that is requested to only what is needed --
910 /// typically the module, compile unit, line table and line table
911 /// entry are sufficient.
913 /// @param[in] file_spec
914 /// A file spec to a source file to match. If \a file_path does
915 /// not specify a directory, then this query will match all
916 /// files whose base filename matches. If \a file_path does
917 /// specify a directory, the fullpath to the file must match.
920 /// The source line to match, or zero if just the compile unit
921 /// should be resolved.
923 /// @param[in] check_inlines
924 /// Check for inline file and line number matches. This option
925 /// should be used sparingly as it will cause all line tables
926 /// for every compile unit to be parsed and searched for
927 /// matching inline file entries.
929 /// @param[in] resolve_scope
930 /// The scope that should be resolved (see
931 /// SymbolContext::Scope).
933 /// @param[out] sc_list
934 /// A symbol context list that gets filled in with all of the
938 /// A integer that contains SymbolContext::Scope bits set for
939 /// each item that was successfully resolved.
941 /// @see SymbolContext::Scope
942 //------------------------------------------------------------------
944 ResolveSymbolContextsForFileSpec (const FileSpec &file_spec, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list);
947 SetFileSpecAndObjectName (const FileSpec &file,
948 const ConstString &object_name);
951 GetIsDynamicLinkEditor ();
954 GetTypeSystemForLanguage (lldb::LanguageType language);
956 // Special error functions that can do printf style formatting that will prepend the message with
957 // something appropriate for this module (like the architecture, path and object name (if any)).
958 // This centralizes code so that everyone doesn't need to format their error and log messages on
959 // their own and keeps the output a bit more consistent.
961 LogMessage (Log *log, const char *format, ...) __attribute__ ((format (printf, 3, 4)));
964 LogMessageVerboseBacktrace (Log *log, const char *format, ...) __attribute__ ((format (printf, 3, 4)));
967 ReportWarning (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
970 ReportError (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
972 // Only report an error once when the module is first detected to be modified
973 // so we don't spam the console with many messages.
975 ReportErrorIfModifyDetected (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
977 //------------------------------------------------------------------
978 // Return true if the file backing this module has changed since the
979 // module was originally created since we saved the initial file
980 // modification time when the module first gets created.
981 //------------------------------------------------------------------
983 FileHasChanged () const;
985 //------------------------------------------------------------------
986 // SymbolVendor, SymbolFile and ObjectFile member objects should
987 // lock the module mutex to avoid deadlocks.
988 //------------------------------------------------------------------
989 std::recursive_mutex &
996 GetSourceMappingList ()
998 return m_source_mappings;
1001 const PathMappingList &
1002 GetSourceMappingList () const
1004 return m_source_mappings;
1007 //------------------------------------------------------------------
1008 /// Finds a source file given a file spec using the module source
1009 /// path remappings (if any).
1011 /// Tries to resolve \a orig_spec by checking the module source path
1012 /// remappings. It makes sure the file exists, so this call can be
1013 /// expensive if the remappings are on a network file system, so
1014 /// use this function sparingly (not in a tight debug info parsing
1017 /// @param[in] orig_spec
1018 /// The original source file path to try and remap.
1020 /// @param[out] new_spec
1021 /// The newly remapped filespec that is guaranteed to exist.
1024 /// /b true if \a orig_spec was successfully located and
1025 /// \a new_spec is filled in with an existing file spec,
1026 /// \b false otherwise.
1027 //------------------------------------------------------------------
1029 FindSourceFile (const FileSpec &orig_spec, FileSpec &new_spec) const;
1031 //------------------------------------------------------------------
1032 /// Remaps a source file given \a path into \a new_path.
1034 /// Remaps \a path if any source remappings match. This function
1035 /// does NOT stat the file system so it can be used in tight loops
1036 /// where debug info is being parsed.
1039 /// The original source file path to try and remap.
1041 /// @param[out] new_path
1042 /// The newly remapped filespec that is may or may not exist.
1045 /// /b true if \a path was successfully located and \a new_path
1046 /// is filled in with a new source path, \b false otherwise.
1047 //------------------------------------------------------------------
1049 RemapSourceFile (const char *path, std::string &new_path) const;
1051 //----------------------------------------------------------------------
1052 /// @class LookupInfo Module.h "lldb/Core/Module.h"
1053 /// @brief A class that encapsulates name lookup information.
1055 /// Users can type a wide variety of partial names when setting
1056 /// breakpoints by name or when looking for functions by name.
1057 /// SymbolVendor and SymbolFile objects are only required to implement
1058 /// name lookup for function basenames and for fully mangled names.
1059 /// This means if the user types in a partial name, we must reduce this
1060 /// to a name lookup that will work with all SymbolFile objects. So we
1061 /// might reduce a name lookup to look for a basename, and then prune
1062 /// out any results that don't match.
1064 /// The "m_name" member variable represents the name as it was typed
1065 /// by the user. "m_lookup_name" will be the name we actually search
1066 /// for through the symbol or objects files. Lanaguage is included in
1067 /// case we need to filter results by language at a later date. The
1068 /// "m_name_type_mask" member variable tells us what kinds of names we
1069 /// are looking for and can help us prune out unwanted results.
1071 /// Function lookups are done in Module.cpp, ModuleList.cpp and in
1072 /// BreakpointResolverName.cpp and they all now use this class to do
1073 /// lookups correctly.
1074 //----------------------------------------------------------------------
1081 m_language(lldb::eLanguageTypeUnknown),
1082 m_name_type_mask(0),
1083 m_match_name_after_lookup(false)
1087 LookupInfo(const ConstString &name, uint32_t name_type_mask, lldb::LanguageType language);
1096 SetName(const ConstString &name)
1102 GetLookupName() const
1104 return m_lookup_name;
1108 SetLookupName(const ConstString &name)
1110 m_lookup_name = name;
1114 GetNameTypeMask() const
1116 return m_name_type_mask;
1120 SetNameTypeMask(uint32_t mask)
1122 m_name_type_mask = mask;
1126 Prune(SymbolContextList &sc_list, size_t start_idx) const;
1129 ConstString m_name; ///< What the user originally typed
1130 ConstString m_lookup_name; ///< The actual name will lookup when calling in the object or symbol file
1131 lldb::LanguageType m_language; ///< Limit matches to only be for this language
1132 uint32_t m_name_type_mask; ///< One or more bits from lldb::FunctionNameType that indicate what kind of names we are looking for
1133 bool m_match_name_after_lookup; ///< If \b true, then demangled names that match will need to contain "m_name" in order to be considered a match
1137 //------------------------------------------------------------------
1139 //------------------------------------------------------------------
1140 mutable std::recursive_mutex m_mutex; ///< A mutex to keep this object happy in multi-threaded environments.
1141 TimeValue m_mod_time; ///< The modification time for this module when it was created.
1142 ArchSpec m_arch; ///< The architecture for this module.
1143 UUID m_uuid; ///< Each module is assumed to have a unique identifier to help match it up to debug symbols.
1144 FileSpec m_file; ///< The file representation on disk for this module (if there is one).
1145 FileSpec m_platform_file;///< The path to the module on the platform on which it is being debugged
1146 FileSpec m_remote_install_file; ///< If set when debugging on remote platforms, this module will be installed at this location
1147 FileSpec m_symfile_spec; ///< If this path is valid, then this is the file that _will_ be used as the symbol file for this module
1148 ConstString m_object_name; ///< The name an object within this module that is selected, or empty of the module is represented by \a m_file.
1149 uint64_t m_object_offset;
1150 TimeValue m_object_mod_time;
1151 lldb::ObjectFileSP m_objfile_sp; ///< A shared pointer to the object file parser for this module as it may or may not be shared with the SymbolFile
1152 lldb::SymbolVendorUP m_symfile_ap; ///< A pointer to the symbol vendor for this module.
1153 std::vector<lldb::SymbolVendorUP> m_old_symfiles; ///< If anyone calls Module::SetSymbolFileFileSpec() and changes the symbol file,
1154 ///< we need to keep all old symbol files around in case anyone has type references to them
1155 TypeSystemMap m_type_system_map; ///< A map of any type systems associated with this module
1156 PathMappingList m_source_mappings; ///< Module specific source remappings for when you have debug info for a module that doesn't match where the sources currently are
1157 lldb::SectionListUP m_sections_ap; ///< Unified section list for module that is used by the ObjectFile and and ObjectFile instances for the debug info
1159 std::atomic<bool> m_did_load_objfile;
1160 std::atomic<bool> m_did_load_symbol_vendor;
1161 std::atomic<bool> m_did_parse_uuid;
1162 mutable bool m_file_has_changed:1,
1163 m_first_file_changed_log:1; /// See if the module was modified after it was initially opened.
1165 //------------------------------------------------------------------
1166 /// Resolve a file or load virtual address.
1168 /// Tries to resolve \a vm_addr as a file address (if \a
1169 /// vm_addr_is_file_addr is true) or as a load address if \a
1170 /// vm_addr_is_file_addr is false) in the symbol vendor.
1171 /// \a resolve_scope indicates what clients wish to resolve
1172 /// and can be used to limit the scope of what is parsed.
1174 /// @param[in] vm_addr
1175 /// The load virtual address to resolve.
1177 /// @param[in] vm_addr_is_file_addr
1178 /// If \b true, \a vm_addr is a file address, else \a vm_addr
1179 /// if a load address.
1181 /// @param[in] resolve_scope
1182 /// The scope that should be resolved (see
1183 /// SymbolContext::Scope).
1185 /// @param[out] so_addr
1186 /// The section offset based address that got resolved if
1187 /// any bits are returned.
1190 // The symbol context that has objects filled in. Each bit
1191 /// in the \a resolve_scope pertains to a member in the \a sc.
1194 /// A integer that contains SymbolContext::Scope bits set for
1195 /// each item that was successfully resolved.
1197 /// @see SymbolContext::Scope
1198 //------------------------------------------------------------------
1200 ResolveSymbolContextForAddress (lldb::addr_t vm_addr,
1201 bool vm_addr_is_file_addr,
1202 uint32_t resolve_scope,
1207 SymbolIndicesToSymbolContextList (Symtab *symtab,
1208 std::vector<uint32_t> &symbol_indexes,
1209 SymbolContextList &sc_list);
1212 SetArchitecture (const ArchSpec &new_arch);
1215 GetUnifiedSectionList();
1217 friend class ModuleList;
1218 friend class ObjectFile;
1219 friend class SymbolFile;
1222 Module (); // Only used internally by CreateJITModule ()
1225 FindTypes_Impl (const SymbolContext& sc,
1226 const ConstString &name,
1227 const CompilerDeclContext *parent_decl_ctx,
1230 llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
1233 DISALLOW_COPY_AND_ASSIGN (Module);
1236 } // namespace lldb_private
1238 #endif // liblldb_Module_h_