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