Module.h revision cbb52a64ea9775af1fcca2e929d0d0b4aa698de4
1//===-- Module.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_Module_h_ 11#define liblldb_Module_h_ 12 13#include "lldb/Core/ArchSpec.h" 14#include "lldb/Core/Section.h" 15#include "lldb/Core/UUID.h" 16#include "lldb/Symbol/ObjectFile.h" 17#include "lldb/Host/Mutex.h" 18#include "lldb/Host/TimeValue.h" 19#include "lldb/Symbol/ClangASTContext.h" 20#include "lldb/Symbol/CompileUnit.h" 21#include "lldb/Symbol/SymbolContext.h" 22#include "lldb/Symbol/Symtab.h" 23#include "lldb/Symbol/TypeList.h" 24 25//---------------------------------------------------------------------- 26/// @class Module Module.h "lldb/Core/Module.h" 27/// @brief A class that describes an executable image and its associated 28/// object and symbol files. 29/// 30/// The module is designed to be able to select a single slice of an 31/// executable image as it would appear on disk and during program 32/// execution. 33/// 34/// Modules control when and if information is parsed according to which 35/// accessors are called. For example the object file (ObjectFile) 36/// representation will only be parsed if the object file is requested 37/// using the Module::GetObjectFile() is called. The debug symbols 38/// will only be parsed if the symbol vendor (SymbolVendor) is 39/// requested using the Module::GetSymbolVendor() is called. 40/// 41/// The module will parse more detailed information as more queries are 42/// made. 43//---------------------------------------------------------------------- 44namespace lldb_private { 45 46class Module : 47 public SymbolContextScope 48{ 49public: 50 friend class ModuleList; 51 friend bool ObjectFile::SetModulesArchitecture (const ArchSpec &new_arch); 52 53 //------------------------------------------------------------------ 54 /// Construct with file specification and architecture. 55 /// 56 /// Clients that wish to share modules with other targets should 57 /// use ModuleList::GetSharedModule(). 58 /// 59 /// @param[in] file_spec 60 /// The file specification for the on disk repesentation of 61 /// this executable image. 62 /// 63 /// @param[in] arch 64 /// The architecture to set as the current architecture in 65 /// this module. 66 /// 67 /// @param[in] object_name 68 /// The name of an object in a module used to extract a module 69 /// within a module (.a files and modules that contain multiple 70 /// architectures). 71 /// 72 /// @param[in] object_offset 73 /// The offset within an existing module used to extract a 74 /// module within a module (.a files and modules that contain 75 /// multiple architectures). 76 //------------------------------------------------------------------ 77 Module (const FileSpec& file_spec, 78 const ArchSpec& arch, 79 const ConstString *object_name = NULL, 80 off_t object_offset = 0); 81 82 //------------------------------------------------------------------ 83 /// Destructor. 84 //------------------------------------------------------------------ 85 virtual 86 ~Module (); 87 88 //------------------------------------------------------------------ 89 /// If you have an instance of Module, get its corresponding shared 90 /// pointer if it has one in the shared module list. 91 //------------------------------------------------------------------ 92 lldb::ModuleSP 93 GetSP () const; 94 95 //------------------------------------------------------------------ 96 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*) 97 /// 98 /// @see SymbolContextScope 99 //------------------------------------------------------------------ 100 virtual void 101 CalculateSymbolContext (SymbolContext* sc); 102 103 void 104 GetDescription (Stream *s); 105 106 //------------------------------------------------------------------ 107 /// Dump a description of this object to a Stream. 108 /// 109 /// Dump a description of the contents of this object to the 110 /// supplied stream \a s. The dumped content will be only what has 111 /// been loaded or parsed up to this point at which this function 112 /// is called, so this is a good way to see what has been parsed 113 /// in a module. 114 /// 115 /// @param[in] s 116 /// The stream to which to dump the object descripton. 117 //------------------------------------------------------------------ 118 void 119 Dump (Stream *s); 120 121 //------------------------------------------------------------------ 122 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*) 123 /// 124 /// @see SymbolContextScope 125 //------------------------------------------------------------------ 126 virtual void 127 DumpSymbolContext (Stream *s); 128 129 //------------------------------------------------------------------ 130 /// Find a symbol in the object files symbol table. 131 /// 132 /// @param[in] name 133 /// The name of the symbol that we are looking for. 134 /// 135 /// @param[in] symbol_type 136 /// If set to eSymbolTypeAny, find a symbol of any type that 137 /// has a name that matches \a name. If set to any other valid 138 /// SymbolType enumeration value, then search only for 139 /// symbols that match \a symbol_type. 140 /// 141 /// @return 142 /// Returns a valid symbol pointer if a symbol was found, 143 /// NULL otherwise. 144 //------------------------------------------------------------------ 145 const Symbol * 146 FindFirstSymbolWithNameAndType (const ConstString &name, 147 lldb::SymbolType symbol_type = lldb::eSymbolTypeAny); 148 149 size_t 150 FindSymbolsWithNameAndType (const ConstString &name, 151 lldb::SymbolType symbol_type, 152 SymbolContextList &sc_list); 153 154 size_t 155 FindSymbolsMatchingRegExAndType (const RegularExpression ®ex, 156 lldb::SymbolType symbol_type, 157 SymbolContextList &sc_list); 158 159 //------------------------------------------------------------------ 160 /// Find functions by name. 161 /// 162 /// @param[in] name 163 /// The name of the function we are looking for. 164 /// 165 /// @param[in] name_type_mask 166 /// A bit mask of bits that indicate what kind of names should 167 /// be used when doing the lookup. Bits include fully qualified 168 /// names, base names, C++ methods, or ObjC selectors. 169 /// See FunctionNameType for more details. 170 /// 171 /// @param[in] append 172 /// If \b true, any matches will be appended to \a sc_list, else 173 /// matches replace the contents of \a sc_list. 174 /// 175 /// @param[out] sc_list 176 /// A symbol context list that gets filled in with all of the 177 /// matches. 178 /// 179 /// @return 180 /// The number of matches added to \a sc_list. 181 //------------------------------------------------------------------ 182 uint32_t 183 FindFunctions (const ConstString &name, 184 uint32_t name_type_mask, 185 bool symbols_ok, 186 bool append, 187 SymbolContextList& sc_list); 188 189 //------------------------------------------------------------------ 190 /// Find functions by name. 191 /// 192 /// @param[in] regex 193 /// A regular expression to use when matching the name. 194 /// 195 /// @param[in] append 196 /// If \b true, any matches will be appended to \a sc_list, else 197 /// matches replace the contents of \a sc_list. 198 /// 199 /// @param[out] sc_list 200 /// A symbol context list that gets filled in with all of the 201 /// matches. 202 /// 203 /// @return 204 /// The number of matches added to \a sc_list. 205 //------------------------------------------------------------------ 206 uint32_t 207 FindFunctions (const RegularExpression& regex, 208 bool symbols_ok, 209 bool append, 210 SymbolContextList& sc_list); 211 212 //------------------------------------------------------------------ 213 /// Find global and static variables by name. 214 /// 215 /// @param[in] name 216 /// The name of the global or static variable we are looking 217 /// for. 218 /// 219 /// @param[in] append 220 /// If \b true, any matches will be appended to \a 221 /// variable_list, else matches replace the contents of 222 /// \a variable_list. 223 /// 224 /// @param[in] max_matches 225 /// Allow the number of matches to be limited to \a 226 /// max_matches. Specify UINT32_MAX to get all possible matches. 227 /// 228 /// @param[in] variable_list 229 /// A list of variables that gets the matches appended to (if 230 /// \a append it \b true), or replace (if \a append is \b false). 231 /// 232 /// @return 233 /// The number of matches added to \a variable_list. 234 //------------------------------------------------------------------ 235 uint32_t 236 FindGlobalVariables (const ConstString &name, 237 bool append, 238 uint32_t max_matches, 239 VariableList& variable_list); 240 241 //------------------------------------------------------------------ 242 /// Find global and static variables by regular exression. 243 /// 244 /// @param[in] regex 245 /// A regular expression to use when matching the name. 246 /// 247 /// @param[in] append 248 /// If \b true, any matches will be appended to \a 249 /// variable_list, else matches replace the contents of 250 /// \a variable_list. 251 /// 252 /// @param[in] max_matches 253 /// Allow the number of matches to be limited to \a 254 /// max_matches. Specify UINT32_MAX to get all possible matches. 255 /// 256 /// @param[in] variable_list 257 /// A list of variables that gets the matches appended to (if 258 /// \a append it \b true), or replace (if \a append is \b false). 259 /// 260 /// @return 261 /// The number of matches added to \a variable_list. 262 //------------------------------------------------------------------ 263 uint32_t 264 FindGlobalVariables (const RegularExpression& regex, 265 bool append, 266 uint32_t max_matches, 267 VariableList& variable_list); 268 269 //------------------------------------------------------------------ 270 /// Find types by name. 271 /// 272 /// @param[in] sc 273 /// A symbol context that scopes where to extract a type list 274 /// from. 275 /// 276 /// @param[in] name 277 /// The name of the type we are looking for. 278 /// 279 /// @param[in] append 280 /// If \b true, any matches will be appended to \a 281 /// variable_list, else matches replace the contents of 282 /// \a variable_list. 283 /// 284 /// @param[in] max_matches 285 /// Allow the number of matches to be limited to \a 286 /// max_matches. Specify UINT32_MAX to get all possible matches. 287 /// 288 /// @param[in] encoding 289 /// Limit the search to specific types, or get all types if 290 /// set to Type::invalid. 291 /// 292 /// @param[in] udt_name 293 /// If the encoding is a user defined type, specify the name 294 /// of the user defined type ("struct", "union", "class", etc). 295 /// 296 /// @param[out] type_list 297 /// A type list gets populated with any matches. 298 /// 299 /// @return 300 /// The number of matches added to \a type_list. 301 //------------------------------------------------------------------ 302 uint32_t 303 FindTypes (const SymbolContext& sc, 304 const ConstString &name, 305 bool append, 306 uint32_t max_matches, 307 TypeList& types); 308 309 //------------------------------------------------------------------ 310 /// Get const accessor for the module architecture. 311 /// 312 /// @return 313 /// A const reference to the architecture object. 314 //------------------------------------------------------------------ 315 const ArchSpec& 316 GetArchitecture () const; 317 318 //------------------------------------------------------------------ 319 /// Get const accessor for the module file specification. 320 /// 321 /// This function returns the file for the module on the host system 322 /// that is running LLDB. This can differ from the path on the 323 /// platform since we might be doing remote debugging. 324 /// 325 /// @return 326 /// A const reference to the file specification object. 327 //------------------------------------------------------------------ 328 const FileSpec & 329 GetFileSpec () const 330 { 331 return m_file; 332 } 333 334 //------------------------------------------------------------------ 335 /// Get accessor for the module platform file specification. 336 /// 337 /// Platform file refers to the path of the module as it is known on 338 /// the remote system on which it is being debugged. For local 339 /// debugging this is always the same as Module::GetFileSpec(). But 340 /// remote debugging might mention a file "/usr/lib/liba.dylib" 341 /// which might be locally downloaded and cached. In this case the 342 /// platform file could be something like: 343 /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" 344 /// The file could also be cached in a local developer kit directory. 345 /// 346 /// @return 347 /// A const reference to the file specification object. 348 //------------------------------------------------------------------ 349 const FileSpec & 350 GetPlatformFileSpec () const 351 { 352 if (m_platform_file) 353 return m_platform_file; 354 return m_file; 355 } 356 357 void 358 SetPlatformFileSpec (const FileSpec &file) 359 { 360 m_platform_file = file; 361 } 362 363 const TimeValue & 364 GetModificationTime () const; 365 366 //------------------------------------------------------------------ 367 /// Tells whether this module is capable of being the main executable 368 /// for a process. 369 /// 370 /// @return 371 /// \b true if it is, \b false otherwise. 372 //------------------------------------------------------------------ 373 bool 374 IsExecutable (); 375 376 //------------------------------------------------------------------ 377 /// Get the number of compile units for this module. 378 /// 379 /// @return 380 /// The number of compile units that the symbol vendor plug-in 381 /// finds. 382 //------------------------------------------------------------------ 383 uint32_t 384 GetNumCompileUnits(); 385 386 lldb::CompUnitSP 387 GetCompileUnitAtIndex (uint32_t); 388 389 const ConstString & 390 GetObjectName() const; 391 392 uint64_t 393 GetObjectOffset() const 394 { 395 return m_object_offset; 396 } 397 398 //------------------------------------------------------------------ 399 /// Get the object file representation for the current architecture. 400 /// 401 /// If the object file has not been located or parsed yet, this 402 /// function will find the best ObjectFile plug-in that can parse 403 /// Module::m_file. 404 /// 405 /// @return 406 /// If Module::m_file does not exist, or no plug-in was found 407 /// that can parse the file, or the object file doesn't contain 408 /// the current architecture in Module::m_arch, NULL will be 409 /// returned, else a valid object file interface will be 410 /// returned. The returned pointer is owned by this object and 411 /// remains valid as long as the object is around. 412 //------------------------------------------------------------------ 413 ObjectFile * 414 GetObjectFile (); 415 416 //------------------------------------------------------------------ 417 /// Get the symbol vendor interface for the current architecture. 418 /// 419 /// If the symbol vendor file has not been located yet, this 420 /// function will find the best SymbolVendor plug-in that can 421 /// use the current object file. 422 /// 423 /// @return 424 /// If this module does not have a valid object file, or no 425 /// plug-in can be found that can use the object file, NULL will 426 /// be returned, else a valid symbol vendor plug-in interface 427 /// will be returned. The returned pointer is owned by this 428 /// object and remains valid as long as the object is around. 429 //------------------------------------------------------------------ 430 SymbolVendor* 431 GetSymbolVendor(bool can_create = true); 432 433 //------------------------------------------------------------------ 434 /// Get accessor the type list for this module. 435 /// 436 /// @return 437 /// A valid type list pointer, or NULL if there is no valid 438 /// symbol vendor for this module. 439 //------------------------------------------------------------------ 440 TypeList* 441 GetTypeList (); 442 443 //------------------------------------------------------------------ 444 /// Get a pointer to the UUID value contained in this object. 445 /// 446 /// If the executable image file doesn't not have a UUID value built 447 /// into the file format, an MD5 checksum of the entire file, or 448 /// slice of the file for the current architecture should be used. 449 /// 450 /// @return 451 /// A const pointer to the internal copy of the UUID value in 452 /// this module if this module has a valid UUID value, NULL 453 /// otherwise. 454 //------------------------------------------------------------------ 455 const lldb_private::UUID & 456 GetUUID (); 457 458 //------------------------------------------------------------------ 459 /// A debugging function that will cause everything in a module to 460 /// be parsed. 461 /// 462 /// All compile units will be pasred, along with all globals and 463 /// static variables and all functions for those compile units. 464 /// All types, scopes, local variables, static variables, global 465 /// variables, and line tables will be parsed. This can be used 466 /// prior to dumping a module to see a complete list of the 467 /// resuling debug information that gets parsed, or as a debug 468 /// function to ensure that the module can consume all of the 469 /// debug data the symbol vendor provides. 470 //------------------------------------------------------------------ 471 void 472 ParseAllDebugSymbols(); 473 474 bool 475 ResolveFileAddress (lldb::addr_t vm_addr, Address& so_addr); 476 477 uint32_t 478 ResolveSymbolContextForAddress (const Address& so_addr, uint32_t resolve_scope, SymbolContext& sc); 479 480 //------------------------------------------------------------------ 481 /// Resolve items in the symbol context for a given file and line. 482 /// 483 /// Tries to resolve \a file_path and \a line to a list of matching 484 /// symbol contexts. 485 /// 486 /// The line table entries contains addresses that can be used to 487 /// further resolve the values in each match: the function, block, 488 /// symbol. Care should be taken to minimize the amount of 489 /// information that is requested to only what is needed -- 490 /// typically the module, compile unit, line table and line table 491 /// entry are sufficient. 492 /// 493 /// @param[in] file_path 494 /// A path to a source file to match. If \a file_path does not 495 /// specify a directory, then this query will match all files 496 /// whose base filename matches. If \a file_path does specify 497 /// a directory, the fullpath to the file must match. 498 /// 499 /// @param[in] line 500 /// The source line to match, or zero if just the compile unit 501 /// should be resolved. 502 /// 503 /// @param[in] check_inlines 504 /// Check for inline file and line number matches. This option 505 /// should be used sparingly as it will cause all line tables 506 /// for every compile unit to be parsed and searched for 507 /// matching inline file entries. 508 /// 509 /// @param[in] resolve_scope 510 /// The scope that should be resolved (see 511 /// SymbolContext::Scope). 512 /// 513 /// @param[out] sc_list 514 /// A symbol context list that gets matching symbols contexts 515 /// appended to. 516 /// 517 /// @return 518 /// The number of matches that were added to \a sc_list. 519 /// 520 /// @see SymbolContext::Scope 521 //------------------------------------------------------------------ 522 uint32_t 523 ResolveSymbolContextForFilePath (const char *file_path, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list); 524 525 //------------------------------------------------------------------ 526 /// Resolve items in the symbol context for a given file and line. 527 /// 528 /// Tries to resolve \a file_spec and \a line to a list of matching 529 /// symbol contexts. 530 /// 531 /// The line table entries contains addresses that can be used to 532 /// further resolve the values in each match: the function, block, 533 /// symbol. Care should be taken to minimize the amount of 534 /// information that is requested to only what is needed -- 535 /// typically the module, compile unit, line table and line table 536 /// entry are sufficient. 537 /// 538 /// @param[in] file_spec 539 /// A file spec to a source file to match. If \a file_path does 540 /// not specify a directory, then this query will match all 541 /// files whose base filename matches. If \a file_path does 542 /// specify a directory, the fullpath to the file must match. 543 /// 544 /// @param[in] line 545 /// The source line to match, or zero if just the compile unit 546 /// should be resolved. 547 /// 548 /// @param[in] check_inlines 549 /// Check for inline file and line number matches. This option 550 /// should be used sparingly as it will cause all line tables 551 /// for every compile unit to be parsed and searched for 552 /// matching inline file entries. 553 /// 554 /// @param[in] resolve_scope 555 /// The scope that should be resolved (see 556 /// SymbolContext::Scope). 557 /// 558 /// @param[out] sc_list 559 /// A symbol context list that gets filled in with all of the 560 /// matches. 561 /// 562 /// @return 563 /// A integer that contains SymbolContext::Scope bits set for 564 /// each item that was successfully resolved. 565 /// 566 /// @see SymbolContext::Scope 567 //------------------------------------------------------------------ 568 uint32_t 569 ResolveSymbolContextsForFileSpec (const FileSpec &file_spec, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list); 570 571 572 void 573 SetFileSpecAndObjectName (const FileSpec &file, 574 const ConstString &object_name); 575 576 bool 577 GetIsDynamicLinkEditor () const 578 { 579 return m_is_dynamic_loader_module; 580 } 581 582 void 583 SetIsDynamicLinkEditor (bool b) 584 { 585 m_is_dynamic_loader_module = b; 586 } 587 588 ClangASTContext & 589 GetClangASTContext (); 590 591protected: 592 //------------------------------------------------------------------ 593 // Member Variables 594 //------------------------------------------------------------------ 595 mutable Mutex m_mutex; ///< A mutex to keep this object happy in multi-threaded environments. 596 TimeValue m_mod_time; ///< The modification time for this module when it was created. 597 ArchSpec m_arch; ///< The architecture for this module. 598 lldb_private::UUID m_uuid; ///< Each module is assumed to have a unique identifier to help match it up to debug symbols. 599 FileSpec m_file; ///< The file representation on disk for this module (if there is one). 600 FileSpec m_platform_file;///< The path to the module on the platform on which it is being debugged 601 ConstString m_object_name; ///< The name an object within this module that is selected, or empty of the module is represented by \a m_file. 602 uint64_t m_object_offset; 603 std::auto_ptr<ObjectFile> m_objfile_ap; ///< A pointer to the object file parser for this module. 604 std::auto_ptr<SymbolVendor> m_symfile_ap; ///< A pointer to the symbol vendor for this module. 605 ClangASTContext m_ast; ///< The AST context for this module. 606 bool m_did_load_objfile:1, 607 m_did_load_symbol_vendor:1, 608 m_did_parse_uuid:1, 609 m_did_init_ast:1, 610 m_is_dynamic_loader_module:1; 611 612 //------------------------------------------------------------------ 613 /// Resolve a file or load virtual address. 614 /// 615 /// Tries to resolve \a vm_addr as a file address (if \a 616 /// vm_addr_is_file_addr is true) or as a load address if \a 617 /// vm_addr_is_file_addr is false) in the symbol vendor. 618 /// \a resolve_scope indicates what clients wish to resolve 619 /// and can be used to limit the scope of what is parsed. 620 /// 621 /// @param[in] vm_addr 622 /// The load virtual address to resolve. 623 /// 624 /// @param[in] vm_addr_is_file_addr 625 /// If \b true, \a vm_addr is a file address, else \a vm_addr 626 /// if a load address. 627 /// 628 /// @param[in] resolve_scope 629 /// The scope that should be resolved (see 630 /// SymbolContext::Scope). 631 /// 632 /// @param[out] so_addr 633 /// The section offset based address that got resolved if 634 /// any bits are returned. 635 /// 636 /// @param[out] sc 637 // The symbol context that has objects filled in. Each bit 638 /// in the \a resolve_scope pertains to a member in the \a sc. 639 /// 640 /// @return 641 /// A integer that contains SymbolContext::Scope bits set for 642 /// each item that was successfully resolved. 643 /// 644 /// @see SymbolContext::Scope 645 //------------------------------------------------------------------ 646 uint32_t 647 ResolveSymbolContextForAddress (lldb::addr_t vm_addr, 648 bool vm_addr_is_file_addr, 649 uint32_t resolve_scope, 650 Address& so_addr, 651 SymbolContext& sc); 652 653 void 654 SymbolIndicesToSymbolContextList (Symtab *symtab, 655 std::vector<uint32_t> &symbol_indexes, 656 SymbolContextList &sc_list); 657 658 bool 659 SetArchitecture (const ArchSpec &new_arch); 660 661private: 662 DISALLOW_COPY_AND_ASSIGN (Module); 663}; 664 665} // namespace lldb_private 666 667#endif // liblldb_Module_h_ 668