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