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