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"
  14 #include "lldb/Core/ModuleSpec.h"
  15 #include "lldb/Core/UserSettingsController.h"
  16 #include "lldb/Utility/FileSpec.h"
  17 #include "lldb/Utility/Iterable.h"
  18 #include "lldb/Utility/Status.h"
  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>
  31 #include <stdint.h>
  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,
 304                        lldb::FunctionNameType name_type_mask,
 305                        bool include_symbols, bool include_inlines, bool append,
 306                        SymbolContextList &sc_list) const;
 307
 308   //------------------------------------------------------------------
 309   /// @see Module::FindFunctionSymbols ()
 310   //------------------------------------------------------------------
 311   size_t FindFunctionSymbols(const ConstString &name,
 312                              lldb::FunctionNameType name_type_mask,
 313                              SymbolContextList &sc_list);
 314
 315   //------------------------------------------------------------------
 316   /// @see Module::FindFunctions ()
 317   //------------------------------------------------------------------
 318   size_t FindFunctions(const RegularExpression &name, bool include_symbols,
 319                        bool include_inlines, bool append,
 320                        SymbolContextList &sc_list);
 321
 322   //------------------------------------------------------------------
 323   /// Find global and static variables by name.
 324   ///
 325   /// @param[in] name
 326   ///     The name of the global or static variable we are looking
 327   ///     for.
 328   ///
 329   /// @param[in] max_matches
 330   ///     Allow the number of matches to be limited to \a
 331   ///     max_matches. Specify UINT32_MAX to get all possible matches.
 332   ///
 333   /// @param[in] variable_list
 334   ///     A list of variables that gets the matches appended to.
 335   ///
 336   /// @return
 337   ///     The number of matches added to \a variable_list.
 338   //------------------------------------------------------------------
 339   size_t FindGlobalVariables(const ConstString &name, size_t max_matches,
 340                              VariableList &variable_list) const;
 341
 342   //------------------------------------------------------------------
 343   /// Find global and static variables by regular expression.
 344   ///
 345   /// @param[in] regex
 346   ///     A regular expression to use when matching the name.
 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[in] variable_list
 353   ///     A list of variables that gets the matches appended to.
 354   ///
 355   /// @return
 356   ///     The number of matches added to \a variable_list.
 357   //------------------------------------------------------------------
 358   size_t FindGlobalVariables(const RegularExpression &regex, size_t max_matches,
 359                              VariableList &variable_list) const;
 360
 361   //------------------------------------------------------------------
 362   /// Finds the first module whose file specification matches \a file_spec.
 363   ///
 364   /// @param[in] file_spec_ptr
 365   ///     A file specification object to match against the Module's
 366   ///     file specifications. If \a file_spec does not have
 367   ///     directory information, matches will occur by matching only
 368   ///     the basename of any modules in this list. If this value is
 369   ///     NULL, then file specifications won't be compared when
 370   ///     searching for matching modules.
 371   ///
 372   /// @param[in] arch_ptr
 373   ///     The architecture to search for if non-NULL. If this value
 374   ///     is NULL no architecture matching will be performed.
 375   ///
 376   /// @param[in] uuid_ptr
 377   ///     The uuid to search for if non-NULL. If this value is NULL
 378   ///     no uuid matching will be performed.
 379   ///
 380   /// @param[in] object_name
 381   ///     An optional object name that must match as well. This value
 382   ///     can be NULL.
 383   ///
 384   /// @param[out] matching_module_list
 385   ///     A module list that gets filled in with any modules that
 386   ///     match the search criteria.
 387   ///
 388   /// @return
 389   ///     The number of matching modules found by the search.
 390   //------------------------------------------------------------------
 391   size_t FindModules(const ModuleSpec &module_spec,
 392                      ModuleList &matching_module_list) const;
 393
 394   lldb::ModuleSP FindModule(const Module *module_ptr) const;
 395
 396   //------------------------------------------------------------------
 397   // Find a module by UUID
 398   //
 399   // The UUID value for a module is extracted from the ObjectFile and is the
 400   // MD5 checksum, or a smarter object file equivalent, so finding modules by
 401   // UUID values is very efficient and accurate.
 402   //------------------------------------------------------------------
 403   lldb::ModuleSP FindModule(const UUID &uuid) const;
 404
 405   lldb::ModuleSP FindFirstModule(const ModuleSpec &module_spec) const;
 406
 407   size_t FindSymbolsWithNameAndType(const ConstString &name,
 408                                     lldb::SymbolType symbol_type,
 409                                     SymbolContextList &sc_list,
 410                                     bool append = false) const;
 411
 412   size_t FindSymbolsMatchingRegExAndType(const RegularExpression &regex,
 413                                          lldb::SymbolType symbol_type,
 414                                          SymbolContextList &sc_list,
 415                                          bool append = false) const;
 416
 417   //------------------------------------------------------------------
 418   /// Find types by name.
 419   ///
 420   /// @param[in] search_first
 421   ///     If non-null, this module will be searched before any other
 422   ///     modules.
 423   ///
 424   /// @param[in] name
 425   ///     The name of the type we are looking for.
 426   ///
 427   /// @param[in] append
 428   ///     If \b true, any matches will be appended to \a
 429   ///     variable_list, else matches replace the contents of
 430   ///     \a variable_list.
 431   ///
 432   /// @param[in] max_matches
 433   ///     Allow the number of matches to be limited to \a
 434   ///     max_matches. Specify UINT32_MAX to get all possible matches.
 435   ///
 436   /// @param[in] encoding
 437   ///     Limit the search to specific types, or get all types if
 438   ///     set to Type::invalid.
 439   ///
 440   /// @param[in] udt_name
 441   ///     If the encoding is a user defined type, specify the name
 442   ///     of the user defined type ("struct", "union", "class", etc).
 443   ///
 444   /// @param[out] type_list
 445   ///     A type list gets populated with any matches.
 446   ///
 447   /// @return
 448   ///     The number of matches added to \a type_list.
 449   //------------------------------------------------------------------
 450   size_t FindTypes(Module *search_first, const ConstString &name,
 451                    bool name_is_fully_qualified, size_t max_matches,
 452                    llvm::DenseSet<SymbolFile *> &searched_symbol_files,
 453                    TypeList &types) const;
 454
 455   bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
 456
 457   //------------------------------------------------------------------
 458   /// Find addresses by file/line
 459   ///
 460   /// @param[in] target_sp
 461   ///     The target the addresses are desired for.
 462   ///
 463   /// @param[in] file
 464   ///     Source file to locate.
 465   ///
 466   /// @param[in] line
 467   ///     Source line to locate.
 468   ///
 469   /// @param[in] function
 470   ///     Optional filter function. Addresses within this function will be
 471   ///     added to the 'local' list. All others will be added to the 'extern'
 472   ///     list.
 473   ///
 474   /// @param[out] output_local
 475   ///     All matching addresses within 'function'
 476   ///
 477   /// @param[out] output_extern
 478   ///     All matching addresses not within 'function'
 479   void FindAddressesForLine(const lldb::TargetSP target_sp,
 480                             const FileSpec &file, uint32_t line,
 481                             Function *function,
 482                             std::vector<Address> &output_local,
 483                             std::vector<Address> &output_extern);
 484
 485   bool Remove(const lldb::ModuleSP &module_sp);
 486
 487   size_t Remove(ModuleList &module_list);
 488
 489   bool RemoveIfOrphaned(const Module *module_ptr);
 490
 491   size_t RemoveOrphans(bool mandatory);
 492
 493   bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr) const;
 494
 495   //------------------------------------------------------------------
 496   /// @copydoc Module::ResolveSymbolContextForAddress (const Address
 497   /// &,uint32_t,SymbolContext&)
 498   //------------------------------------------------------------------
 499   uint32_t ResolveSymbolContextForAddress(const Address &so_addr,
 500                                           lldb::SymbolContextItem resolve_scope,
 501                                           SymbolContext &sc) const;
 502
 503   //------------------------------------------------------------------
 504   /// @copydoc Module::ResolveSymbolContextForFilePath (const char
 505   /// *,uint32_t,bool,uint32_t,SymbolContextList&)
 506   //------------------------------------------------------------------
 507   uint32_t ResolveSymbolContextForFilePath(
 508       const char *file_path, uint32_t line, bool check_inlines,
 509       lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list) const;
 510
 511   //------------------------------------------------------------------
 512   /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec
 513   /// &,uint32_t,bool,uint32_t,SymbolContextList&)
 514   //------------------------------------------------------------------
 515   uint32_t ResolveSymbolContextsForFileSpec(
 516       const FileSpec &file_spec, uint32_t line, bool check_inlines,
 517       lldb::SymbolContextItem resolve_scope, 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_