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