LLDB  mainline
ModuleList.h
Go to the documentation of this file.
1 //===-- ModuleList.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 liblldb_ModuleList_h_
10 #define liblldb_ModuleList_h_
11 
12 #include "lldb/Core/Address.h"
13 #include "lldb/Core/ModuleSpec.h"
15 #include "lldb/Utility/FileSpec.h"
16 #include "lldb/Utility/Iterable.h"
17 #include "lldb/Utility/Status.h"
18 #include "lldb/lldb-enumerations.h"
19 #include "lldb/lldb-forward.h"
20 #include "lldb/lldb-types.h"
21 
22 #include "llvm/ADT/DenseSet.h"
23 
24 #include <functional>
25 #include <list>
26 #include <mutex>
27 #include <vector>
28 
29 #include <stddef.h>
30 #include <stdint.h>
31 
32 namespace lldb_private {
33 class ConstString;
34 }
35 namespace lldb_private {
36 class FileSpecList;
37 }
38 namespace lldb_private {
39 class Function;
40 }
41 namespace lldb_private {
42 class Log;
43 }
44 namespace lldb_private {
45 class Module;
46 }
47 namespace lldb_private {
48 class RegularExpression;
49 }
50 namespace lldb_private {
51 class Stream;
52 }
53 namespace lldb_private {
54 class SymbolContext;
55 }
56 namespace lldb_private {
57 class SymbolContextList;
58 }
59 namespace lldb_private {
60 class SymbolFile;
61 }
62 namespace lldb_private {
63 class Target;
64 }
65 namespace lldb_private {
66 class TypeList;
67 }
68 namespace lldb_private {
69 class UUID;
70 }
71 namespace lldb_private {
72 class VariableList;
73 }
74 
75 namespace lldb_private {
76 
78 public:
80 
82  bool SetClangModulesCachePath(llvm::StringRef path);
83  bool GetEnableExternalLookup() const;
84 };
85 
86 /// \class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
87 /// A collection class for Module objects.
88 ///
89 /// Modules in the module collection class are stored as reference counted
90 /// shared pointers to Module objects.
91 class ModuleList {
92 public:
93  class Notifier {
94  public:
95  virtual ~Notifier() = default;
96 
97  virtual void NotifyModuleAdded(const ModuleList &module_list,
98  const lldb::ModuleSP &module_sp) = 0;
99  virtual void NotifyModuleRemoved(const ModuleList &module_list,
100  const lldb::ModuleSP &module_sp) = 0;
101  virtual void NotifyModuleUpdated(const ModuleList &module_list,
102  const lldb::ModuleSP &old_module_sp,
103  const lldb::ModuleSP &new_module_sp) = 0;
104  virtual void NotifyWillClearList(const ModuleList &module_list) = 0;
105 
106  virtual void NotifyModulesRemoved(lldb_private::ModuleList &module_list) = 0;
107  };
108 
109  /// Default constructor.
110  ///
111  /// Creates an empty list of Module objects.
112  ModuleList();
113 
114  /// Copy Constructor.
115  ///
116  /// Creates a new module list object with a copy of the modules from \a rhs.
117  ///
118  /// \param[in] rhs
119  /// Another module list object.
120  ModuleList(const ModuleList &rhs);
121 
122  ModuleList(ModuleList::Notifier *notifier);
123 
124  /// Destructor.
125  ~ModuleList();
126 
127  /// Assignment operator.
128  ///
129  /// Copies the module list from \a rhs into this list.
130  ///
131  /// \param[in] rhs
132  /// Another module list object.
133  ///
134  /// \return
135  /// A const reference to this object.
136  const ModuleList &operator=(const ModuleList &rhs);
137 
138  /// Append a module to the module list.
139  ///
140  /// \param[in] module_sp
141  /// A shared pointer to a module to add to this collection.
142  ///
143  /// \param[in] notify
144  /// If true, and a notifier function is set, the notifier function
145  /// will be called. Defaults to true.
146  ///
147  /// When this ModuleList is the Target's ModuleList, the notifier
148  /// function is Target::ModulesDidLoad -- the call to
149  /// ModulesDidLoad may be deferred when adding multiple Modules
150  /// to the Target, but it must be called at the end,
151  /// before resuming execution.
152  void Append(const lldb::ModuleSP &module_sp, bool notify = true);
153 
154  /// Append a module to the module list and remove any equivalent modules.
155  /// Equivalent modules are ones whose file, platform file and architecture
156  /// matches.
157  ///
158  /// Replaces the module to the collection.
159  ///
160  /// \param[in] module_sp
161  /// A shared pointer to a module to replace in this collection.
162  void ReplaceEquivalent(const lldb::ModuleSP &module_sp);
163 
164  /// Append a module to the module list, if it is not already there.
165  ///
166  /// \param[in] module_sp
167  ///
168  /// \param[in] notify
169  /// If true, and a notifier function is set, the notifier function
170  /// will be called. Defaults to true.
171  ///
172  /// When this ModuleList is the Target's ModuleList, the notifier
173  /// function is Target::ModulesDidLoad -- the call to
174  /// ModulesDidLoad may be deferred when adding multiple Modules
175  /// to the Target, but it must be called at the end,
176  /// before resuming execution.
177  bool AppendIfNeeded(const lldb::ModuleSP &module_sp, bool notify = true);
178 
179  void Append(const ModuleList &module_list);
180 
181  bool AppendIfNeeded(const ModuleList &module_list);
182 
183  bool ReplaceModule(const lldb::ModuleSP &old_module_sp,
184  const lldb::ModuleSP &new_module_sp);
185 
186  /// Clear the object's state.
187  ///
188  /// Clears the list of modules and releases a reference to each module
189  /// object and if the reference count goes to zero, the module will be
190  /// deleted.
191  void Clear();
192 
193  /// Clear the object's state.
194  ///
195  /// Clears the list of modules and releases a reference to each module
196  /// object and if the reference count goes to zero, the module will be
197  /// deleted. Also release all memory that might be held by any collection
198  /// classes (like std::vector)
199  void Destroy();
200 
201  /// Dump the description of each module contained in this list.
202  ///
203  /// Dump the description of each module contained in this list to the
204  /// supplied stream \a s.
205  ///
206  /// \param[in] s
207  /// The stream to which to dump the object description.
208  ///
209  /// \see Module::Dump(Stream *) const
210  void Dump(Stream *s) const;
211 
212  void LogUUIDAndPaths(Log *log, const char *prefix_cstr);
213 
214  std::recursive_mutex &GetMutex() const { return m_modules_mutex; }
215 
216  size_t GetIndexForModule(const Module *module) const;
217 
218  /// Get the module shared pointer for the module at index \a idx.
219  ///
220  /// \param[in] idx
221  /// An index into this module collection.
222  ///
223  /// \return
224  /// A shared pointer to a Module which can contain NULL if
225  /// \a idx is out of range.
226  ///
227  /// \see ModuleList::GetSize()
228  lldb::ModuleSP GetModuleAtIndex(size_t idx) const;
229 
230  /// Get the module shared pointer for the module at index \a idx without
231  /// acquiring the ModuleList mutex. This MUST already have been acquired
232  /// with ModuleList::GetMutex and locked for this call to be safe.
233  ///
234  /// \param[in] idx
235  /// An index into this module collection.
236  ///
237  /// \return
238  /// A shared pointer to a Module which can contain NULL if
239  /// \a idx is out of range.
240  ///
241  /// \see ModuleList::GetSize()
242  lldb::ModuleSP GetModuleAtIndexUnlocked(size_t idx) const;
243 
244  /// Get the module pointer for the module at index \a idx.
245  ///
246  /// \param[in] idx
247  /// An index into this module collection.
248  ///
249  /// \return
250  /// A pointer to a Module which can by nullptr if \a idx is out
251  /// of range.
252  ///
253  /// \see ModuleList::GetSize()
254  Module *GetModulePointerAtIndex(size_t idx) const;
255 
256  /// Get the module pointer for the module at index \a idx without acquiring
257  /// the ModuleList mutex. This MUST already have been acquired with
258  /// ModuleList::GetMutex and locked for this call to be safe.
259  ///
260  /// \param[in] idx
261  /// An index into this module collection.
262  ///
263  /// \return
264  /// A pointer to a Module which can by nullptr if \a idx is out
265  /// of range.
266  ///
267  /// \see ModuleList::GetSize()
268  Module *GetModulePointerAtIndexUnlocked(size_t idx) const;
269 
270  /// Find compile units by partial or full path.
271  ///
272  /// Finds all compile units that match \a path in all of the modules and
273  /// returns the results in \a sc_list.
274  ///
275  /// \param[in] path
276  /// The name of the compile unit we are looking for.
277  ///
278  /// \param[in] append
279  /// If \b true, then append any compile units that were found
280  /// to \a sc_list. If \b false, then the \a sc_list is cleared
281  /// and the contents of \a sc_list are replaced.
282  ///
283  /// \param[out] sc_list
284  /// A symbol context list that gets filled in with all of the
285  /// matches.
286  ///
287  /// \return
288  /// The number of matches added to \a sc_list.
289  size_t FindCompileUnits(const FileSpec &path, bool append,
290  SymbolContextList &sc_list) const;
291 
292  /// \see Module::FindFunctions ()
293  size_t FindFunctions(ConstString name,
294  lldb::FunctionNameType name_type_mask,
295  bool include_symbols, bool include_inlines, bool append,
296  SymbolContextList &sc_list) const;
297 
298  /// \see Module::FindFunctionSymbols ()
299  size_t FindFunctionSymbols(ConstString name,
300  lldb::FunctionNameType name_type_mask,
301  SymbolContextList &sc_list);
302 
303  /// \see Module::FindFunctions ()
304  size_t FindFunctions(const RegularExpression &name, bool include_symbols,
305  bool include_inlines, bool append,
306  SymbolContextList &sc_list);
307 
308  /// Find global and static variables by name.
309  ///
310  /// \param[in] name
311  /// The name of the global or static variable we are looking
312  /// for.
313  ///
314  /// \param[in] max_matches
315  /// Allow the number of matches to be limited to \a
316  /// max_matches. Specify UINT32_MAX to get all possible matches.
317  ///
318  /// \param[in] variable_list
319  /// A list of variables that gets the matches appended to.
320  ///
321  /// \return
322  /// The number of matches added to \a variable_list.
323  size_t FindGlobalVariables(ConstString name, size_t max_matches,
324  VariableList &variable_list) const;
325 
326  /// Find global and static variables by regular expression.
327  ///
328  /// \param[in] regex
329  /// A regular expression to use when matching the name.
330  ///
331  /// \param[in] max_matches
332  /// Allow the number of matches to be limited to \a
333  /// max_matches. Specify UINT32_MAX to get all possible matches.
334  ///
335  /// \param[in] variable_list
336  /// A list of variables that gets the matches appended to.
337  ///
338  /// \return
339  /// The number of matches added to \a variable_list.
340  size_t FindGlobalVariables(const RegularExpression &regex, size_t max_matches,
341  VariableList &variable_list) const;
342 
343  /// Finds the first module whose file specification matches \a file_spec.
344  ///
345  /// \param[in] file_spec_ptr
346  /// A file specification object to match against the Module's
347  /// file specifications. If \a file_spec does not have
348  /// directory information, matches will occur by matching only
349  /// the basename of any modules in this list. If this value is
350  /// NULL, then file specifications won't be compared when
351  /// searching for matching modules.
352  ///
353  /// \param[in] arch_ptr
354  /// The architecture to search for if non-NULL. If this value
355  /// is NULL no architecture matching will be performed.
356  ///
357  /// \param[in] uuid_ptr
358  /// The uuid to search for if non-NULL. If this value is NULL
359  /// no uuid matching will be performed.
360  ///
361  /// \param[in] object_name
362  /// An optional object name that must match as well. This value
363  /// can be NULL.
364  ///
365  /// \param[out] matching_module_list
366  /// A module list that gets filled in with any modules that
367  /// match the search criteria.
368  ///
369  /// \return
370  /// The number of matching modules found by the search.
371  size_t FindModules(const ModuleSpec &module_spec,
372  ModuleList &matching_module_list) const;
373 
374  lldb::ModuleSP FindModule(const Module *module_ptr) const;
375 
376  // Find a module by UUID
377  //
378  // The UUID value for a module is extracted from the ObjectFile and is the
379  // MD5 checksum, or a smarter object file equivalent, so finding modules by
380  // UUID values is very efficient and accurate.
381  lldb::ModuleSP FindModule(const UUID &uuid) const;
382 
383  lldb::ModuleSP FindFirstModule(const ModuleSpec &module_spec) const;
384 
385  size_t FindSymbolsWithNameAndType(ConstString name,
386  lldb::SymbolType symbol_type,
387  SymbolContextList &sc_list,
388  bool append = false) const;
389 
390  size_t FindSymbolsMatchingRegExAndType(const RegularExpression &regex,
391  lldb::SymbolType symbol_type,
392  SymbolContextList &sc_list,
393  bool append = false) const;
394 
395  /// Find types by name.
396  ///
397  /// \param[in] search_first
398  /// If non-null, this module will be searched before any other
399  /// modules.
400  ///
401  /// \param[in] name
402  /// The name of the type we are looking for.
403  ///
404  /// \param[in] append
405  /// If \b true, any matches will be appended to \a
406  /// variable_list, else matches replace the contents of
407  /// \a variable_list.
408  ///
409  /// \param[in] max_matches
410  /// Allow the number of matches to be limited to \a
411  /// max_matches. Specify UINT32_MAX to get all possible matches.
412  ///
413  /// \param[in] encoding
414  /// Limit the search to specific types, or get all types if
415  /// set to Type::invalid.
416  ///
417  /// \param[in] udt_name
418  /// If the encoding is a user defined type, specify the name
419  /// of the user defined type ("struct", "union", "class", etc).
420  ///
421  /// \param[out] type_list
422  /// A type list gets populated with any matches.
423  ///
424  /// \return
425  /// The number of matches added to \a type_list.
426  size_t FindTypes(Module *search_first, ConstString name,
427  bool name_is_fully_qualified, size_t max_matches,
428  llvm::DenseSet<SymbolFile *> &searched_symbol_files,
429  TypeList &types) const;
430 
431  bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
432 
433  /// Find addresses by file/line
434  ///
435  /// \param[in] target_sp
436  /// The target the addresses are desired for.
437  ///
438  /// \param[in] file
439  /// Source file to locate.
440  ///
441  /// \param[in] line
442  /// Source line to locate.
443  ///
444  /// \param[in] function
445  /// Optional filter function. Addresses within this function will be
446  /// added to the 'local' list. All others will be added to the 'extern'
447  /// list.
448  ///
449  /// \param[out] output_local
450  /// All matching addresses within 'function'
451  ///
452  /// \param[out] output_extern
453  /// All matching addresses not within 'function'
454  void FindAddressesForLine(const lldb::TargetSP target_sp,
455  const FileSpec &file, uint32_t line,
456  Function *function,
457  std::vector<Address> &output_local,
458  std::vector<Address> &output_extern);
459 
460  /// Remove a module from the module list.
461  ///
462  /// \param[in] module_sp
463  /// A shared pointer to a module to remove from this collection.
464  ///
465  /// \param[in] notify
466  /// If true, and a notifier function is set, the notifier function
467  /// will be called. Defaults to true.
468  ///
469  /// When this ModuleList is the Target's ModuleList, the notifier
470  /// function is Target::ModulesDidUnload -- the call to
471  /// ModulesDidUnload may be deferred when removing multiple Modules
472  /// from the Target, but it must be called at the end,
473  /// before resuming execution.
474  bool Remove(const lldb::ModuleSP &module_sp, bool notify = true);
475 
476  size_t Remove(ModuleList &module_list);
477 
478  bool RemoveIfOrphaned(const Module *module_ptr);
479 
480  size_t RemoveOrphans(bool mandatory);
481 
482  bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr) const;
483 
484  /// \copydoc Module::ResolveSymbolContextForAddress (const Address
485  /// &,uint32_t,SymbolContext&)
486  uint32_t ResolveSymbolContextForAddress(const Address &so_addr,
487  lldb::SymbolContextItem resolve_scope,
488  SymbolContext &sc) const;
489 
490  /// \copydoc Module::ResolveSymbolContextForFilePath (const char
491  /// *,uint32_t,bool,uint32_t,SymbolContextList&)
492  uint32_t ResolveSymbolContextForFilePath(
493  const char *file_path, uint32_t line, bool check_inlines,
494  lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list) const;
495 
496  /// \copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec
497  /// &,uint32_t,bool,uint32_t,SymbolContextList&)
498  uint32_t ResolveSymbolContextsForFileSpec(
499  const FileSpec &file_spec, uint32_t line, bool check_inlines,
500  lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list) const;
501 
502  /// Gets the size of the module list.
503  ///
504  /// \return
505  /// The number of modules in the module list.
506  size_t GetSize() const;
507 
508  bool LoadScriptingResourcesInTarget(Target *target, std::list<Status> &errors,
509  Stream *feedback_stream = nullptr,
510  bool continue_on_error = true);
511 
512  static ModuleListProperties &GetGlobalModuleListProperties();
513 
514  static bool ModuleIsInCache(const Module *module_ptr);
515 
516  static Status GetSharedModule(const ModuleSpec &module_spec,
517  lldb::ModuleSP &module_sp,
518  const FileSpecList *module_search_paths_ptr,
519  lldb::ModuleSP *old_module_sp_ptr,
520  bool *did_create_ptr,
521  bool always_create = false);
522 
523  static bool RemoveSharedModule(lldb::ModuleSP &module_sp);
524 
525  static size_t FindSharedModules(const ModuleSpec &module_spec,
526  ModuleList &matching_module_list);
527 
528  static size_t RemoveOrphanSharedModules(bool mandatory);
529 
530  static bool RemoveSharedModuleIfOrphaned(const Module *module_ptr);
531 
532  void ForEach(std::function<bool(const lldb::ModuleSP &module_sp)> const
533  &callback) const;
534 
535 protected:
536  // Class typedefs.
537  typedef std::vector<lldb::ModuleSP>
538  collection; ///< The module collection type.
539 
540  void AppendImpl(const lldb::ModuleSP &module_sp, bool use_notifier = true);
541 
542  bool RemoveImpl(const lldb::ModuleSP &module_sp, bool use_notifier = true);
543 
544  collection::iterator RemoveImpl(collection::iterator pos,
545  bool use_notifier = true);
546 
547  void ClearImpl(bool use_notifier = true);
548 
549  // Member variables.
550  collection m_modules; ///< The collection of modules.
551  mutable std::recursive_mutex m_modules_mutex;
552 
554 
555 public:
556  typedef LockingAdaptedIterable<collection, lldb::ModuleSP, vector_adapter,
557  std::recursive_mutex>
559  ModuleIterable Modules() { return ModuleIterable(m_modules, GetMutex()); }
560 
564  return ModuleIterableNoLocking(m_modules);
565  }
566 };
567 
568 } // namespace lldb_private
569 
570 #endif // liblldb_ModuleList_h_
std::vector< lldb::ModuleSP > collection
The module collection type.
Definition: ModuleList.h:538
Defines a list of symbol context objects.
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
Defines a symbol context baton that can be handed other debug core functions.
Definition: SymbolContext.h:33
ModuleIterableNoLocking ModulesNoLocking()
Definition: ModuleList.h:563
A file utility class.
Definition: FileSpec.h:55
"lldb/Utility/RegularExpression.h" A C++ wrapper class for regex.
A class that describes a function.
Definition: Function.h:323
E vector_adapter(I &iter)
Definition: Iterable.h:21
collection m_modules
The collection of modules.
Definition: ModuleList.h:550
A collection class for Module objects.
Definition: ModuleList.h:91
A class that describes an executable image and its associated object and symbol files.
Definition: Module.h:109
AdaptedIterable< collection, lldb::ModuleSP, vector_adapter > ModuleIterableNoLocking
Definition: ModuleList.h:562
bool SetClangModulesCachePath(llvm::StringRef path)
Definition: ModuleList.cpp:112
A section + offset based address class.
Definition: Address.h:80
LockingAdaptedIterable< collection, lldb::ModuleSP, vector_adapter, std::recursive_mutex > ModuleIterable
Definition: ModuleList.h:558
std::recursive_mutex m_modules_mutex
Definition: ModuleList.h:551
ModuleIterable Modules()
Definition: ModuleList.h:559
uint64_t addr_t
Definition: lldb-types.h:83
A uniqued constant string class.
Definition: ConstString.h:38
FileSpec GetClangModulesCachePath() const
Definition: ModuleList.cpp:105
std::recursive_mutex & GetMutex() const
Definition: ModuleList.h:214
An error handling class.
Definition: Status.h:44