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/ArchSpec.h"
14 #include "lldb/Core/UUID.h"
15 #include "lldb/Host/FileSpec.h"
16 #include "lldb/Host/Mutex.h"
17 #include "lldb/Host/TimeValue.h"
18 #include "lldb/Symbol/ClangASTContext.h"
19 #include "lldb/Symbol/SymbolContextScope.h"
20 #include "lldb/Target/PathMappingList.h"
22 namespace lldb_private {
24 //----------------------------------------------------------------------
25 /// @class Module Module.h "lldb/Core/Module.h"
26 /// @brief A class that describes an executable image and its associated
27 /// object and symbol files.
29 /// The module is designed to be able to select a single slice of an
30 /// executable image as it would appear on disk and during program
33 /// Modules control when and if information is parsed according to which
34 /// accessors are called. For example the object file (ObjectFile)
35 /// representation will only be parsed if the object file is requested
36 /// using the Module::GetObjectFile() is called. The debug symbols
37 /// will only be parsed if the symbol vendor (SymbolVendor) is
38 /// requested using the Module::GetSymbolVendor() is called.
40 /// The module will parse more detailed information as more queries are
42 //----------------------------------------------------------------------
44 public std::enable_shared_from_this<Module>,
45 public SymbolContextScope
48 // Static functions that can track the lifetime of module objects.
49 // This is handy because we might have Module objects that are in
50 // shared pointers that aren't in the global module list (from
51 // ModuleList). If this is the case we need to know about it.
52 // The modules in the global list maintained by these functions
53 // can be viewed using the "target modules list" command using the
54 // "--global" (-g for short).
56 GetNumberAllocatedModules ();
59 GetAllocatedModuleAtIndex (size_t idx);
62 GetAllocationModuleCollectionMutex();
64 //------------------------------------------------------------------
65 /// Construct with file specification and architecture.
67 /// Clients that wish to share modules with other targets should
68 /// use ModuleList::GetSharedModule().
70 /// @param[in] file_spec
71 /// The file specification for the on disk repesentation of
72 /// this executable image.
75 /// The architecture to set as the current architecture in
78 /// @param[in] object_name
79 /// The name of an object in a module used to extract a module
80 /// within a module (.a files and modules that contain multiple
83 /// @param[in] object_offset
84 /// The offset within an existing module used to extract a
85 /// module within a module (.a files and modules that contain
86 /// multiple architectures).
87 //------------------------------------------------------------------
88 Module (const FileSpec& file_spec,
90 const ConstString *object_name = NULL,
91 off_t object_offset = 0,
92 const TimeValue *object_mod_time_ptr = NULL);
94 Module (const ModuleSpec &module_spec);
95 //------------------------------------------------------------------
97 //------------------------------------------------------------------
102 MatchesModuleSpec (const ModuleSpec &module_ref);
104 //------------------------------------------------------------------
105 /// Set the load address for all sections in a module to be the
106 /// file address plus \a slide.
108 /// Many times a module will be loaded in a target with a constant
109 /// offset applied to all top level sections. This function can
110 /// set the load address for all top level sections to be the
111 /// section file address + offset.
113 /// @param[in] target
114 /// The target in which to apply the section load addresses.
117 /// if \a value_is_offset is true, then value is the offset to
118 /// apply to all file addresses for all top level sections in
119 /// the object file as each section load address is being set.
120 /// If \a value_is_offset is false, then "value" is the new
121 /// absolute base address for the image.
123 /// @param[in] value_is_offset
124 /// If \b true, then \a value is an offset to apply to each
125 /// file address of each top level section.
126 /// If \b false, then \a value is the image base address that
127 /// will be used to rigidly slide all loadable sections.
129 /// @param[out] changed
130 /// If any section load addresses were changed in \a target,
131 /// then \a changed will be set to \b true. Else \a changed
132 /// will be set to false. This allows this function to be
133 /// called multiple times on the same module for the same
134 /// target. If the module hasn't moved, then \a changed will
135 /// be false and no module updated notification will need to
139 /// /b True if any sections were successfully loaded in \a target,
140 /// /b false otherwise.
141 //------------------------------------------------------------------
143 SetLoadAddress (Target &target,
145 bool value_is_offset,
148 //------------------------------------------------------------------
149 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
151 /// @see SymbolContextScope
152 //------------------------------------------------------------------
154 CalculateSymbolContext (SymbolContext* sc);
156 virtual lldb::ModuleSP
157 CalculateSymbolContextModule ();
160 GetDescription (Stream *s,
161 lldb::DescriptionLevel level = lldb::eDescriptionLevelFull);
163 //------------------------------------------------------------------
164 /// Get the module path and object name.
166 /// Modules can refer to object files. In this case the specification
167 /// is simple and would return the path to the file:
169 /// "/usr/lib/foo.dylib"
171 /// Modules can be .o files inside of a BSD archive (.a file). In
172 /// this case, the object specification will look like:
174 /// "/usr/lib/foo.a(bar.o)"
176 /// There are many places where logging wants to log this fully
177 /// qualified specification, so we centralize this functionality
181 /// The object path + object name if there is one.
182 //------------------------------------------------------------------
184 GetSpecificationDescription () const;
186 //------------------------------------------------------------------
187 /// Dump a description of this object to a Stream.
189 /// Dump a description of the contents of this object to the
190 /// supplied stream \a s. The dumped content will be only what has
191 /// been loaded or parsed up to this point at which this function
192 /// is called, so this is a good way to see what has been parsed
196 /// The stream to which to dump the object descripton.
197 //------------------------------------------------------------------
201 //------------------------------------------------------------------
202 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
204 /// @see SymbolContextScope
205 //------------------------------------------------------------------
207 DumpSymbolContext (Stream *s);
210 //------------------------------------------------------------------
211 /// Find a symbol in the object file's symbol table.
214 /// The name of the symbol that we are looking for.
216 /// @param[in] symbol_type
217 /// If set to eSymbolTypeAny, find a symbol of any type that
218 /// has a name that matches \a name. If set to any other valid
219 /// SymbolType enumeration value, then search only for
220 /// symbols that match \a symbol_type.
223 /// Returns a valid symbol pointer if a symbol was found,
225 //------------------------------------------------------------------
227 FindFirstSymbolWithNameAndType (const ConstString &name,
228 lldb::SymbolType symbol_type = lldb::eSymbolTypeAny);
231 FindSymbolsWithNameAndType (const ConstString &name,
232 lldb::SymbolType symbol_type,
233 SymbolContextList &sc_list);
236 FindSymbolsMatchingRegExAndType (const RegularExpression ®ex,
237 lldb::SymbolType symbol_type,
238 SymbolContextList &sc_list);
240 //------------------------------------------------------------------
241 /// Find a funciton symbols in the object file's symbol table.
244 /// The name of the symbol that we are looking for.
246 /// @param[in] name_type_mask
247 /// A mask that has one or more bitwise OR'ed values from the
248 /// lldb::FunctionNameType enumeration type that indicate what
249 /// kind of names we are looking for.
251 /// @param[out] sc_list
252 /// A list to append any matching symbol contexts to.
255 /// The number of symbol contexts that were added to \a sc_list
256 //------------------------------------------------------------------
258 FindFunctionSymbols (const ConstString &name,
259 uint32_t name_type_mask,
260 SymbolContextList& sc_list);
262 //------------------------------------------------------------------
263 /// Find compile units by partial or full path.
265 /// Finds all compile units that match \a path in all of the modules
266 /// and returns the results in \a sc_list.
269 /// The name of the function we are looking for.
271 /// @param[in] append
272 /// If \b true, then append any compile units that were found
273 /// to \a sc_list. If \b false, then the \a sc_list is cleared
274 /// and the contents of \a sc_list are replaced.
276 /// @param[out] sc_list
277 /// A symbol context list that gets filled in with all of the
281 /// The number of matches added to \a sc_list.
282 //------------------------------------------------------------------
284 FindCompileUnits (const FileSpec &path,
286 SymbolContextList &sc_list);
289 //------------------------------------------------------------------
290 /// Find functions by name.
292 /// If the function is an inlined function, it will have a block,
293 /// representing the inlined function, and the function will be the
294 /// containing function. If it is not inlined, then the block will
298 /// The name of the compile unit we are looking for.
300 /// @param[in] namespace_decl
301 /// If valid, a namespace to search in.
303 /// @param[in] name_type_mask
304 /// A bit mask of bits that indicate what kind of names should
305 /// be used when doing the lookup. Bits include fully qualified
306 /// names, base names, C++ methods, or ObjC selectors.
307 /// See FunctionNameType for more details.
309 /// @param[in] append
310 /// If \b true, any matches will be appended to \a sc_list, else
311 /// matches replace the contents of \a sc_list.
313 /// @param[out] sc_list
314 /// A symbol context list that gets filled in with all of the
318 /// The number of matches added to \a sc_list.
319 //------------------------------------------------------------------
321 FindFunctions (const ConstString &name,
322 const ClangNamespaceDecl *namespace_decl,
323 uint32_t name_type_mask,
327 SymbolContextList& sc_list);
329 //------------------------------------------------------------------
330 /// Find functions by name.
332 /// If the function is an inlined function, it will have a block,
333 /// representing the inlined function, and the function will be the
334 /// containing function. If it is not inlined, then the block will
338 /// A regular expression to use when matching the name.
340 /// @param[in] append
341 /// If \b true, any matches will be appended to \a sc_list, else
342 /// matches replace the contents of \a sc_list.
344 /// @param[out] sc_list
345 /// A symbol context list that gets filled in with all of the
349 /// The number of matches added to \a sc_list.
350 //------------------------------------------------------------------
352 FindFunctions (const RegularExpression& regex,
356 SymbolContextList& sc_list);
358 //------------------------------------------------------------------
359 /// Find addresses by file/line
361 /// @param[in] target_sp
362 /// The target the addresses are desired for.
365 /// Source file to locate.
368 /// Source line to locate.
370 /// @param[in] function
371 /// Optional filter function. Addresses within this function will be
372 /// added to the 'local' list. All others will be added to the 'extern' list.
374 /// @param[out] output_local
375 /// All matching addresses within 'function'
377 /// @param[out] output_extern
378 /// All matching addresses not within 'function'
379 void FindAddressesForLine (const lldb::TargetSP target_sp,
380 const FileSpec &file, uint32_t line,
382 std::vector<Address> &output_local, std::vector<Address> &output_extern);
384 //------------------------------------------------------------------
385 /// Find global and static variables by name.
388 /// The name of the global or static variable we are looking
391 /// @param[in] namespace_decl
392 /// If valid, a namespace to search in.
394 /// @param[in] append
395 /// If \b true, any matches will be appended to \a
396 /// variable_list, else matches replace the contents of
397 /// \a variable_list.
399 /// @param[in] max_matches
400 /// Allow the number of matches to be limited to \a
401 /// max_matches. Specify UINT32_MAX to get all possible matches.
403 /// @param[in] variable_list
404 /// A list of variables that gets the matches appended to (if
405 /// \a append it \b true), or replace (if \a append is \b false).
408 /// The number of matches added to \a variable_list.
409 //------------------------------------------------------------------
411 FindGlobalVariables (const ConstString &name,
412 const ClangNamespaceDecl *namespace_decl,
415 VariableList& variable_list);
417 //------------------------------------------------------------------
418 /// Find global and static variables by regular exression.
421 /// A regular expression to use when matching the name.
423 /// @param[in] append
424 /// If \b true, any matches will be appended to \a
425 /// variable_list, else matches replace the contents of
426 /// \a variable_list.
428 /// @param[in] max_matches
429 /// Allow the number of matches to be limited to \a
430 /// max_matches. Specify UINT32_MAX to get all possible matches.
432 /// @param[in] variable_list
433 /// A list of variables that gets the matches appended to (if
434 /// \a append it \b true), or replace (if \a append is \b false).
437 /// The number of matches added to \a variable_list.
438 //------------------------------------------------------------------
440 FindGlobalVariables (const RegularExpression& regex,
443 VariableList& variable_list);
445 //------------------------------------------------------------------
446 /// Find types by name.
448 /// Type lookups in modules go through the SymbolVendor (which will
449 /// use one or more SymbolFile subclasses). The SymbolFile needs to
450 /// be able to lookup types by basename and not the fully qualified
451 /// typename. This allows the type accelerator tables to stay small,
452 /// even with heavily templatized C++. The type search will then
453 /// narrow down the search results. If "exact_match" is true, then
454 /// the type search will only match exact type name matches. If
455 /// "exact_match" is false, the type will match as long as the base
456 /// typename matches and as long as any immediate containing
457 /// namespaces/class scopes that are specified match. So to search
458 /// for a type "d" in "b::c", the name "b::c::d" can be specified
459 /// and it will match any class/namespace "b" which contains a
460 /// class/namespace "c" which contains type "d". We do this to
461 /// allow users to not always have to specify complete scoping on
462 /// all expressions, but it also allows for exact matching when
466 /// A symbol context that scopes where to extract a type list
469 /// @param[in] type_name
470 /// The name of the type we are looking for that is a fully
471 /// or partially qualfieid type name.
473 /// @param[in] exact_match
474 /// If \b true, \a type_name is fully qualifed and must match
475 /// exactly. If \b false, \a type_name is a partially qualfied
476 /// name where the leading namespaces or classes can be
477 /// omitted to make finding types that a user may type
480 /// @param[out] type_list
481 /// A type list gets populated with any matches.
484 /// The number of matches added to \a type_list.
485 //------------------------------------------------------------------
487 FindTypes (const SymbolContext& sc,
488 const ConstString &type_name,
494 FindFirstType (const SymbolContext& sc,
495 const ConstString &type_name,
498 //------------------------------------------------------------------
499 /// Find types by name that are in a namespace. This function is
500 /// used by the expression parser when searches need to happen in
501 /// an exact namespace scope.
504 /// A symbol context that scopes where to extract a type list
507 /// @param[in] type_name
508 /// The name of a type within a namespace that should not include
509 /// any qualifying namespaces (just a type basename).
511 /// @param[in] namespace_decl
512 /// The namespace declaration that this type must exist in.
514 /// @param[out] type_list
515 /// A type list gets populated with any matches.
518 /// The number of matches added to \a type_list.
519 //------------------------------------------------------------------
521 FindTypesInNamespace (const SymbolContext& sc,
522 const ConstString &type_name,
523 const ClangNamespaceDecl *namespace_decl,
525 TypeList& type_list);
527 //------------------------------------------------------------------
528 /// Get const accessor for the module architecture.
531 /// A const reference to the architecture object.
532 //------------------------------------------------------------------
534 GetArchitecture () const;
536 //------------------------------------------------------------------
537 /// Get const accessor for the module file specification.
539 /// This function returns the file for the module on the host system
540 /// that is running LLDB. This can differ from the path on the
541 /// platform since we might be doing remote debugging.
544 /// A const reference to the file specification object.
545 //------------------------------------------------------------------
552 //------------------------------------------------------------------
553 /// Get accessor for the module platform file specification.
555 /// Platform file refers to the path of the module as it is known on
556 /// the remote system on which it is being debugged. For local
557 /// debugging this is always the same as Module::GetFileSpec(). But
558 /// remote debugging might mention a file "/usr/lib/liba.dylib"
559 /// which might be locally downloaded and cached. In this case the
560 /// platform file could be something like:
561 /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib"
562 /// The file could also be cached in a local developer kit directory.
565 /// A const reference to the file specification object.
566 //------------------------------------------------------------------
568 GetPlatformFileSpec () const
571 return m_platform_file;
576 SetPlatformFileSpec (const FileSpec &file)
578 m_platform_file = file;
582 GetRemoteInstallFileSpec () const
584 return m_remote_install_file;
588 SetRemoteInstallFileSpec (const FileSpec &file)
590 m_remote_install_file = file;
594 GetSymbolFileFileSpec () const
596 return m_symfile_spec;
600 SetSymbolFileFileSpec (const FileSpec &file);
603 GetModificationTime () const
609 GetObjectModificationTime () const
611 return m_object_mod_time;
615 SetObjectModificationTime (const TimeValue &mod_time)
617 m_mod_time = mod_time;
620 //------------------------------------------------------------------
621 /// Tells whether this module is capable of being the main executable
625 /// \b true if it is, \b false otherwise.
626 //------------------------------------------------------------------
630 //------------------------------------------------------------------
631 /// Tells whether this module has been loaded in the target passed in.
632 /// This call doesn't distinguish between whether the module is loaded
633 /// by the dynamic loader, or by a "target module add" type call.
635 /// @param[in] target
636 /// The target to check whether this is loaded in.
639 /// \b true if it is, \b false otherwise.
640 //------------------------------------------------------------------
642 IsLoadedInTarget (Target *target);
645 LoadScriptingResourceInTarget (Target *target,
647 Stream* feedback_stream = NULL);
649 //------------------------------------------------------------------
650 /// Get the number of compile units for this module.
653 /// The number of compile units that the symbol vendor plug-in
655 //------------------------------------------------------------------
657 GetNumCompileUnits();
660 GetCompileUnitAtIndex (size_t idx);
663 GetObjectName() const;
666 GetObjectOffset() const
668 return m_object_offset;
671 //------------------------------------------------------------------
672 /// Get the object file representation for the current architecture.
674 /// If the object file has not been located or parsed yet, this
675 /// function will find the best ObjectFile plug-in that can parse
679 /// If Module::m_file does not exist, or no plug-in was found
680 /// that can parse the file, or the object file doesn't contain
681 /// the current architecture in Module::m_arch, NULL will be
682 /// returned, else a valid object file interface will be
683 /// returned. The returned pointer is owned by this object and
684 /// remains valid as long as the object is around.
685 //------------------------------------------------------------------
689 //------------------------------------------------------------------
690 /// Get the unified section list for the module. This is the section
691 /// list created by the module's object file and any debug info and
692 /// symbol files created by the symbol vendor.
694 /// If the symbol vendor has not been loaded yet, this function
695 /// will return the section list for the object file.
698 /// Unified module section list.
699 //------------------------------------------------------------------
700 virtual SectionList *
704 GetVersion (uint32_t *versions, uint32_t num_versions);
706 // Load an object file from memory.
708 GetMemoryObjectFile (const lldb::ProcessSP &process_sp,
709 lldb::addr_t header_addr,
711 //------------------------------------------------------------------
712 /// Get the symbol vendor interface for the current architecture.
714 /// If the symbol vendor file has not been located yet, this
715 /// function will find the best SymbolVendor plug-in that can
716 /// use the current object file.
719 /// If this module does not have a valid object file, or no
720 /// plug-in can be found that can use the object file, NULL will
721 /// be returned, else a valid symbol vendor plug-in interface
722 /// will be returned. The returned pointer is owned by this
723 /// object and remains valid as long as the object is around.
724 //------------------------------------------------------------------
725 virtual SymbolVendor*
726 GetSymbolVendor(bool can_create = true,
727 lldb_private::Stream *feedback_strm = NULL);
729 //------------------------------------------------------------------
730 /// Get accessor the type list for this module.
733 /// A valid type list pointer, or NULL if there is no valid
734 /// symbol vendor for this module.
735 //------------------------------------------------------------------
739 //------------------------------------------------------------------
740 /// Get a pointer to the UUID value contained in this object.
742 /// If the executable image file doesn't not have a UUID value built
743 /// into the file format, an MD5 checksum of the entire file, or
744 /// slice of the file for the current architecture should be used.
747 /// A const pointer to the internal copy of the UUID value in
748 /// this module if this module has a valid UUID value, NULL
750 //------------------------------------------------------------------
751 const lldb_private::UUID &
754 //------------------------------------------------------------------
755 /// A debugging function that will cause everything in a module to
758 /// All compile units will be pasred, along with all globals and
759 /// static variables and all functions for those compile units.
760 /// All types, scopes, local variables, static variables, global
761 /// variables, and line tables will be parsed. This can be used
762 /// prior to dumping a module to see a complete list of the
763 /// resuling debug information that gets parsed, or as a debug
764 /// function to ensure that the module can consume all of the
765 /// debug data the symbol vendor provides.
766 //------------------------------------------------------------------
768 ParseAllDebugSymbols();
771 ResolveFileAddress (lldb::addr_t vm_addr, Address& so_addr);
773 //------------------------------------------------------------------
774 /// Resolve the symbol context for the given address.
776 /// Tries to resolve the matching symbol context based on a lookup
777 /// from the current symbol vendor. If the lazy lookup fails,
778 /// an attempt is made to parse the eh_frame section to handle
779 /// stripped symbols. If this fails, an attempt is made to resolve
780 /// the symbol to the previous address to handle the case of a
781 /// function with a tail call.
783 /// Use properties of the modified SymbolContext to inspect any
784 /// resolved target, module, compilation unit, symbol, function,
785 /// function block or line entry. Use the return value to determine
786 /// which of these properties have been modified.
788 /// @param[in] so_addr
789 /// A load address to resolve.
791 /// @param[in] resolve_scope
792 /// The scope that should be resolved (see SymbolContext::Scope).
793 /// A combination of flags from the enumeration SymbolContextItem
794 /// requesting a resolution depth. Note that the flags that are
795 /// actually resolved may be a superset of the requested flags.
796 /// For instance, eSymbolContextSymbol requires resolution of
797 /// eSymbolContextModule, and eSymbolContextFunction requires
798 /// eSymbolContextSymbol.
801 /// The SymbolContext that is modified based on symbol resolution.
803 /// @param[in] resolve_tail_call_address
804 /// Determines if so_addr should resolve to a symbol in the case
805 /// of a function whose last instruction is a call. In this case,
806 /// the PC can be one past the address range of the function.
809 /// The scope that has been resolved (see SymbolContext::Scope).
811 /// @see SymbolContext::Scope
812 //------------------------------------------------------------------
814 ResolveSymbolContextForAddress (const Address& so_addr, uint32_t resolve_scope,
815 SymbolContext& sc, bool resolve_tail_call_address = false);
817 //------------------------------------------------------------------
818 /// Resolve items in the symbol context for a given file and line.
820 /// Tries to resolve \a file_path and \a line to a list of matching
823 /// The line table entries contains addresses that can be used to
824 /// further resolve the values in each match: the function, block,
825 /// symbol. Care should be taken to minimize the amount of
826 /// information that is requested to only what is needed --
827 /// typically the module, compile unit, line table and line table
828 /// entry are sufficient.
830 /// @param[in] file_path
831 /// A path to a source file to match. If \a file_path does not
832 /// specify a directory, then this query will match all files
833 /// whose base filename matches. If \a file_path does specify
834 /// a directory, the fullpath to the file must match.
837 /// The source line to match, or zero if just the compile unit
838 /// should be resolved.
840 /// @param[in] check_inlines
841 /// Check for inline file and line number matches. This option
842 /// should be used sparingly as it will cause all line tables
843 /// for every compile unit to be parsed and searched for
844 /// matching inline file entries.
846 /// @param[in] resolve_scope
847 /// The scope that should be resolved (see
848 /// SymbolContext::Scope).
850 /// @param[out] sc_list
851 /// A symbol context list that gets matching symbols contexts
855 /// The number of matches that were added to \a sc_list.
857 /// @see SymbolContext::Scope
858 //------------------------------------------------------------------
860 ResolveSymbolContextForFilePath (const char *file_path, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list);
862 //------------------------------------------------------------------
863 /// Resolve items in the symbol context for a given file and line.
865 /// Tries to resolve \a file_spec and \a line to a list of matching
868 /// The line table entries contains addresses that can be used to
869 /// further resolve the values in each match: the function, block,
870 /// symbol. Care should be taken to minimize the amount of
871 /// information that is requested to only what is needed --
872 /// typically the module, compile unit, line table and line table
873 /// entry are sufficient.
875 /// @param[in] file_spec
876 /// A file spec to a source file to match. If \a file_path does
877 /// not specify a directory, then this query will match all
878 /// files whose base filename matches. If \a file_path does
879 /// specify a directory, the fullpath to the file must match.
882 /// The source line to match, or zero if just the compile unit
883 /// should be resolved.
885 /// @param[in] check_inlines
886 /// Check for inline file and line number matches. This option
887 /// should be used sparingly as it will cause all line tables
888 /// for every compile unit to be parsed and searched for
889 /// matching inline file entries.
891 /// @param[in] resolve_scope
892 /// The scope that should be resolved (see
893 /// SymbolContext::Scope).
895 /// @param[out] sc_list
896 /// A symbol context list that gets filled in with all of the
900 /// A integer that contains SymbolContext::Scope bits set for
901 /// each item that was successfully resolved.
903 /// @see SymbolContext::Scope
904 //------------------------------------------------------------------
906 ResolveSymbolContextsForFileSpec (const FileSpec &file_spec, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list);
910 SetFileSpecAndObjectName (const FileSpec &file,
911 const ConstString &object_name);
914 GetIsDynamicLinkEditor () const
916 return m_is_dynamic_loader_module;
920 SetIsDynamicLinkEditor (bool b)
922 m_is_dynamic_loader_module = b;
926 GetClangASTContext ();
928 // Special error functions that can do printf style formatting that will prepend the message with
929 // something appropriate for this module (like the architecture, path and object name (if any)).
930 // This centralizes code so that everyone doesn't need to format their error and log messages on
931 // their own and keeps the output a bit more consistent.
933 LogMessage (Log *log, const char *format, ...) __attribute__ ((format (printf, 3, 4)));
936 LogMessageVerboseBacktrace (Log *log, const char *format, ...) __attribute__ ((format (printf, 3, 4)));
939 ReportWarning (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
942 ReportError (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
944 // Only report an error once when the module is first detected to be modified
945 // so we don't spam the console with many messages.
947 ReportErrorIfModifyDetected (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
949 //------------------------------------------------------------------
950 // Return true if the file backing this module has changed since the
951 // module was originally created since we saved the intial file
952 // modification time when the module first gets created.
953 //------------------------------------------------------------------
955 FileHasChanged () const;
957 //------------------------------------------------------------------
958 // SymbolVendor, SymbolFile and ObjectFile member objects should
959 // lock the module mutex to avoid deadlocks.
960 //------------------------------------------------------------------
968 GetSourceMappingList ()
970 return m_source_mappings;
973 const PathMappingList &
974 GetSourceMappingList () const
976 return m_source_mappings;
979 //------------------------------------------------------------------
980 /// Finds a source file given a file spec using the module source
981 /// path remappings (if any).
983 /// Tries to resolve \a orig_spec by checking the module source path
984 /// remappings. It makes sure the file exists, so this call can be
985 /// expensive if the remappings are on a network file system, so
986 /// use this function sparingly (not in a tight debug info parsing
989 /// @param[in] orig_spec
990 /// The original source file path to try and remap.
992 /// @param[out] new_spec
993 /// The newly remapped filespec that is guaranteed to exist.
996 /// /b true if \a orig_spec was successfully located and
997 /// \a new_spec is filled in with an existing file spec,
998 /// \b false otherwise.
999 //------------------------------------------------------------------
1001 FindSourceFile (const FileSpec &orig_spec, FileSpec &new_spec) const;
1003 //------------------------------------------------------------------
1004 /// Remaps a source file given \a path into \a new_path.
1006 /// Remaps \a path if any source remappings match. This function
1007 /// does NOT stat the file system so it can be used in tight loops
1008 /// where debug info is being parsed.
1011 /// The original source file path to try and remap.
1013 /// @param[out] new_path
1014 /// The newly remapped filespec that is may or may not exist.
1017 /// /b true if \a path was successfully located and \a new_path
1018 /// is filled in with a new source path, \b false otherwise.
1019 //------------------------------------------------------------------
1021 RemapSourceFile (const char *path, std::string &new_path) const;
1024 //------------------------------------------------------------------
1025 /// Prepare to do a function name lookup.
1027 /// Looking up functions by name can be a tricky thing. LLDB requires
1028 /// that accelerator tables contain full names for functions as well
1029 /// as function basenames which include functions, class methods and
1030 /// class functions. When the user requests that an action use a
1031 /// function by name, we are sometimes asked to automatically figure
1032 /// out what a name could possibly map to. A user might request a
1033 /// breakpoint be set on "count". If no options are supplied to limit
1034 /// the scope of where to search for count, we will by default match
1035 /// any function names named "count", all class and instance methods
1036 /// named "count" (no matter what the namespace or contained context)
1037 /// and any selectors named "count". If a user specifies "a::b" we
1038 /// will search for the basename "b", and then prune the results that
1039 /// don't match "a::b" (note that "c::a::b" and "d::e::a::b" will
1040 /// match a query of "a::b".
1043 /// The user supplied name to use in the lookup
1045 /// @param[in] name_type_mask
1046 /// The mask of bits from lldb::FunctionNameType enumerations
1047 /// that tell us what kind of name we are looking for.
1049 /// @param[out] lookup_name
1050 /// The actual name that will be used when calling
1051 /// SymbolVendor::FindFunctions() or Symtab::FindFunctionSymbols()
1053 /// @param[out] lookup_name_type_mask
1054 /// The actual name mask that should be used in the calls to
1055 /// SymbolVendor::FindFunctions() or Symtab::FindFunctionSymbols()
1057 /// @param[out] match_name_after_lookup
1058 /// A boolean that indicates if we need to iterate through any
1059 /// match results obtained from SymbolVendor::FindFunctions() or
1060 /// Symtab::FindFunctionSymbols() to see if the name contains
1061 /// \a name. For example if \a name is "a::b", this function will
1062 /// return a \a lookup_name of "b", with \a match_name_after_lookup
1063 /// set to true to indicate any matches will need to be checked
1064 /// to make sure they contain \a name.
1065 //------------------------------------------------------------------
1067 PrepareForFunctionNameLookup (const ConstString &name,
1068 uint32_t name_type_mask,
1069 ConstString &lookup_name,
1070 uint32_t &lookup_name_type_mask,
1071 bool &match_name_after_lookup);
1074 //------------------------------------------------------------------
1076 //------------------------------------------------------------------
1077 mutable Mutex m_mutex; ///< A mutex to keep this object happy in multi-threaded environments.
1078 TimeValue m_mod_time; ///< The modification time for this module when it was created.
1079 ArchSpec m_arch; ///< The architecture for this module.
1080 lldb_private::UUID m_uuid; ///< Each module is assumed to have a unique identifier to help match it up to debug symbols.
1081 FileSpec m_file; ///< The file representation on disk for this module (if there is one).
1082 FileSpec m_platform_file;///< The path to the module on the platform on which it is being debugged
1083 FileSpec m_remote_install_file; ///< If set when debugging on remote platforms, this module will be installed at this location
1084 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
1085 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.
1086 uint64_t m_object_offset;
1087 TimeValue m_object_mod_time;
1088 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
1089 std::unique_ptr<SymbolVendor> m_symfile_ap; ///< A pointer to the symbol vendor for this module.
1090 ClangASTContext m_ast; ///< The AST context for this module.
1091 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
1092 std::unique_ptr<lldb_private::SectionList> m_sections_ap; ///< Unified section list for module that is used by the ObjectFile and and ObjectFile instances for the debug info
1094 bool m_did_load_objfile:1,
1095 m_did_load_symbol_vendor:1,
1098 m_is_dynamic_loader_module:1;
1099 mutable bool m_file_has_changed:1,
1100 m_first_file_changed_log:1; /// See if the module was modified after it was initially opened.
1102 //------------------------------------------------------------------
1103 /// Resolve a file or load virtual address.
1105 /// Tries to resolve \a vm_addr as a file address (if \a
1106 /// vm_addr_is_file_addr is true) or as a load address if \a
1107 /// vm_addr_is_file_addr is false) in the symbol vendor.
1108 /// \a resolve_scope indicates what clients wish to resolve
1109 /// and can be used to limit the scope of what is parsed.
1111 /// @param[in] vm_addr
1112 /// The load virtual address to resolve.
1114 /// @param[in] vm_addr_is_file_addr
1115 /// If \b true, \a vm_addr is a file address, else \a vm_addr
1116 /// if a load address.
1118 /// @param[in] resolve_scope
1119 /// The scope that should be resolved (see
1120 /// SymbolContext::Scope).
1122 /// @param[out] so_addr
1123 /// The section offset based address that got resolved if
1124 /// any bits are returned.
1127 // The symbol context that has objects filled in. Each bit
1128 /// in the \a resolve_scope pertains to a member in the \a sc.
1131 /// A integer that contains SymbolContext::Scope bits set for
1132 /// each item that was successfully resolved.
1134 /// @see SymbolContext::Scope
1135 //------------------------------------------------------------------
1137 ResolveSymbolContextForAddress (lldb::addr_t vm_addr,
1138 bool vm_addr_is_file_addr,
1139 uint32_t resolve_scope,
1144 SymbolIndicesToSymbolContextList (Symtab *symtab,
1145 std::vector<uint32_t> &symbol_indexes,
1146 SymbolContextList &sc_list);
1149 SetArchitecture (const ArchSpec &new_arch);
1152 GetUnifiedSectionList();
1154 friend class ModuleList;
1155 friend class ObjectFile;
1156 friend class SymbolFile;
1161 FindTypes_Impl (const SymbolContext& sc,
1162 const ConstString &name,
1163 const ClangNamespaceDecl *namespace_decl,
1169 DISALLOW_COPY_AND_ASSIGN (Module);
1172 } // namespace lldb_private
1174 #endif // liblldb_Module_h_