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