contrib/llvm/tools/lldb/include/lldb/Core/ModuleList.h

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