contrib/llvm-project/lldb/include/lldb/Core/ModuleList.h

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