Module.h revision 0467c78e9a75eff9ec33d3c1f39fa83e1c5d9241
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 (); 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 173 /// variable_list, else matches replace the contents of 174 /// \a variable_list. 175 /// 176 /// @param[out] sc_list 177 /// A symbol context list that gets filled in with all of the 178 /// matches. 179 /// 180 /// @return 181 /// The number of matches added to \a sc_list. 182 //------------------------------------------------------------------ 183 uint32_t 184 FindFunctions (const ConstString &name, 185 uint32_t name_type_mask, 186 bool symbols_ok, 187 bool append, 188 SymbolContextList& sc_list); 189 190 //------------------------------------------------------------------ 191 /// Find functions by name. 192 /// 193 /// @param[in] regex 194 /// A regular expression to use when matching the name. 195 /// 196 /// @param[in] append 197 /// If \b true, any matches will be appended to \a 198 /// variable_list, else matches replace the contents of 199 /// \a variable_list. 200 /// 201 /// @param[out] sc_list 202 /// A symbol context list that gets filled in with all of the 203 /// matches. 204 /// 205 /// @return 206 /// The number of matches added to \a sc_list. 207 //------------------------------------------------------------------ 208 uint32_t 209 FindFunctions (const RegularExpression& regex, 210 bool symbols_ok, 211 bool append, 212 SymbolContextList& sc_list); 213 214 //------------------------------------------------------------------ 215 /// Find global and static variables by name. 216 /// 217 /// @param[in] name 218 /// The name of the global or static variable we are looking 219 /// for. 220 /// 221 /// @param[in] append 222 /// If \b true, any matches will be appended to \a 223 /// variable_list, else matches replace the contents of 224 /// \a variable_list. 225 /// 226 /// @param[in] max_matches 227 /// Allow the number of matches to be limited to \a 228 /// max_matches. Specify UINT32_MAX to get all possible matches. 229 /// 230 /// @param[in] variable_list 231 /// A list of variables that gets the matches appended to (if 232 /// \a append it \b true), or replace (if \a append is \b false). 233 /// 234 /// @return 235 /// The number of matches added to \a variable_list. 236 //------------------------------------------------------------------ 237 uint32_t 238 FindGlobalVariables (const ConstString &name, 239 bool append, 240 uint32_t max_matches, 241 VariableList& variable_list); 242 243 //------------------------------------------------------------------ 244 /// Find global and static variables by regular exression. 245 /// 246 /// @param[in] regex 247 /// A regular expression to use when matching the name. 248 /// 249 /// @param[in] append 250 /// If \b true, any matches will be appended to \a 251 /// variable_list, else matches replace the contents of 252 /// \a variable_list. 253 /// 254 /// @param[in] max_matches 255 /// Allow the number of matches to be limited to \a 256 /// max_matches. Specify UINT32_MAX to get all possible matches. 257 /// 258 /// @param[in] variable_list 259 /// A list of variables that gets the matches appended to (if 260 /// \a append it \b true), or replace (if \a append is \b false). 261 /// 262 /// @return 263 /// The number of matches added to \a variable_list. 264 //------------------------------------------------------------------ 265 uint32_t 266 FindGlobalVariables (const RegularExpression& regex, 267 bool append, 268 uint32_t max_matches, 269 VariableList& variable_list); 270 271 //------------------------------------------------------------------ 272 /// Find types by name. 273 /// 274 /// @param[in] sc 275 /// A symbol context that scopes where to extract a type list 276 /// from. 277 /// 278 /// @param[in] name 279 /// The name of the type we are looking for. 280 /// 281 /// @param[in] append 282 /// If \b true, any matches will be appended to \a 283 /// variable_list, else matches replace the contents of 284 /// \a variable_list. 285 /// 286 /// @param[in] max_matches 287 /// Allow the number of matches to be limited to \a 288 /// max_matches. Specify UINT32_MAX to get all possible matches. 289 /// 290 /// @param[in] encoding 291 /// Limit the search to specific types, or get all types if 292 /// set to Type::invalid. 293 /// 294 /// @param[in] udt_name 295 /// If the encoding is a user defined type, specify the name 296 /// of the user defined type ("struct", "union", "class", etc). 297 /// 298 /// @param[out] type_list 299 /// A type list gets populated with any matches. 300 /// 301 /// @return 302 /// The number of matches added to \a type_list. 303 //------------------------------------------------------------------ 304 uint32_t 305 FindTypes (const SymbolContext& sc, 306 const ConstString &name, 307 bool append, 308 uint32_t max_matches, 309 TypeList& types); 310 311 //------------------------------------------------------------------ 312 /// Get const accessor for the module architecture. 313 /// 314 /// @return 315 /// A const reference to the architecture object. 316 //------------------------------------------------------------------ 317 const ArchSpec& 318 GetArchitecture () const; 319 320 //------------------------------------------------------------------ 321 /// Get const accessor for the module file specification. 322 /// 323 /// @return 324 /// A const reference to the file specification object. 325 //------------------------------------------------------------------ 326 const FileSpec & 327 GetFileSpec () const; 328 329 330 const TimeValue & 331 GetModificationTime () const; 332 333 //------------------------------------------------------------------ 334 /// Tells whether this module is capable of being the main executable 335 /// for a process. 336 /// 337 /// @return 338 /// \b true if it is, \b false otherwise. 339 //------------------------------------------------------------------ 340 bool 341 IsExecutable (); 342 343 //------------------------------------------------------------------ 344 /// Get the number of compile units for this module. 345 /// 346 /// @return 347 /// The number of compile units that the symbol vendor plug-in 348 /// finds. 349 //------------------------------------------------------------------ 350 uint32_t 351 GetNumCompileUnits(); 352 353 lldb::CompUnitSP 354 GetCompileUnitAtIndex (uint32_t); 355 356 const ConstString & 357 GetObjectName() const; 358 359 off_t 360 GetObjectOffset() const; 361 362 //------------------------------------------------------------------ 363 /// Get the object file representation for the current architecture. 364 /// 365 /// If the object file has not been located or parsed yet, this 366 /// function will find the best ObjectFile plug-in that can parse 367 /// Module::m_file. 368 /// 369 /// @return 370 /// If Module::m_file does not exist, or no plug-in was found 371 /// that can parse the file, or the object file doesn't contain 372 /// the current architecture in Module::m_arch, NULL will be 373 /// returned, else a valid object file interface will be 374 /// returned. The returned pointer is owned by this object and 375 /// remains valid as long as the object is around. 376 //------------------------------------------------------------------ 377 ObjectFile * 378 GetObjectFile (); 379 380 //------------------------------------------------------------------ 381 /// Get the symbol vendor interface for the current architecture. 382 /// 383 /// If the symbol vendor file has not been located yet, this 384 /// function will find the best SymbolVendor plug-in that can 385 /// use the current object file. 386 /// 387 /// @return 388 /// If this module does not have a valid object file, or no 389 /// plug-in can be found that can use the object file, NULL will 390 /// be returned, else a valid symbol vendor plug-in interface 391 /// will be returned. The returned pointer is owned by this 392 /// object and remains valid as long as the object is around. 393 //------------------------------------------------------------------ 394 SymbolVendor* 395 GetSymbolVendor(bool can_create = true); 396 397 //------------------------------------------------------------------ 398 /// Get accessor the type list for this module. 399 /// 400 /// @return 401 /// A valid type list pointer, or NULL if there is no valid 402 /// symbol vendor for this module. 403 //------------------------------------------------------------------ 404 TypeList* 405 GetTypeList (); 406 407 //------------------------------------------------------------------ 408 /// Get a pointer to the UUID value contained in this object. 409 /// 410 /// If the executable image file doesn't not have a UUID value built 411 /// into the file format, an MD5 checksum of the entire file, or 412 /// slice of the file for the current architecture should be used. 413 /// 414 /// @return 415 /// A const pointer to the internal copy of the UUID value in 416 /// this module if this module has a valid UUID value, NULL 417 /// otherwise. 418 //------------------------------------------------------------------ 419 const lldb_private::UUID & 420 GetUUID (); 421 422 //------------------------------------------------------------------ 423 /// A debugging function that will cause everything in a module to 424 /// be parsed. 425 /// 426 /// All compile units will be pasred, along with all globals and 427 /// static variables and all functions for those compile units. 428 /// All types, scopes, local variables, static variables, global 429 /// variables, and line tables will be parsed. This can be used 430 /// prior to dumping a module to see a complete list of the 431 /// resuling debug information that gets parsed, or as a debug 432 /// function to ensure that the module can consume all of the 433 /// debug data the symbol vendor provides. 434 //------------------------------------------------------------------ 435 void 436 ParseAllDebugSymbols(); 437 438 bool 439 ResolveFileAddress (lldb::addr_t vm_addr, Address& so_addr); 440 441 uint32_t 442 ResolveSymbolContextForAddress (const Address& so_addr, uint32_t resolve_scope, SymbolContext& sc); 443 444 //------------------------------------------------------------------ 445 /// Resolve items in the symbol context for a given file and line. 446 /// 447 /// Tries to resolve \a file_path and \a line to a list of matching 448 /// symbol contexts. 449 /// 450 /// The line table entries contains addresses that can be used to 451 /// further resolve the values in each match: the function, block, 452 /// symbol. Care should be taken to minimize the amount of 453 /// information that is requested to only what is needed -- 454 /// typically the module, compile unit, line table and line table 455 /// entry are sufficient. 456 /// 457 /// @param[in] file_path 458 /// A path to a source file to match. If \a file_path does not 459 /// specify a directory, then this query will match all files 460 /// whose base filename matches. If \a file_path does specify 461 /// a directory, the fullpath to the file must match. 462 /// 463 /// @param[in] line 464 /// The source line to match, or zero if just the compile unit 465 /// should be resolved. 466 /// 467 /// @param[in] check_inlines 468 /// Check for inline file and line number matches. This option 469 /// should be used sparingly as it will cause all line tables 470 /// for every compile unit to be parsed and searched for 471 /// matching inline file entries. 472 /// 473 /// @param[in] resolve_scope 474 /// The scope that should be resolved (see 475 /// SymbolContext::Scope). 476 /// 477 /// @param[out] sc_list 478 /// A symbol context list that gets matching symbols contexts 479 /// appended to. 480 /// 481 /// @return 482 /// The number of matches that were added to \a sc_list. 483 /// 484 /// @see SymbolContext::Scope 485 //------------------------------------------------------------------ 486 uint32_t 487 ResolveSymbolContextForFilePath (const char *file_path, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list); 488 489 //------------------------------------------------------------------ 490 /// Resolve items in the symbol context for a given file and line. 491 /// 492 /// Tries to resolve \a file_spec and \a line to a list of matching 493 /// symbol contexts. 494 /// 495 /// The line table entries contains addresses that can be used to 496 /// further resolve the values in each match: the function, block, 497 /// symbol. Care should be taken to minimize the amount of 498 /// information that is requested to only what is needed -- 499 /// typically the module, compile unit, line table and line table 500 /// entry are sufficient. 501 /// 502 /// @param[in] file_spec 503 /// A file spec to a source file to match. If \a file_path does 504 /// not specify a directory, then this query will match all 505 /// files whose base filename matches. If \a file_path does 506 /// specify a directory, the fullpath to the file must match. 507 /// 508 /// @param[in] line 509 /// The source line to match, or zero if just the compile unit 510 /// should be resolved. 511 /// 512 /// @param[in] check_inlines 513 /// Check for inline file and line number matches. This option 514 /// should be used sparingly as it will cause all line tables 515 /// for every compile unit to be parsed and searched for 516 /// matching inline file entries. 517 /// 518 /// @param[in] resolve_scope 519 /// The scope that should be resolved (see 520 /// SymbolContext::Scope). 521 /// 522 /// @param[out] sc_list 523 /// A symbol context list that gets filled in with all of the 524 /// matches. 525 /// 526 /// @return 527 /// A integer that contains SymbolContext::Scope bits set for 528 /// each item that was successfully resolved. 529 /// 530 /// @see SymbolContext::Scope 531 //------------------------------------------------------------------ 532 uint32_t 533 ResolveSymbolContextsForFileSpec (const FileSpec &file_spec, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list); 534 535 536 void 537 SetFileSpecAndObjectName (const FileSpec &file, 538 const ConstString &object_name); 539 540 bool 541 GetIsDynamicLinkEditor () const 542 { 543 return m_is_dynamic_loader_module; 544 } 545 546 void 547 SetIsDynamicLinkEditor (bool b) 548 { 549 m_is_dynamic_loader_module = b; 550 } 551 552 ClangASTContext & 553 GetClangASTContext (); 554 555protected: 556 //------------------------------------------------------------------ 557 // Member Variables 558 //------------------------------------------------------------------ 559 mutable Mutex m_mutex; ///< A mutex to keep this object happy in multi-threaded environments. 560 TimeValue m_mod_time; ///< The modification time for this module when it was created. 561 ArchSpec m_arch; ///< The architecture for this module. 562 lldb_private::UUID m_uuid; ///< Each module is assumed to have a unique identifier to help match it up to debug symbols. 563 FileSpec m_file; ///< The file representation on disk for this module (if there is one). 564 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. 565 std::auto_ptr<ObjectFile> m_objfile_ap; ///< A pointer to the object file parser for this module. 566 std::auto_ptr<SymbolVendor> m_symfile_ap; ///< A pointer to the symbol vendor for this module. 567 ClangASTContext m_ast; ///< The AST context for this module. 568 bool m_did_load_objfile:1, 569 m_did_load_symbol_vendor:1, 570 m_did_parse_uuid:1, 571 m_did_init_ast:1, 572 m_is_dynamic_loader_module:1; 573 574 //------------------------------------------------------------------ 575 /// Resolve a file or load virtual address. 576 /// 577 /// Tries to resolve \a vm_addr as a file address (if \a 578 /// vm_addr_is_file_addr is true) or as a load address if \a 579 /// vm_addr_is_file_addr is false) in the symbol vendor. 580 /// \a resolve_scope indicates what clients wish to resolve 581 /// and can be used to limit the scope of what is parsed. 582 /// 583 /// @param[in] vm_addr 584 /// The load virtual address to resolve. 585 /// 586 /// @param[in] vm_addr_is_file_addr 587 /// If \b true, \a vm_addr is a file address, else \a vm_addr 588 /// if a load address. 589 /// 590 /// @param[in] resolve_scope 591 /// The scope that should be resolved (see 592 /// SymbolContext::Scope). 593 /// 594 /// @param[out] so_addr 595 /// The section offset based address that got resolved if 596 /// any bits are returned. 597 /// 598 /// @param[out] sc 599 // The symbol context that has objects filled in. Each bit 600 /// in the \a resolve_scope pertains to a member in the \a sc. 601 /// 602 /// @return 603 /// A integer that contains SymbolContext::Scope bits set for 604 /// each item that was successfully resolved. 605 /// 606 /// @see SymbolContext::Scope 607 //------------------------------------------------------------------ 608 uint32_t 609 ResolveSymbolContextForAddress (lldb::addr_t vm_addr, 610 bool vm_addr_is_file_addr, 611 uint32_t resolve_scope, 612 Address& so_addr, 613 SymbolContext& sc); 614 615 void 616 SymbolIndicesToSymbolContextList (Symtab *symtab, 617 std::vector<uint32_t> &symbol_indexes, 618 SymbolContextList &sc_list); 619 620 bool 621 SetArchitecture (const ArchSpec &new_arch); 622 623private: 624 DISALLOW_COPY_AND_ASSIGN (Module); 625}; 626 627} // namespace lldb_private 628 629#endif // liblldb_Module_h_ 630