1 //===-- Module.h ------------------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef LLDB_CORE_MODULE_H
10 #define LLDB_CORE_MODULE_H
11 
12 #include "lldb/Core/Address.h"
13 #include "lldb/Core/ModuleList.h"
14 #include "lldb/Core/ModuleSpec.h"
15 #include "lldb/Symbol/ObjectFile.h"
16 #include "lldb/Symbol/SymbolContextScope.h"
17 #include "lldb/Symbol/TypeSystem.h"
18 #include "lldb/Target/PathMappingList.h"
19 #include "lldb/Target/Statistics.h"
20 #include "lldb/Utility/ArchSpec.h"
21 #include "lldb/Utility/ConstString.h"
22 #include "lldb/Utility/FileSpec.h"
23 #include "lldb/Utility/Status.h"
24 #include "lldb/Utility/UUID.h"
25 #include "lldb/Utility/XcodeSDK.h"
26 #include "lldb/lldb-defines.h"
27 #include "lldb/lldb-enumerations.h"
28 #include "lldb/lldb-forward.h"
29 #include "lldb/lldb-types.h"
30 
31 #include "llvm/ADT/DenseSet.h"
32 #include "llvm/ADT/StringRef.h"
33 #include "llvm/Support/Chrono.h"
34 
35 #include <atomic>
36 #include <cstddef>
37 #include <cstdint>
38 #include <memory>
39 #include <mutex>
40 #include <string>
41 #include <vector>
42 
43 namespace lldb_private {
44 class CompilerDeclContext;
45 class Function;
46 class Log;
47 class ObjectFile;
48 class RegularExpression;
49 class SectionList;
50 class Stream;
51 class Symbol;
52 class SymbolContext;
53 class SymbolContextList;
54 class SymbolFile;
55 class Symtab;
56 class Target;
57 class TypeList;
58 class TypeMap;
59 class VariableList;
60 
61 /// Options used by Module::FindFunctions. This cannot be a nested class
62 /// because it must be forward-declared in ModuleList.h.
63 struct ModuleFunctionSearchOptions {
64   /// Include the symbol table.
65   bool include_symbols = false;
66   /// Include inlined functions.
67   bool include_inlines = false;
68 };
69 
70 /// \class Module Module.h "lldb/Core/Module.h"
71 /// A class that describes an executable image and its associated
72 ///        object and symbol files.
73 ///
74 /// The module is designed to be able to select a single slice of an
75 /// executable image as it would appear on disk and during program execution.
76 ///
77 /// Modules control when and if information is parsed according to which
78 /// accessors are called. For example the object file (ObjectFile)
79 /// representation will only be parsed if the object file is requested using
80 /// the Module::GetObjectFile() is called. The debug symbols will only be
81 /// parsed if the symbol file (SymbolFile) is requested using the
82 /// Module::GetSymbolFile() method.
83 ///
84 /// The module will parse more detailed information as more queries are made.
85 class Module : public std::enable_shared_from_this<Module>,
86                public SymbolContextScope {
87 public:
88   // Static functions that can track the lifetime of module objects. This is
89   // handy because we might have Module objects that are in shared pointers
90   // that aren't in the global module list (from ModuleList). If this is the
91   // case we need to know about it. The modules in the global list maintained
92   // by these functions can be viewed using the "target modules list" command
93   // using the "--global" (-g for short).
94   static size_t GetNumberAllocatedModules();
95 
96   static Module *GetAllocatedModuleAtIndex(size_t idx);
97 
98   static std::recursive_mutex &GetAllocationModuleCollectionMutex();
99 
100   /// Construct with file specification and architecture.
101   ///
102   /// Clients that wish to share modules with other targets should use
103   /// ModuleList::GetSharedModule().
104   ///
105   /// \param[in] file_spec
106   ///     The file specification for the on disk representation of
107   ///     this executable image.
108   ///
109   /// \param[in] arch
110   ///     The architecture to set as the current architecture in
111   ///     this module.
112   ///
113   /// \param[in] object_name
114   ///     The name of an object in a module used to extract a module
115   ///     within a module (.a files and modules that contain multiple
116   ///     architectures).
117   ///
118   /// \param[in] object_offset
119   ///     The offset within an existing module used to extract a
120   ///     module within a module (.a files and modules that contain
121   ///     multiple architectures).
122   Module(
123       const FileSpec &file_spec, const ArchSpec &arch,
124       const ConstString *object_name = nullptr,
125       lldb::offset_t object_offset = 0,
126       const llvm::sys::TimePoint<> &object_mod_time = llvm::sys::TimePoint<>());
127 
128   Module(const ModuleSpec &module_spec);
129 
130   template <typename ObjFilePlugin, typename... Args>
131   static lldb::ModuleSP CreateModuleFromObjectFile(Args &&...args) {
132     // Must create a module and place it into a shared pointer before we can
133     // create an object file since it has a std::weak_ptr back to the module,
134     // so we need to control the creation carefully in this static function
135     lldb::ModuleSP module_sp(new Module());
136     module_sp->m_objfile_sp =
137         std::make_shared<ObjFilePlugin>(module_sp, std::forward<Args>(args)...);
138     module_sp->m_did_load_objfile.store(true, std::memory_order_relaxed);
139 
140     // Once we get the object file, set module ArchSpec to the one we get from
141     // the object file. If the object file does not have an architecture, we
142     // consider the creation a failure.
143     ArchSpec arch = module_sp->m_objfile_sp->GetArchitecture();
144     if (!arch)
145       return nullptr;
146     module_sp->m_arch = arch;
147 
148     // Also copy the object file's FileSpec.
149     module_sp->m_file = module_sp->m_objfile_sp->GetFileSpec();
150     return module_sp;
151   }
152 
153   /// Destructor.
154   ~Module() override;
155 
156   bool MatchesModuleSpec(const ModuleSpec &module_ref);
157 
158   /// Set the load address for all sections in a module to be the file address
159   /// plus \a slide.
160   ///
161   /// Many times a module will be loaded in a target with a constant offset
162   /// applied to all top level sections. This function can set the load
163   /// address for all top level sections to be the section file address +
164   /// offset.
165   ///
166   /// \param[in] target
167   ///     The target in which to apply the section load addresses.
168   ///
169   /// \param[in] value
170   ///     if \a value_is_offset is true, then value is the offset to
171   ///     apply to all file addresses for all top level sections in
172   ///     the object file as each section load address is being set.
173   ///     If \a value_is_offset is false, then "value" is the new
174   ///     absolute base address for the image.
175   ///
176   /// \param[in] value_is_offset
177   ///     If \b true, then \a value is an offset to apply to each
178   ///     file address of each top level section.
179   ///     If \b false, then \a value is the image base address that
180   ///     will be used to rigidly slide all loadable sections.
181   ///
182   /// \param[out] changed
183   ///     If any section load addresses were changed in \a target,
184   ///     then \a changed will be set to \b true. Else \a changed
185   ///     will be set to false. This allows this function to be
186   ///     called multiple times on the same module for the same
187   ///     target. If the module hasn't moved, then \a changed will
188   ///     be false and no module updated notification will need to
189   ///     be sent out.
190   ///
191   /// \return
192   ///     /b True if any sections were successfully loaded in \a target,
193   ///     /b false otherwise.
194   bool SetLoadAddress(Target &target, lldb::addr_t value, bool value_is_offset,
195                       bool &changed);
196 
197   /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
198   ///
199   /// \see SymbolContextScope
200   void CalculateSymbolContext(SymbolContext *sc) override;
201 
202   lldb::ModuleSP CalculateSymbolContextModule() override;
203 
204   void
205   GetDescription(llvm::raw_ostream &s,
206                  lldb::DescriptionLevel level = lldb::eDescriptionLevelFull);
207 
208   /// Get the module path and object name.
209   ///
210   /// Modules can refer to object files. In this case the specification is
211   /// simple and would return the path to the file:
212   ///
213   ///     "/usr/lib/foo.dylib"
214   ///
215   /// Modules can be .o files inside of a BSD archive (.a file). In this case,
216   /// the object specification will look like:
217   ///
218   ///     "/usr/lib/foo.a(bar.o)"
219   ///
220   /// There are many places where logging wants to log this fully qualified
221   /// specification, so we centralize this functionality here.
222   ///
223   /// \return
224   ///     The object path + object name if there is one.
225   std::string GetSpecificationDescription() const;
226 
227   /// Dump a description of this object to a Stream.
228   ///
229   /// Dump a description of the contents of this object to the supplied stream
230   /// \a s. The dumped content will be only what has been loaded or parsed up
231   /// to this point at which this function is called, so this is a good way to
232   /// see what has been parsed in a module.
233   ///
234   /// \param[in] s
235   ///     The stream to which to dump the object description.
236   void Dump(Stream *s);
237 
238   /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
239   ///
240   /// \see SymbolContextScope
241   void DumpSymbolContext(Stream *s) override;
242 
243   /// Find a symbol in the object file's symbol table.
244   ///
245   /// \param[in] name
246   ///     The name of the symbol that we are looking for.
247   ///
248   /// \param[in] symbol_type
249   ///     If set to eSymbolTypeAny, find a symbol of any type that
250   ///     has a name that matches \a name. If set to any other valid
251   ///     SymbolType enumeration value, then search only for
252   ///     symbols that match \a symbol_type.
253   ///
254   /// \return
255   ///     Returns a valid symbol pointer if a symbol was found,
256   ///     nullptr otherwise.
257   const Symbol *FindFirstSymbolWithNameAndType(
258       ConstString name, lldb::SymbolType symbol_type = lldb::eSymbolTypeAny);
259 
260   void FindSymbolsWithNameAndType(ConstString name,
261                                   lldb::SymbolType symbol_type,
262                                   SymbolContextList &sc_list);
263 
264   void FindSymbolsMatchingRegExAndType(const RegularExpression &regex,
265                                        lldb::SymbolType symbol_type,
266                                        SymbolContextList &sc_list);
267 
268   /// Find a function symbols in the object file's symbol table.
269   ///
270   /// \param[in] name
271   ///     The name of the symbol that we are looking for.
272   ///
273   /// \param[in] name_type_mask
274   ///     A mask that has one or more bitwise OR'ed values from the
275   ///     lldb::FunctionNameType enumeration type that indicate what
276   ///     kind of names we are looking for.
277   ///
278   /// \param[out] sc_list
279   ///     A list to append any matching symbol contexts to.
280   void FindFunctionSymbols(ConstString name, uint32_t name_type_mask,
281                            SymbolContextList &sc_list);
282 
283   /// Find compile units by partial or full path.
284   ///
285   /// Finds all compile units that match \a path in all of the modules and
286   /// returns the results in \a sc_list.
287   ///
288   /// \param[in] path
289   ///     The name of the function we are looking for.
290   ///
291   /// \param[out] sc_list
292   ///     A symbol context list that gets filled in with all of the
293   ///     matches.
294   void FindCompileUnits(const FileSpec &path, SymbolContextList &sc_list);
295 
296   /// Find functions by name.
297   ///
298   /// If the function is an inlined function, it will have a block,
299   /// representing the inlined function, and the function will be the
300   /// containing function.  If it is not inlined, then the block will be NULL.
301   ///
302   /// \param[in] name
303   ///     The name of the function we are looking for.
304   ///
305   /// \param[in] name_type_mask
306   ///     A bit mask of bits that indicate what kind of names should
307   ///     be used when doing the lookup. Bits include fully qualified
308   ///     names, base names, C++ methods, or ObjC selectors.
309   ///     See FunctionNameType for more details.
310   ///
311   /// \param[out] sc_list
312   ///     A symbol context list that gets filled in with all of the
313   ///     matches.
314   void FindFunctions(ConstString name,
315                      const CompilerDeclContext &parent_decl_ctx,
316                      lldb::FunctionNameType name_type_mask,
317                      const ModuleFunctionSearchOptions &options,
318                      SymbolContextList &sc_list);
319 
320   /// Find functions by name.
321   ///
322   /// If the function is an inlined function, it will have a block,
323   /// representing the inlined function, and the function will be the
324   /// containing function.  If it is not inlined, then the block will be NULL.
325   ///
326   /// \param[in] regex
327   ///     A regular expression to use when matching the name.
328   ///
329   /// \param[out] sc_list
330   ///     A symbol context list that gets filled in with all of the
331   ///     matches.
332   void FindFunctions(const RegularExpression &regex,
333                      const ModuleFunctionSearchOptions &options,
334                      SymbolContextList &sc_list);
335 
336   /// Find addresses by file/line
337   ///
338   /// \param[in] target_sp
339   ///     The target the addresses are desired for.
340   ///
341   /// \param[in] file
342   ///     Source file to locate.
343   ///
344   /// \param[in] line
345   ///     Source line to locate.
346   ///
347   /// \param[in] function
348   ///	    Optional filter function. Addresses within this function will be
349   ///     added to the 'local' list. All others will be added to the 'extern'
350   ///     list.
351   ///
352   /// \param[out] output_local
353   ///     All matching addresses within 'function'
354   ///
355   /// \param[out] output_extern
356   ///     All matching addresses not within 'function'
357   void FindAddressesForLine(const lldb::TargetSP target_sp,
358                             const FileSpec &file, uint32_t line,
359                             Function *function,
360                             std::vector<Address> &output_local,
361                             std::vector<Address> &output_extern);
362 
363   /// Find global and static variables by name.
364   ///
365   /// \param[in] name
366   ///     The name of the global or static variable we are looking
367   ///     for.
368   ///
369   /// \param[in] parent_decl_ctx
370   ///     If valid, a decl context that results must exist within
371   ///
372   /// \param[in] max_matches
373   ///     Allow the number of matches to be limited to \a
374   ///     max_matches. Specify UINT32_MAX to get all possible matches.
375   ///
376   /// \param[in] variable_list
377   ///     A list of variables that gets the matches appended to.
378   ///
379   void FindGlobalVariables(ConstString name,
380                            const CompilerDeclContext &parent_decl_ctx,
381                            size_t max_matches, VariableList &variable_list);
382 
383   /// Find global and static variables by regular expression.
384   ///
385   /// \param[in] regex
386   ///     A regular expression to use when matching the name.
387   ///
388   /// \param[in] max_matches
389   ///     Allow the number of matches to be limited to \a
390   ///     max_matches. Specify UINT32_MAX to get all possible matches.
391   ///
392   /// \param[in] variable_list
393   ///     A list of variables that gets the matches appended to.
394   ///
395   void FindGlobalVariables(const RegularExpression &regex, size_t max_matches,
396                            VariableList &variable_list);
397 
398   /// Find types by name.
399   ///
400   /// Type lookups in modules go through the SymbolFile. The SymbolFile needs to
401   /// be able to lookup types by basename and not the fully qualified typename.
402   /// This allows the type accelerator tables to stay small, even with heavily
403   /// templatized C++. The type search will then narrow down the search
404   /// results. If "exact_match" is true, then the type search will only match
405   /// exact type name matches. If "exact_match" is false, the type will match
406   /// as long as the base typename matches and as long as any immediate
407   /// containing namespaces/class scopes that are specified match. So to
408   /// search for a type "d" in "b::c", the name "b::c::d" can be specified and
409   /// it will match any class/namespace "b" which contains a class/namespace
410   /// "c" which contains type "d". We do this to allow users to not always
411   /// have to specify complete scoping on all expressions, but it also allows
412   /// for exact matching when required.
413   ///
414   /// \param[in] type_name
415   ///     The name of the type we are looking for that is a fully
416   ///     or partially qualified type name.
417   ///
418   /// \param[in] exact_match
419   ///     If \b true, \a type_name is fully qualified and must match
420   ///     exactly. If \b false, \a type_name is a partially qualified
421   ///     name where the leading namespaces or classes can be
422   ///     omitted to make finding types that a user may type
423   ///     easier.
424   ///
425   /// \param[out] types
426   ///     A type list gets populated with any matches.
427   ///
428   void
429   FindTypes(ConstString type_name, bool exact_match, size_t max_matches,
430             llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
431             TypeList &types);
432 
433   /// Find types by name.
434   ///
435   /// This behaves like the other FindTypes method but allows to
436   /// specify a DeclContext and a language for the type being searched
437   /// for.
438   ///
439   /// \param searched_symbol_files
440   ///     Prevents one file from being visited multiple times.
441   void
442   FindTypes(llvm::ArrayRef<CompilerContext> pattern, LanguageSet languages,
443             llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
444             TypeMap &types);
445 
446   lldb::TypeSP FindFirstType(const SymbolContext &sc, ConstString type_name,
447                              bool exact_match);
448 
449   /// Find types by name that are in a namespace. This function is used by the
450   /// expression parser when searches need to happen in an exact namespace
451   /// scope.
452   ///
453   /// \param[in] type_name
454   ///     The name of a type within a namespace that should not include
455   ///     any qualifying namespaces (just a type basename).
456   ///
457   /// \param[out] type_list
458   ///     A type list gets populated with any matches.
459   void FindTypesInNamespace(ConstString type_name,
460                             const CompilerDeclContext &parent_decl_ctx,
461                             size_t max_matches, TypeList &type_list);
462 
463   /// Get const accessor for the module architecture.
464   ///
465   /// \return
466   ///     A const reference to the architecture object.
467   const ArchSpec &GetArchitecture() const;
468 
469   /// Get const accessor for the module file specification.
470   ///
471   /// This function returns the file for the module on the host system that is
472   /// running LLDB. This can differ from the path on the platform since we
473   /// might be doing remote debugging.
474   ///
475   /// \return
476   ///     A const reference to the file specification object.
477   const FileSpec &GetFileSpec() const { return m_file; }
478 
479   /// Get accessor for the module platform file specification.
480   ///
481   /// Platform file refers to the path of the module as it is known on the
482   /// remote system on which it is being debugged. For local debugging this is
483   /// always the same as Module::GetFileSpec(). But remote debugging might
484   /// mention a file "/usr/lib/liba.dylib" which might be locally downloaded
485   /// and cached. In this case the platform file could be something like:
486   /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" The
487   /// file could also be cached in a local developer kit directory.
488   ///
489   /// \return
490   ///     A const reference to the file specification object.
491   const FileSpec &GetPlatformFileSpec() const {
492     if (m_platform_file)
493       return m_platform_file;
494     return m_file;
495   }
496 
497   void SetPlatformFileSpec(const FileSpec &file) { m_platform_file = file; }
498 
499   const FileSpec &GetRemoteInstallFileSpec() const {
500     return m_remote_install_file;
501   }
502 
503   void SetRemoteInstallFileSpec(const FileSpec &file) {
504     m_remote_install_file = file;
505   }
506 
507   const FileSpec &GetSymbolFileFileSpec() const { return m_symfile_spec; }
508 
509   void PreloadSymbols();
510 
511   void SetSymbolFileFileSpec(const FileSpec &file);
512 
513   const llvm::sys::TimePoint<> &GetModificationTime() const {
514     return m_mod_time;
515   }
516 
517   const llvm::sys::TimePoint<> &GetObjectModificationTime() const {
518     return m_object_mod_time;
519   }
520 
521   /// This callback will be called by SymbolFile implementations when
522   /// parsing a compile unit that contains SDK information.
523   /// \param sysroot will be added to the path remapping dictionary.
524   void RegisterXcodeSDK(llvm::StringRef sdk, llvm::StringRef sysroot);
525 
526   /// Tells whether this module is capable of being the main executable for a
527   /// process.
528   ///
529   /// \return
530   ///     \b true if it is, \b false otherwise.
531   bool IsExecutable();
532 
533   /// Tells whether this module has been loaded in the target passed in. This
534   /// call doesn't distinguish between whether the module is loaded by the
535   /// dynamic loader, or by a "target module add" type call.
536   ///
537   /// \param[in] target
538   ///    The target to check whether this is loaded in.
539   ///
540   /// \return
541   ///     \b true if it is, \b false otherwise.
542   bool IsLoadedInTarget(Target *target);
543 
544   bool LoadScriptingResourceInTarget(Target *target, Status &error,
545                                      Stream *feedback_stream = nullptr);
546 
547   /// Get the number of compile units for this module.
548   ///
549   /// \return
550   ///     The number of compile units that the symbol vendor plug-in
551   ///     finds.
552   size_t GetNumCompileUnits();
553 
554   lldb::CompUnitSP GetCompileUnitAtIndex(size_t idx);
555 
556   ConstString GetObjectName() const;
557 
558   uint64_t GetObjectOffset() const { return m_object_offset; }
559 
560   /// Get the object file representation for the current architecture.
561   ///
562   /// If the object file has not been located or parsed yet, this function
563   /// will find the best ObjectFile plug-in that can parse Module::m_file.
564   ///
565   /// \return
566   ///     If Module::m_file does not exist, or no plug-in was found
567   ///     that can parse the file, or the object file doesn't contain
568   ///     the current architecture in Module::m_arch, nullptr will be
569   ///     returned, else a valid object file interface will be
570   ///     returned. The returned pointer is owned by this object and
571   ///     remains valid as long as the object is around.
572   virtual ObjectFile *GetObjectFile();
573 
574   /// Get the unified section list for the module. This is the section list
575   /// created by the module's object file and any debug info and symbol files
576   /// created by the symbol vendor.
577   ///
578   /// If the symbol vendor has not been loaded yet, this function will return
579   /// the section list for the object file.
580   ///
581   /// \return
582   ///     Unified module section list.
583   virtual SectionList *GetSectionList();
584 
585   /// Notify the module that the file addresses for the Sections have been
586   /// updated.
587   ///
588   /// If the Section file addresses for a module are updated, this method
589   /// should be called.  Any parts of the module, object file, or symbol file
590   /// that has cached those file addresses must invalidate or update its
591   /// cache.
592   virtual void SectionFileAddressesChanged();
593 
594   /// Returns a reference to the UnwindTable for this Module
595   ///
596   /// The UnwindTable contains FuncUnwinders objects for any function in this
597   /// Module.  If a FuncUnwinders object hasn't been created yet (i.e. the
598   /// function has yet to be unwound in a stack walk), it will be created when
599   /// requested.  Specifically, we do not create FuncUnwinders objects for
600   /// functions until they are needed.
601   ///
602   /// \return
603   ///     Returns the unwind table for this module. If this object has no
604   ///     associated object file, an empty UnwindTable is returned.
605   UnwindTable &GetUnwindTable();
606 
607   llvm::VersionTuple GetVersion();
608 
609   /// Load an object file from memory.
610   ///
611   /// If available, the size of the object file in memory may be passed to
612   /// avoid additional round trips to process memory. If the size is not
613   /// provided, a default value is used. This value should be large enough to
614   /// enable the ObjectFile plugins to read the header of the object file
615   /// without going back to the process.
616   ///
617   /// \return
618   ///     The object file loaded from memory or nullptr, if the operation
619   ///     failed (see the `error` for more information in that case).
620   ObjectFile *GetMemoryObjectFile(const lldb::ProcessSP &process_sp,
621                                   lldb::addr_t header_addr, Status &error,
622                                   size_t size_to_read = 512);
623 
624   /// Get the module's symbol file
625   ///
626   /// If the symbol file has already been loaded, this function returns it. All
627   /// arguments are ignored. If the symbol file has not been located yet, and
628   /// the can_create argument is false, the function returns nullptr. If
629   /// can_create is true, this function will find the best SymbolFile plug-in
630   /// that can use the current object file. feedback_strm, if not null, is used
631   /// to report the details of the search process.
632   virtual SymbolFile *GetSymbolFile(bool can_create = true,
633                                     Stream *feedback_strm = nullptr);
634 
635   Symtab *GetSymtab();
636 
637   /// Get a reference to the UUID value contained in this object.
638   ///
639   /// If the executable image file doesn't not have a UUID value built into
640   /// the file format, an MD5 checksum of the entire file, or slice of the
641   /// file for the current architecture should be used.
642   ///
643   /// \return
644   ///     A const pointer to the internal copy of the UUID value in
645   ///     this module if this module has a valid UUID value, NULL
646   ///     otherwise.
647   const lldb_private::UUID &GetUUID();
648 
649   /// A debugging function that will cause everything in a module to
650   /// be parsed.
651   ///
652   /// All compile units will be parsed, along with all globals and static
653   /// variables and all functions for those compile units. All types, scopes,
654   /// local variables, static variables, global variables, and line tables
655   /// will be parsed. This can be used prior to dumping a module to see a
656   /// complete list of the resulting debug information that gets parsed, or as
657   /// a debug function to ensure that the module can consume all of the debug
658   /// data the symbol vendor provides.
659   void ParseAllDebugSymbols();
660 
661   bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr);
662 
663   /// Resolve the symbol context for the given address.
664   ///
665   /// Tries to resolve the matching symbol context based on a lookup from the
666   /// current symbol vendor.  If the lazy lookup fails, an attempt is made to
667   /// parse the eh_frame section to handle stripped symbols.  If this fails,
668   /// an attempt is made to resolve the symbol to the previous address to
669   /// handle the case of a function with a tail call.
670   ///
671   /// Use properties of the modified SymbolContext to inspect any resolved
672   /// target, module, compilation unit, symbol, function, function block or
673   /// line entry.  Use the return value to determine which of these properties
674   /// have been modified.
675   ///
676   /// \param[in] so_addr
677   ///     A load address to resolve.
678   ///
679   /// \param[in] resolve_scope
680   ///     The scope that should be resolved (see SymbolContext::Scope).
681   ///     A combination of flags from the enumeration SymbolContextItem
682   ///     requesting a resolution depth.  Note that the flags that are
683   ///     actually resolved may be a superset of the requested flags.
684   ///     For instance, eSymbolContextSymbol requires resolution of
685   ///     eSymbolContextModule, and eSymbolContextFunction requires
686   ///     eSymbolContextSymbol.
687   ///
688   /// \param[out] sc
689   ///     The SymbolContext that is modified based on symbol resolution.
690   ///
691   /// \param[in] resolve_tail_call_address
692   ///     Determines if so_addr should resolve to a symbol in the case
693   ///     of a function whose last instruction is a call.  In this case,
694   ///     the PC can be one past the address range of the function.
695   ///
696   /// \return
697   ///     The scope that has been resolved (see SymbolContext::Scope).
698   ///
699   /// \see SymbolContext::Scope
700   uint32_t ResolveSymbolContextForAddress(
701       const Address &so_addr, lldb::SymbolContextItem resolve_scope,
702       SymbolContext &sc, bool resolve_tail_call_address = false);
703 
704   /// Resolve items in the symbol context for a given file and line.
705   ///
706   /// Tries to resolve \a file_path and \a line to a list of matching symbol
707   /// contexts.
708   ///
709   /// The line table entries contains addresses that can be used to further
710   /// resolve the values in each match: the function, block, symbol. Care
711   /// should be taken to minimize the amount of information that is requested
712   /// to only what is needed -- typically the module, compile unit, line table
713   /// and line table entry are sufficient.
714   ///
715   /// \param[in] file_path
716   ///     A path to a source file to match. If \a file_path does not
717   ///     specify a directory, then this query will match all files
718   ///     whose base filename matches. If \a file_path does specify
719   ///     a directory, the fullpath to the file must match.
720   ///
721   /// \param[in] line
722   ///     The source line to match, or zero if just the compile unit
723   ///     should be resolved.
724   ///
725   /// \param[in] check_inlines
726   ///     Check for inline file and line number matches. This option
727   ///     should be used sparingly as it will cause all line tables
728   ///     for every compile unit to be parsed and searched for
729   ///     matching inline file entries.
730   ///
731   /// \param[in] resolve_scope
732   ///     The scope that should be resolved (see
733   ///     SymbolContext::Scope).
734   ///
735   /// \param[out] sc_list
736   ///     A symbol context list that gets matching symbols contexts
737   ///     appended to.
738   ///
739   /// \return
740   ///     The number of matches that were added to \a sc_list.
741   ///
742   /// \see SymbolContext::Scope
743   uint32_t ResolveSymbolContextForFilePath(
744       const char *file_path, uint32_t line, bool check_inlines,
745       lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list);
746 
747   /// Resolve items in the symbol context for a given file and line.
748   ///
749   /// Tries to resolve \a file_spec and \a line to a list of matching symbol
750   /// contexts.
751   ///
752   /// The line table entries contains addresses that can be used to further
753   /// resolve the values in each match: the function, block, symbol. Care
754   /// should be taken to minimize the amount of information that is requested
755   /// to only what is needed -- typically the module, compile unit, line table
756   /// and line table entry are sufficient.
757   ///
758   /// \param[in] file_spec
759   ///     A file spec to a source file to match. If \a file_path does
760   ///     not specify a directory, then this query will match all
761   ///     files whose base filename matches. If \a file_path does
762   ///     specify a directory, the fullpath to the file must match.
763   ///
764   /// \param[in] line
765   ///     The source line to match, or zero if just the compile unit
766   ///     should be resolved.
767   ///
768   /// \param[in] check_inlines
769   ///     Check for inline file and line number matches. This option
770   ///     should be used sparingly as it will cause all line tables
771   ///     for every compile unit to be parsed and searched for
772   ///     matching inline file entries.
773   ///
774   /// \param[in] resolve_scope
775   ///     The scope that should be resolved (see
776   ///     SymbolContext::Scope).
777   ///
778   /// \param[out] sc_list
779   ///     A symbol context list that gets filled in with all of the
780   ///     matches.
781   ///
782   /// \return
783   ///     A integer that contains SymbolContext::Scope bits set for
784   ///     each item that was successfully resolved.
785   ///
786   /// \see SymbolContext::Scope
787   uint32_t ResolveSymbolContextsForFileSpec(
788       const FileSpec &file_spec, uint32_t line, bool check_inlines,
789       lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list);
790 
791   void SetFileSpecAndObjectName(const FileSpec &file, ConstString object_name);
792 
793   bool GetIsDynamicLinkEditor();
794 
795   llvm::Expected<TypeSystem &>
796   GetTypeSystemForLanguage(lldb::LanguageType language);
797 
798   // Special error functions that can do printf style formatting that will
799   // prepend the message with something appropriate for this module (like the
800   // architecture, path and object name (if any)). This centralizes code so
801   // that everyone doesn't need to format their error and log messages on their
802   // own and keeps the output a bit more consistent.
803   void LogMessage(Log *log, const char *format, ...)
804       __attribute__((format(printf, 3, 4)));
805 
806   void LogMessageVerboseBacktrace(Log *log, const char *format, ...)
807       __attribute__((format(printf, 3, 4)));
808 
809   void ReportWarning(const char *format, ...)
810       __attribute__((format(printf, 2, 3)));
811 
812   void ReportError(const char *format, ...)
813       __attribute__((format(printf, 2, 3)));
814 
815   // Only report an error once when the module is first detected to be modified
816   // so we don't spam the console with many messages.
817   void ReportErrorIfModifyDetected(const char *format, ...)
818       __attribute__((format(printf, 2, 3)));
819 
820   void ReportWarningOptimization(llvm::Optional<lldb::user_id_t> debugger_id);
821 
822   void
823   ReportWarningUnsupportedLanguage(lldb::LanguageType language,
824                                    llvm::Optional<lldb::user_id_t> debugger_id);
825 
826   // Return true if the file backing this module has changed since the module
827   // was originally created  since we saved the initial file modification time
828   // when the module first gets created.
829   bool FileHasChanged() const;
830 
831   // SymbolFile and ObjectFile member objects should lock the
832   // module mutex to avoid deadlocks.
833   std::recursive_mutex &GetMutex() const { return m_mutex; }
834 
835   PathMappingList &GetSourceMappingList() { return m_source_mappings; }
836 
837   const PathMappingList &GetSourceMappingList() const {
838     return m_source_mappings;
839   }
840 
841   /// Finds a source file given a file spec using the module source path
842   /// remappings (if any).
843   ///
844   /// Tries to resolve \a orig_spec by checking the module source path
845   /// remappings. It makes sure the file exists, so this call can be expensive
846   /// if the remappings are on a network file system, so use this function
847   /// sparingly (not in a tight debug info parsing loop).
848   ///
849   /// \param[in] orig_spec
850   ///     The original source file path to try and remap.
851   ///
852   /// \param[out] new_spec
853   ///     The newly remapped filespec that is guaranteed to exist.
854   ///
855   /// \return
856   ///     /b true if \a orig_spec was successfully located and
857   ///     \a new_spec is filled in with an existing file spec,
858   ///     \b false otherwise.
859   bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
860 
861   /// Remaps a source file given \a path into \a new_path.
862   ///
863   /// Remaps \a path if any source remappings match. This function does NOT
864   /// stat the file system so it can be used in tight loops where debug info
865   /// is being parsed.
866   ///
867   /// \param[in] path
868   ///     The original source file path to try and remap.
869   ///
870   /// \return
871   ///     The newly remapped filespec that is may or may not exist if
872   ///     \a path was successfully located.
873   llvm::Optional<std::string> RemapSourceFile(llvm::StringRef path) const;
874   bool RemapSourceFile(const char *, std::string &) const = delete;
875 
876   /// Update the ArchSpec to a more specific variant.
877   bool MergeArchitecture(const ArchSpec &arch_spec);
878 
879   /// Accessor for the symbol table parse time metric.
880   ///
881   /// The value is returned as a reference to allow it to be updated by the
882   /// ElapsedTime RAII object.
883   StatsDuration &GetSymtabParseTime() { return m_symtab_parse_time; }
884 
885   /// Accessor for the symbol table index time metric.
886   ///
887   /// The value is returned as a reference to allow it to be updated by the
888   /// ElapsedTime RAII object.
889   StatsDuration &GetSymtabIndexTime() { return m_symtab_index_time; }
890 
891   /// \class LookupInfo Module.h "lldb/Core/Module.h"
892   /// A class that encapsulates name lookup information.
893   ///
894   /// Users can type a wide variety of partial names when setting breakpoints
895   /// by name or when looking for functions by name. The SymbolFile object is
896   /// only required to implement name lookup for function basenames and for
897   /// fully mangled names. This means if the user types in a partial name, we
898   /// must reduce this to a name lookup that will work with all SymbolFile
899   /// objects. So we might reduce a name lookup to look for a basename, and then
900   /// prune out any results that don't match.
901   ///
902   /// The "m_name" member variable represents the name as it was typed by the
903   /// user. "m_lookup_name" will be the name we actually search for through
904   /// the symbol or objects files. Lanaguage is included in case we need to
905   /// filter results by language at a later date. The "m_name_type_mask"
906   /// member variable tells us what kinds of names we are looking for and can
907   /// help us prune out unwanted results.
908   ///
909   /// Function lookups are done in Module.cpp, ModuleList.cpp and in
910   /// BreakpointResolverName.cpp and they all now use this class to do lookups
911   /// correctly.
912   class LookupInfo {
913   public:
914     LookupInfo() = default;
915 
916     LookupInfo(ConstString name, lldb::FunctionNameType name_type_mask,
917                lldb::LanguageType language);
918 
919     ConstString GetName() const { return m_name; }
920 
921     void SetName(ConstString name) { m_name = name; }
922 
923     ConstString GetLookupName() const { return m_lookup_name; }
924 
925     void SetLookupName(ConstString name) { m_lookup_name = name; }
926 
927     lldb::FunctionNameType GetNameTypeMask() const { return m_name_type_mask; }
928 
929     void SetNameTypeMask(lldb::FunctionNameType mask) {
930       m_name_type_mask = mask;
931     }
932 
933     void Prune(SymbolContextList &sc_list, size_t start_idx) const;
934 
935   protected:
936     /// What the user originally typed
937     ConstString m_name;
938 
939     /// The actual name will lookup when calling in the object or symbol file
940     ConstString m_lookup_name;
941 
942     /// Limit matches to only be for this language
943     lldb::LanguageType m_language = lldb::eLanguageTypeUnknown;
944 
945     /// One or more bits from lldb::FunctionNameType that indicate what kind of
946     /// names we are looking for
947     lldb::FunctionNameType m_name_type_mask = lldb::eFunctionNameTypeNone;
948 
949     ///< If \b true, then demangled names that match will need to contain
950     ///< "m_name" in order to be considered a match
951     bool m_match_name_after_lookup = false;
952   };
953 
954   /// Get a unique hash for this module.
955   ///
956   /// The hash should be enough to identify the file on disk and the
957   /// architecture of the file. If the module represents an object inside of a
958   /// file, then the hash should include the object name and object offset to
959   /// ensure a unique hash. Some examples:
960   /// - just a regular object file (mach-o, elf, coff, etc) should create a hash
961   /// - a universal mach-o file that contains to multiple architectures,
962   ///   each architecture slice should have a unique hash even though they come
963   ///   from the same file
964   /// - a .o file inside of a BSD archive. Each .o file will have an object name
965   ///   and object offset that should produce a unique hash. The object offset
966   ///   is needed as BSD archive files can contain multiple .o files that have
967   ///   the same name.
968   uint32_t Hash();
969 
970   /// Get a unique cache key for the current module.
971   ///
972   /// The cache key must be unique for a file on disk and not change if the file
973   /// is updated. This allows cache data to use this key as a prefix and as
974   /// files are modified in disk, we will overwrite the cache files. If one file
975   /// can contain multiple files, like a universal mach-o file or like a BSD
976   /// archive, the cache key must contain enough information to differentiate
977   /// these different files.
978   std::string GetCacheKey();
979 
980   /// Get the global index file cache.
981   ///
982   /// LLDB can cache data for a module between runs. This cache directory can be
983   /// used to stored data that previously was manually created each time you debug.
984   /// Examples include debug information indexes, symbol tables, symbol table
985   /// indexes, and more.
986   ///
987   /// \returns
988   ///   If caching is enabled in the lldb settings, return a pointer to the data
989   ///   file cache. If caching is not enabled, return NULL.
990   static DataFileCache *GetIndexCache();
991 protected:
992   // Member Variables
993   mutable std::recursive_mutex m_mutex; ///< A mutex to keep this object happy
994                                         /// in multi-threaded environments.
995 
996   /// The modification time for this module when it was created.
997   llvm::sys::TimePoint<> m_mod_time;
998 
999   ArchSpec m_arch; ///< The architecture for this module.
1000   UUID m_uuid; ///< Each module is assumed to have a unique identifier to help
1001                /// match it up to debug symbols.
1002   FileSpec m_file; ///< The file representation on disk for this module (if
1003                    /// there is one).
1004   FileSpec m_platform_file; ///< The path to the module on the platform on which
1005                             /// it is being debugged
1006   FileSpec m_remote_install_file; ///< If set when debugging on remote
1007                                   /// platforms, this module will be installed
1008                                   /// at this location
1009   FileSpec m_symfile_spec;   ///< If this path is valid, then this is the file
1010                              /// that _will_ be used as the symbol file for this
1011                              /// module
1012   ConstString m_object_name; ///< The name an object within this module that is
1013                              /// selected, or empty of the module is represented
1014                              /// by \a m_file.
1015   uint64_t m_object_offset = 0;
1016   llvm::sys::TimePoint<> m_object_mod_time;
1017 
1018   /// DataBuffer containing the module image, if it was provided at
1019   /// construction time. Otherwise the data will be retrieved by mapping
1020   /// one of the FileSpec members above.
1021   lldb::DataBufferSP m_data_sp;
1022 
1023   lldb::ObjectFileSP m_objfile_sp; ///< A shared pointer to the object file
1024                                    /// parser for this module as it may or may
1025                                    /// not be shared with the SymbolFile
1026   llvm::Optional<UnwindTable> m_unwind_table; ///< Table of FuncUnwinders
1027                                               /// objects created for this
1028                                               /// Module's functions
1029   lldb::SymbolVendorUP
1030       m_symfile_up; ///< A pointer to the symbol vendor for this module.
1031   std::vector<lldb::SymbolVendorUP>
1032       m_old_symfiles; ///< If anyone calls Module::SetSymbolFileFileSpec() and
1033                       /// changes the symbol file,
1034   ///< we need to keep all old symbol files around in case anyone has type
1035   /// references to them
1036   TypeSystemMap m_type_system_map; ///< A map of any type systems associated
1037                                    /// with this module
1038   /// Module specific source remappings for when you have debug info for a
1039   /// module that doesn't match where the sources currently are.
1040   PathMappingList m_source_mappings =
1041       ModuleList::GetGlobalModuleListProperties().GetSymlinkMappings();
1042 
1043   lldb::SectionListUP m_sections_up; ///< Unified section list for module that
1044                                      /// is used by the ObjectFile and and
1045                                      /// ObjectFile instances for the debug info
1046 
1047   std::atomic<bool> m_did_load_objfile{false};
1048   std::atomic<bool> m_did_load_symfile{false};
1049   std::atomic<bool> m_did_set_uuid{false};
1050   mutable bool m_file_has_changed : 1,
1051       m_first_file_changed_log : 1; /// See if the module was modified after it
1052                                     /// was initially opened.
1053   /// We store a symbol table parse time duration here because we might have
1054   /// an object file and a symbol file which both have symbol tables. The parse
1055   /// time for the symbol tables can be aggregated here.
1056   StatsDuration m_symtab_parse_time;
1057   /// We store a symbol named index time duration here because we might have
1058   /// an object file and a symbol file which both have symbol tables. The parse
1059   /// time for the symbol tables can be aggregated here.
1060   StatsDuration m_symtab_index_time;
1061 
1062   std::once_flag m_optimization_warning;
1063   std::once_flag m_language_warning;
1064 
1065   /// Resolve a file or load virtual address.
1066   ///
1067   /// Tries to resolve \a vm_addr as a file address (if \a
1068   /// vm_addr_is_file_addr is true) or as a load address if \a
1069   /// vm_addr_is_file_addr is false) in the symbol vendor. \a resolve_scope
1070   /// indicates what clients wish to resolve and can be used to limit the
1071   /// scope of what is parsed.
1072   ///
1073   /// \param[in] vm_addr
1074   ///     The load virtual address to resolve.
1075   ///
1076   /// \param[in] vm_addr_is_file_addr
1077   ///     If \b true, \a vm_addr is a file address, else \a vm_addr
1078   ///     if a load address.
1079   ///
1080   /// \param[in] resolve_scope
1081   ///     The scope that should be resolved (see
1082   ///     SymbolContext::Scope).
1083   ///
1084   /// \param[out] so_addr
1085   ///     The section offset based address that got resolved if
1086   ///     any bits are returned.
1087   ///
1088   /// \param[out] sc
1089   //      The symbol context that has objects filled in. Each bit
1090   ///     in the \a resolve_scope pertains to a member in the \a sc.
1091   ///
1092   /// \return
1093   ///     A integer that contains SymbolContext::Scope bits set for
1094   ///     each item that was successfully resolved.
1095   ///
1096   /// \see SymbolContext::Scope
1097   uint32_t ResolveSymbolContextForAddress(lldb::addr_t vm_addr,
1098                                           bool vm_addr_is_file_addr,
1099                                           lldb::SymbolContextItem resolve_scope,
1100                                           Address &so_addr, SymbolContext &sc);
1101 
1102   void SymbolIndicesToSymbolContextList(Symtab *symtab,
1103                                         std::vector<uint32_t> &symbol_indexes,
1104                                         SymbolContextList &sc_list);
1105 
1106   bool SetArchitecture(const ArchSpec &new_arch);
1107 
1108   void SetUUID(const lldb_private::UUID &uuid);
1109 
1110   SectionList *GetUnifiedSectionList();
1111 
1112   friend class ModuleList;
1113   friend class ObjectFile;
1114   friend class SymbolFile;
1115 
1116 private:
1117   Module(); // Only used internally by CreateJITModule ()
1118 
1119   void FindTypes_Impl(
1120       ConstString name, const CompilerDeclContext &parent_decl_ctx,
1121       size_t max_matches,
1122       llvm::DenseSet<lldb_private::SymbolFile *> &searched_symbol_files,
1123       TypeMap &types);
1124 
1125   Module(const Module &) = delete;
1126   const Module &operator=(const Module &) = delete;
1127 };
1128 
1129 } // namespace lldb_private
1130 
1131 #endif // LLDB_CORE_MODULE_H
1132