Coverage Report

Created: 2022-01-18 06:27

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