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 GetMutex()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 ®ex, 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 ®ex, 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; Modules()582 ModuleIterable Modules() { return ModuleIterable(m_modules, GetMutex()); } 583 584 typedef AdaptedIterable<collection, lldb::ModuleSP, vector_adapter> 585 ModuleIterableNoLocking; ModulesNoLocking()586 ModuleIterableNoLocking ModulesNoLocking() { 587 return ModuleIterableNoLocking(m_modules); 588 } 589 }; 590 591 } // namespace lldb_private 592 593 #endif // liblldb_ModuleList_h_ 594