ObjectFile.h revision 7940069905bee0b2e5f0661bf37c9f906ddf8603
1//===-- ObjectFile.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_ObjectFile_h_ 11#define liblldb_ObjectFile_h_ 12 13#include "lldb/lldb-private.h" 14#include "lldb/Core/DataExtractor.h" 15#include "lldb/Host/FileSpec.h" 16#include "lldb/Core/FileSpecList.h" 17#include "lldb/Core/ModuleChild.h" 18#include "lldb/Core/PluginInterface.h" 19#include "lldb/Host/Endian.h" 20#include "lldb/Symbol/Symtab.h" 21#include "lldb/Symbol/UnwindTable.h" 22 23namespace lldb_private { 24 25//---------------------------------------------------------------------- 26/// @class ObjectFile ObjectFile.h "lldb/Symbol/ObjectFile.h" 27/// @brief A plug-in interface definition class for object file parsers. 28/// 29/// Object files belong to Module objects and know how to extract 30/// information from executable, shared library, and object (.o) files 31/// used by operating system runtime. The symbol table and section list 32/// for an object file. 33/// 34/// Object files can be represented by the entire file, or by part of a 35/// file. Examples of object files that are part of a file include 36/// object files that contain information for multiple architectures in 37/// the same file, or archive files that contain multiple objects 38/// (ranlib archives) (possibly for multiple architectures as well). 39/// 40/// Object archive files (e.g. ranlib archives) can contain 41/// multiple .o (object) files that must be selected by index or by name. 42/// The number of objects that an ObjectFile contains can be determined 43/// using the ObjectFile::GetNumObjects() const 44/// function, and followed by a call to 45/// ObjectFile::SelectObjectAtIndex (uint32_t) to change the currently 46/// selected object. Objects can also be selected by name using the 47/// ObjectFile::SelectObject(const char *) function. 48/// 49/// Once an architecture is selected (and an object is selected for 50/// for archives), the object file information can be extracted from 51/// this abstract class. 52//---------------------------------------------------------------------- 53class ObjectFile: 54 public std::enable_shared_from_this<ObjectFile>, 55 public PluginInterface, 56 public ModuleChild 57{ 58friend class lldb_private::Module; 59 60public: 61 typedef enum 62 { 63 eTypeInvalid = 0, 64 eTypeCoreFile, /// A core file that has a checkpoint of a program's execution state 65 eTypeExecutable, /// A normal executable 66 eTypeDebugInfo, /// An object file that contains only debug information 67 eTypeDynamicLinker, /// The platform's dynamic linker executable 68 eTypeObjectFile, /// An intermediate object file 69 eTypeSharedLibrary, /// A shared library that can be used during execution 70 eTypeStubLibrary, /// A library that can be linked against but not used for execution 71 eTypeUnknown 72 } Type; 73 74 typedef enum 75 { 76 eStrataInvalid = 0, 77 eStrataUnknown, 78 eStrataUser, 79 eStrataKernel, 80 eStrataRawImage 81 } Strata; 82 83 //------------------------------------------------------------------ 84 /// Construct with a parent module, offset, and header data. 85 /// 86 /// Object files belong to modules and a valid module must be 87 /// supplied upon construction. The at an offset within a file for 88 /// objects that contain more than one architecture or object. 89 //------------------------------------------------------------------ 90 ObjectFile (const lldb::ModuleSP &module_sp, 91 const FileSpec *file_spec_ptr, 92 lldb::offset_t file_offset, 93 lldb::offset_t length, 94 lldb::DataBufferSP& data_sp, 95 lldb::offset_t data_offset); 96 97 ObjectFile (const lldb::ModuleSP &module_sp, 98 const lldb::ProcessSP &process_sp, 99 lldb::addr_t header_addr, 100 lldb::DataBufferSP& data_sp); 101 102 //------------------------------------------------------------------ 103 /// Destructor. 104 /// 105 /// The destructor is virtual since this class is designed to be 106 /// inherited from by the plug-in instance. 107 //------------------------------------------------------------------ 108 virtual 109 ~ObjectFile(); 110 111 //------------------------------------------------------------------ 112 /// Dump a description of this object to a Stream. 113 /// 114 /// Dump a description of the current contents of this object 115 /// to the supplied stream \a s. The dumping should include the 116 /// section list if it has been parsed, and the symbol table 117 /// if it has been parsed. 118 /// 119 /// @param[in] s 120 /// The stream to which to dump the object descripton. 121 //------------------------------------------------------------------ 122 virtual void 123 Dump (Stream *s) = 0; 124 125 //------------------------------------------------------------------ 126 /// Find a ObjectFile plug-in that can parse \a file_spec. 127 /// 128 /// Scans all loaded plug-in interfaces that implement versions of 129 /// the ObjectFile plug-in interface and returns the first 130 /// instance that can parse the file. 131 /// 132 /// @param[in] module 133 /// The parent module that owns this object file. 134 /// 135 /// @param[in] file_spec 136 /// A file specification that indicates which file to use as the 137 /// object file. 138 /// 139 /// @param[in] file_offset 140 /// The offset into the file at which to start parsing the 141 /// object. This is for files that contain multiple 142 /// architectures or objects. 143 /// 144 /// @param[in] file_size 145 /// The size of the current object file if it can be determined 146 /// or if it is known. This can be zero. 147 /// 148 /// @see ObjectFile::ParseHeader() 149 //------------------------------------------------------------------ 150 static lldb::ObjectFileSP 151 FindPlugin (const lldb::ModuleSP &module_sp, 152 const FileSpec* file_spec, 153 lldb::offset_t file_offset, 154 lldb::offset_t file_size, 155 lldb::DataBufferSP &data_sp, 156 lldb::offset_t &data_offset); 157 158 //------------------------------------------------------------------ 159 /// Find a ObjectFile plug-in that can parse a file in memory. 160 /// 161 /// Scans all loaded plug-in interfaces that implement versions of 162 /// the ObjectFile plug-in interface and returns the first 163 /// instance that can parse the file. 164 /// 165 /// @param[in] module 166 /// The parent module that owns this object file. 167 /// 168 /// @param[in] process_sp 169 /// A shared pointer to the process whose memory space contains 170 /// an object file. This will be stored as a std::weak_ptr. 171 /// 172 /// @param[in] header_addr 173 /// The address of the header for the object file in memory. 174 //------------------------------------------------------------------ 175 static lldb::ObjectFileSP 176 FindPlugin (const lldb::ModuleSP &module_sp, 177 const lldb::ProcessSP &process_sp, 178 lldb::addr_t header_addr, 179 lldb::DataBufferSP &file_data_sp); 180 181 182 static size_t 183 GetModuleSpecifications (const FileSpec &file, 184 lldb::offset_t file_offset, 185 ModuleSpecList &specs); 186 187 static size_t 188 GetModuleSpecifications (const lldb_private::FileSpec& file, 189 lldb::DataBufferSP& data_sp, 190 lldb::offset_t data_offset, 191 lldb::offset_t file_offset, 192 lldb::offset_t length, 193 lldb_private::ModuleSpecList &specs); 194 //------------------------------------------------------------------ 195 /// Split a path into a file path with object name. 196 /// 197 /// For paths like "/tmp/foo.a(bar.o)" we often need to split a path 198 /// up into the actual path name and into the object name so we can 199 /// make a valid object file from it. 200 /// 201 /// @param[in] path_with_object 202 /// A path that might contain an archive path with a .o file 203 /// specified in parens in the basename of the path. 204 /// 205 /// @param[out] archive_file 206 /// If \b true is returned, \a file_spec will be filled in with 207 /// the path to the archive. 208 /// 209 /// @param[out] archive_object 210 /// If \b true is returned, \a object will be filled in with 211 /// the name of the object inside the archive. 212 /// 213 /// @return 214 /// \b true if the path matches the pattern of archive + object 215 /// and \a archive_file and \a archive_object are modified, 216 /// \b false otherwise and \a archive_file and \a archive_object 217 /// are guaranteed to be remain unchanged. 218 //------------------------------------------------------------------ 219 static bool 220 SplitArchivePathWithObject (const char *path_with_object, 221 lldb_private::FileSpec &archive_file, 222 lldb_private::ConstString &archive_object, 223 bool must_exist); 224 225 //------------------------------------------------------------------ 226 /// Gets the address size in bytes for the current object file. 227 /// 228 /// @return 229 /// The size of an address in bytes for the currently selected 230 /// architecture (and object for archives). Returns zero if no 231 /// architecture or object has been selected. 232 //------------------------------------------------------------------ 233 virtual uint32_t 234 GetAddressByteSize () const = 0; 235 236 //------------------------------------------------------------------ 237 /// Get the address type given a file address in an object file. 238 /// 239 /// Many binary file formats know what kinds 240 /// This is primarily for ARM binaries, though it can be applied to 241 /// any executable file format that supports different opcode types 242 /// within the same binary. ARM binaries support having both ARM and 243 /// Thumb within the same executable container. We need to be able 244 /// to get 245 /// @return 246 /// The size of an address in bytes for the currently selected 247 /// architecture (and object for archives). Returns zero if no 248 /// architecture or object has been selected. 249 //------------------------------------------------------------------ 250 virtual lldb::AddressClass 251 GetAddressClass (lldb::addr_t file_addr); 252 253 //------------------------------------------------------------------ 254 /// Extract the dependent modules from an object file. 255 /// 256 /// If an object file has information about which other images it 257 /// depends on (such as shared libraries), this function will 258 /// provide the list. Since many executables or shared libraries 259 /// may depend on the same files, 260 /// FileSpecList::AppendIfUnique(const FileSpec &) should be 261 /// used to make sure any files that are added are not already in 262 /// the list. 263 /// 264 /// @param[out] file_list 265 /// A list of file specification objects that gets dependent 266 /// files appended to. 267 /// 268 /// @return 269 /// The number of new files that were appended to \a file_list. 270 /// 271 /// @see FileSpecList::AppendIfUnique(const FileSpec &) 272 //------------------------------------------------------------------ 273 virtual uint32_t 274 GetDependentModules (FileSpecList& file_list) = 0; 275 276 //------------------------------------------------------------------ 277 /// Tells whether this object file is capable of being the main executable 278 /// for a process. 279 /// 280 /// @return 281 /// \b true if it is, \b false otherwise. 282 //------------------------------------------------------------------ 283 virtual bool 284 IsExecutable () const = 0; 285 286 //------------------------------------------------------------------ 287 /// Returns the offset into a file at which this object resides. 288 /// 289 /// Some files contain many object files, and this function allows 290 /// access to an object's offset within the file. 291 /// 292 /// @return 293 /// The offset in bytes into the file. Defaults to zero for 294 /// simple object files that a represented by an entire file. 295 //------------------------------------------------------------------ 296 virtual lldb::addr_t 297 GetFileOffset () const 298 { return m_file_offset; } 299 300 virtual lldb::addr_t 301 GetByteSize () const 302 { return m_length; } 303 304 //------------------------------------------------------------------ 305 /// Get accessor to the object file specification. 306 /// 307 /// @return 308 /// The file specification object pointer if there is one, or 309 /// NULL if this object is only from memory. 310 //------------------------------------------------------------------ 311 virtual FileSpec& 312 GetFileSpec() { return m_file; } 313 314 //------------------------------------------------------------------ 315 /// Get const accessor to the object file specification. 316 /// 317 /// @return 318 /// The const file specification object pointer if there is one, 319 /// or NULL if this object is only from memory. 320 //------------------------------------------------------------------ 321 virtual const FileSpec& 322 GetFileSpec() const { return m_file; } 323 324 //------------------------------------------------------------------ 325 /// Get the name of the cpu, vendor and OS for this object file. 326 /// 327 /// This value is a string that represents the target triple where 328 /// the cpu type, the vendor and the OS are encoded into a string. 329 /// 330 /// @param[out] target_triple 331 /// The string value of the target triple. 332 /// 333 /// @return 334 /// \b True if the target triple was able to be computed, \b 335 /// false otherwise. 336 //------------------------------------------------------------------ 337 virtual bool 338 GetArchitecture (ArchSpec &arch) = 0; 339 340 //------------------------------------------------------------------ 341 /// Gets the section list for the currently selected architecture 342 /// (and object for archives). 343 /// 344 /// Section list parsing can be deferred by ObjectFile instances 345 /// until this accessor is called the first time. 346 /// 347 /// @return 348 /// The list of sections contained in this object file. 349 //------------------------------------------------------------------ 350 virtual SectionList * 351 GetSectionList (); 352 353 virtual void 354 CreateSections (SectionList &unified_section_list) = 0; 355 356 //------------------------------------------------------------------ 357 /// Gets the symbol table for the currently selected architecture 358 /// (and object for archives). 359 /// 360 /// Symbol table parsing can be deferred by ObjectFile instances 361 /// until this accessor is called the first time. 362 /// 363 /// @return 364 /// The symbol table for this object file. 365 //------------------------------------------------------------------ 366 virtual Symtab * 367 GetSymtab () = 0; 368 369 //------------------------------------------------------------------ 370 /// Detect if this object file has been stripped of local symbols. 371 /// 372 /// @return 373 /// Return \b true if the object file has been stripped of local 374 /// symbols. 375 //------------------------------------------------------------------ 376 virtual bool 377 IsStripped () = 0; 378 379 //------------------------------------------------------------------ 380 /// Frees the symbol table. 381 /// 382 /// This function should only be used when an object file is 383 /// 384 /// @param[in] flags 385 /// eSymtabFromUnifiedSectionList: Whether to clear symbol table 386 /// for unified module section list, or object file. 387 /// 388 /// @return 389 /// The symbol table for this object file. 390 //------------------------------------------------------------------ 391 virtual void 392 ClearSymtab (); 393 394 //------------------------------------------------------------------ 395 /// Gets the UUID for this object file. 396 /// 397 /// If the object file format contains a UUID, the value should be 398 /// returned. Else ObjectFile instances should return the MD5 399 /// checksum of all of the bytes for the object file (or memory for 400 /// memory based object files). 401 /// 402 /// @return 403 /// Returns \b true if a UUID was successfully extracted into 404 /// \a uuid, \b false otherwise. 405 //------------------------------------------------------------------ 406 virtual bool 407 GetUUID (lldb_private::UUID* uuid) = 0; 408 409 //------------------------------------------------------------------ 410 /// Gets the symbol file spec list for this object file. 411 /// 412 /// If the object file format contains a debug symbol file link, 413 /// the values will be return in the FileSpecList. 414 /// 415 /// @return 416 /// Returns filespeclist. 417 //------------------------------------------------------------------ 418 virtual lldb_private::FileSpecList 419 GetDebugSymbolFilePaths() 420 { 421 return FileSpecList(); 422 } 423 424 //------------------------------------------------------------------ 425 /// Gets whether endian swapping should occur when extracting data 426 /// from this object file. 427 /// 428 /// @return 429 /// Returns \b true if endian swapping is needed, \b false 430 /// otherwise. 431 //------------------------------------------------------------------ 432 virtual lldb::ByteOrder 433 GetByteOrder () const = 0; 434 435 //------------------------------------------------------------------ 436 /// Attempts to parse the object header. 437 /// 438 /// This function is used as a test to see if a given plug-in 439 /// instance can parse the header data already contained in 440 /// ObjectFile::m_data. If an object file parser does not 441 /// recognize that magic bytes in a header, false should be returned 442 /// and the next plug-in can attempt to parse an object file. 443 /// 444 /// @return 445 /// Returns \b true if the header was parsed succesfully, \b 446 /// false otherwise. 447 //------------------------------------------------------------------ 448 virtual bool 449 ParseHeader () = 0; 450 451 //------------------------------------------------------------------ 452 /// Returns a reference to the UnwindTable for this ObjectFile 453 /// 454 /// The UnwindTable contains FuncUnwinders objects for any function in 455 /// this ObjectFile. If a FuncUnwinders object hasn't been created yet 456 /// (i.e. the function has yet to be unwound in a stack walk), it 457 /// will be created when requested. Specifically, we do not create 458 /// FuncUnwinders objects for functions until they are needed. 459 /// 460 /// @return 461 /// Returns the unwind table for this object file. 462 //------------------------------------------------------------------ 463 virtual lldb_private::UnwindTable& 464 GetUnwindTable () { return m_unwind_table; } 465 466 //------------------------------------------------------------------ 467 /// Similar to Process::GetImageInfoAddress(). 468 /// 469 /// Some platforms embed auxiliary structures useful to debuggers in the 470 /// address space of the inferior process. This method returns the address 471 /// of such a structure if the information can be resolved via entries in 472 /// the object file. ELF, for example, provides a means to hook into the 473 /// runtime linker so that a debugger may monitor the loading and unloading 474 /// of shared libraries. 475 /// 476 /// @return 477 /// The address of any auxiliary tables, or an invalid address if this 478 /// object file format does not support or contain such information. 479 virtual lldb_private::Address 480 GetImageInfoAddress () { return Address(); } 481 482 //------------------------------------------------------------------ 483 /// Returns the address of the Entry Point in this object file - if 484 /// the object file doesn't have an entry point (because it is not an 485 /// executable file) then an invalid address is returned. 486 /// 487 /// @return 488 /// Returns the entry address for this module. 489 //------------------------------------------------------------------ 490 virtual lldb_private::Address 491 GetEntryPointAddress () { return Address();} 492 493 //------------------------------------------------------------------ 494 /// Returns the address that represents the header of this object 495 /// file. 496 /// 497 /// The header address is defined as where the header for the object 498 /// file is that describes the content of the file. If the header 499 /// doesn't appear in a section that is defined in the object file, 500 /// an address with no section is returned that has the file offset 501 /// set in the m_file_offset member of the lldb_private::Address object. 502 /// 503 /// @return 504 /// Returns the entry address for this module. 505 //------------------------------------------------------------------ 506 virtual lldb_private::Address 507 GetHeaderAddress () { return Address(m_memory_addr);} 508 509 510 virtual uint32_t 511 GetNumThreadContexts () 512 { 513 return 0; 514 } 515 516 virtual lldb::RegisterContextSP 517 GetThreadContextAtIndex (uint32_t idx, lldb_private::Thread &thread) 518 { 519 return lldb::RegisterContextSP(); 520 } 521 522 //------------------------------------------------------------------ 523 /// The object file should be able to calculate its type by looking 524 /// at its file header and possibly the sections or other data in 525 /// the object file. The file type is used in the debugger to help 526 /// select the correct plug-ins for the job at hand, so this is 527 /// important to get right. If any eTypeXXX definitions do not match 528 /// up with the type of file you are loading, please feel free to 529 /// add a new enumeration value. 530 /// 531 /// @return 532 /// The calculated file type for the current object file. 533 //------------------------------------------------------------------ 534 virtual Type 535 CalculateType() = 0; 536 537 //------------------------------------------------------------------ 538 /// In cases where the type can't be calculated (elf files), this 539 /// routine allows someone to explicitly set it. As an example, 540 /// SymbolVendorELF uses this routine to set eTypeDebugInfo when 541 /// loading debug link files. 542 virtual void 543 SetType (Type type) 544 { 545 m_type = type; 546 } 547 548 //------------------------------------------------------------------ 549 /// The object file should be able to calculate the strata of the 550 /// object file. 551 /// 552 /// Many object files for platforms might be for either user space 553 /// debugging or for kernel debugging. If your object file subclass 554 /// can figure this out, it will help with debugger plug-in selection 555 /// when it comes time to debug. 556 /// 557 /// @return 558 /// The calculated object file strata for the current object 559 /// file. 560 //------------------------------------------------------------------ 561 virtual Strata 562 CalculateStrata() = 0; 563 564 //------------------------------------------------------------------ 565 /// Get the object file version numbers. 566 /// 567 /// Many object files have a set of version numbers that describe 568 /// the version of the executable or shared library. Typically there 569 /// are major, minor and build, but there may be more. This function 570 /// will extract the versions from object files if they are available. 571 /// 572 /// If \a versions is NULL, or if \a num_versions is 0, the return 573 /// value will indicate how many version numbers are available in 574 /// this object file. Then a subsequent call can be made to this 575 /// function with a value of \a versions and \a num_versions that 576 /// has enough storage to store some or all version numbers. 577 /// 578 /// @param[out] versions 579 /// A pointer to an array of uint32_t types that is \a num_versions 580 /// long. If this value is NULL, the return value will indicate 581 /// how many version numbers are required for a subsequent call 582 /// to this function so that all versions can be retrieved. If 583 /// the value is non-NULL, then at most \a num_versions of the 584 /// existing versions numbers will be filled into \a versions. 585 /// If there is no version information available, \a versions 586 /// will be filled with \a num_versions UINT32_MAX values 587 /// and zero will be returned. 588 /// 589 /// @param[in] num_versions 590 /// The maximum number of entries to fill into \a versions. If 591 /// this value is zero, then the return value will indicate 592 /// how many version numbers there are in total so another call 593 /// to this function can be make with adequate storage in 594 /// \a versions to get all of the version numbers. If \a 595 /// num_versions is less than the actual number of version 596 /// numbers in this object file, only \a num_versions will be 597 /// filled into \a versions (if \a versions is non-NULL). 598 /// 599 /// @return 600 /// This function always returns the number of version numbers 601 /// that this object file has regardless of the number of 602 /// version numbers that were copied into \a versions. 603 //------------------------------------------------------------------ 604 virtual uint32_t 605 GetVersion (uint32_t *versions, uint32_t num_versions) 606 { 607 if (versions && num_versions) 608 { 609 for (uint32_t i=0; i<num_versions; ++i) 610 versions[i] = UINT32_MAX; 611 } 612 return 0; 613 } 614 615 //------------------------------------------------------------------ 616 // Member Functions 617 //------------------------------------------------------------------ 618 Type 619 GetType () 620 { 621 if (m_type == eTypeInvalid) 622 m_type = CalculateType(); 623 return m_type; 624 } 625 626 Strata 627 GetStrata () 628 { 629 if (m_strata == eStrataInvalid) 630 m_strata = CalculateStrata(); 631 return m_strata; 632 } 633 634 // When an object file is in memory, subclasses should try and lock 635 // the process weak pointer. If the process weak pointer produces a 636 // valid ProcessSP, then subclasses can call this function to read 637 // memory. 638 static lldb::DataBufferSP 639 ReadMemory (const lldb::ProcessSP &process_sp, 640 lldb::addr_t addr, 641 size_t byte_size); 642 643 size_t 644 GetData (off_t offset, size_t length, DataExtractor &data) const; 645 646 size_t 647 CopyData (off_t offset, size_t length, void *dst) const; 648 649 size_t 650 ReadSectionData (const Section *section, 651 off_t section_offset, 652 void *dst, 653 size_t dst_len) const; 654 size_t 655 ReadSectionData (const Section *section, 656 DataExtractor& section_data) const; 657 658 size_t 659 MemoryMapSectionData (const Section *section, 660 DataExtractor& section_data) const; 661 662 bool 663 IsInMemory () const 664 { 665 return m_memory_addr != LLDB_INVALID_ADDRESS; 666 } 667 668protected: 669 //------------------------------------------------------------------ 670 // Member variables. 671 //------------------------------------------------------------------ 672 FileSpec m_file; 673 Type m_type; 674 Strata m_strata; 675 lldb::addr_t m_file_offset; ///< The offset in bytes into the file, or the address in memory 676 lldb::addr_t m_length; ///< The length of this object file if it is known (can be zero if length is unknown or can't be determined). 677 DataExtractor m_data; ///< The data for this object file so things can be parsed lazily. 678 lldb_private::UnwindTable m_unwind_table; /// < Table of FuncUnwinders objects created for this ObjectFile's functions 679 lldb::ProcessWP m_process_wp; 680 const lldb::addr_t m_memory_addr; 681 std::unique_ptr<lldb_private::SectionList> m_sections_ap; 682 std::unique_ptr<lldb_private::Symtab> m_symtab_ap; 683 684 //------------------------------------------------------------------ 685 /// Sets the architecture for a module. At present the architecture 686 /// can only be set if it is invalid. It is not allowed to switch from 687 /// one concrete architecture to another. 688 /// 689 /// @param[in] new_arch 690 /// The architecture this module will be set to. 691 /// 692 /// @return 693 /// Returns \b true if the architecture was changed, \b 694 /// false otherwise. 695 //------------------------------------------------------------------ 696 bool SetModulesArchitecture (const ArchSpec &new_arch); 697 698private: 699 DISALLOW_COPY_AND_ASSIGN (ObjectFile); 700}; 701 702} // namespace lldb_private 703 704#endif // liblldb_ObjectFile_h_ 705 706