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