ObjectFile.h revision b344843f75ef893762c93fd0a22d2d45712ce74d
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 PluginInterface, 54 public ModuleChild 55{ 56friend class lldb_private::Module; 57 58public: 59 //------------------------------------------------------------------ 60 /// Construct with a parent module, offset, and header data. 61 /// 62 /// Object files belong to modules and a valid module must be 63 /// supplied upon construction. The at an offset within a file for 64 /// objects that contain more than one architecture or object. 65 //------------------------------------------------------------------ 66 ObjectFile (Module* module, const FileSpec *file_spec_ptr, lldb::addr_t offset, lldb::addr_t length, lldb::DataBufferSP& headerDataSP) : 67 ModuleChild (module), 68 m_file (), // This file could be different from the original module's file 69 m_offset (offset), 70 m_length (length), 71 m_data (headerDataSP, lldb::endian::InlHostByteOrder(), 4), 72 m_unwind_table (*this) 73 { 74 if (file_spec_ptr) 75 m_file = *file_spec_ptr; 76 } 77 78 //------------------------------------------------------------------ 79 /// Destructor. 80 /// 81 /// The destructor is virtual since this class is designed to be 82 /// inherited from by the plug-in instance. 83 //------------------------------------------------------------------ 84 virtual 85 ~ObjectFile() 86 { 87 } 88 89 //------------------------------------------------------------------ 90 /// Dump a description of this object to a Stream. 91 /// 92 /// Dump a description of the current contents of this object 93 /// to the supplied stream \a s. The dumping should include the 94 /// section list if it has been parsed, and the symbol table 95 /// if it has been parsed. 96 /// 97 /// @param[in] s 98 /// The stream to which to dump the object descripton. 99 //------------------------------------------------------------------ 100 virtual void 101 Dump (Stream *s) = 0; 102 103 //------------------------------------------------------------------ 104 /// Find a ObjectFile plug-in that can parse \a file_spec. 105 /// 106 /// Scans all loaded plug-in interfaces that implement versions of 107 /// the ObjectFile plug-in interface and returns the first 108 /// instance that can parse the file. 109 /// 110 /// @param[in] module 111 /// The parent module that owns this object file. 112 /// 113 /// @param[in] file_spec 114 /// A file specification that indicates which file to use as the 115 /// object file. 116 /// 117 /// @param[in] file_offset 118 /// The offset into the file at which to start parsing the 119 /// object. This is for files that contain multiple 120 /// architectures or objects. 121 /// 122 /// @param[in] file_size 123 /// The size of the current object file if it can be determined 124 /// or if it is known. This can be zero. 125 /// 126 /// @see ObjectFile::ParseHeader() 127 //------------------------------------------------------------------ 128 static ObjectFile* 129 FindPlugin (Module* module, 130 const FileSpec* file_spec, 131 lldb::addr_t file_offset, 132 lldb::addr_t file_size); 133 134 //------------------------------------------------------------------ 135 /// Gets the address size in bytes for the current object file. 136 /// 137 /// @return 138 /// The size of an address in bytes for the currently selected 139 /// architecture (and object for archives). Returns zero if no 140 /// architecture or object has been selected. 141 //------------------------------------------------------------------ 142 virtual size_t 143 GetAddressByteSize () const = 0; 144 145 //------------------------------------------------------------------ 146 /// Get the address type given a file address in an object file. 147 /// 148 /// Many binary file formats know what kinds 149 /// This is primarily for ARM binaries, though it can be applied to 150 /// any executable file format that supports different opcode types 151 /// within the same binary. ARM binaries support having both ARM and 152 /// Thumb within the same executable container. We need to be able 153 /// to get 154 /// @return 155 /// The size of an address in bytes for the currently selected 156 /// architecture (and object for archives). Returns zero if no 157 /// architecture or object has been selected. 158 //------------------------------------------------------------------ 159 virtual AddressClass 160 GetAddressClass (lldb::addr_t file_addr); 161 162 //------------------------------------------------------------------ 163 /// Extract the dependent modules from an object file. 164 /// 165 /// If an object file has information about which other images it 166 /// depends on (such as shared libraries), this function will 167 /// provide the list. Since many executables or shared libraries 168 /// may depend on the same files, 169 /// FileSpecList::AppendIfUnique(const FileSpec &) should be 170 /// used to make sure any files that are added are not already in 171 /// the list. 172 /// 173 /// @param[out] file_list 174 /// A list of file specification objects that gets dependent 175 /// files appended to. 176 /// 177 /// @return 178 /// The number of new files that were appended to \a file_list. 179 /// 180 /// @see FileSpecList::AppendIfUnique(const FileSpec &) 181 //------------------------------------------------------------------ 182 virtual uint32_t 183 GetDependentModules (FileSpecList& file_list) = 0; 184 185 //------------------------------------------------------------------ 186 /// Tells whether this object file is capable of being the main executable 187 /// for a process. 188 /// 189 /// @return 190 /// \b true if it is, \b false otherwise. 191 //------------------------------------------------------------------ 192 virtual bool 193 IsExecutable () const = 0; 194 195 //------------------------------------------------------------------ 196 /// Returns the offset into a file at which this object resides. 197 /// 198 /// Some files contain many object files, and this function allows 199 /// access to an object's offset within the file. 200 /// 201 /// @return 202 /// The offset in bytes into the file. Defaults to zero for 203 /// simple object files that a represented by an entire file. 204 //------------------------------------------------------------------ 205 virtual lldb::addr_t 206 GetOffset () const 207 { return m_offset; } 208 209 virtual lldb::addr_t 210 GetByteSize () const 211 { return m_length; } 212 213 //------------------------------------------------------------------ 214 /// Get accessor to the object file specification. 215 /// 216 /// @return 217 /// The file specification object pointer if there is one, or 218 /// NULL if this object is only from memory. 219 //------------------------------------------------------------------ 220 virtual FileSpec& 221 GetFileSpec() { return m_file; } 222 223 //------------------------------------------------------------------ 224 /// Get const accessor to the object file specification. 225 /// 226 /// @return 227 /// The const file specification object pointer if there is one, 228 /// or NULL if this object is only from memory. 229 //------------------------------------------------------------------ 230 virtual const FileSpec& 231 GetFileSpec() const { return m_file; } 232 233 //------------------------------------------------------------------ 234 /// Get the name of the cpu, vendor and OS for this object file. 235 /// 236 /// This value is a string that represents the target triple where 237 /// the cpu type, the vendor and the OS are encoded into a string. 238 /// 239 /// @param[out] target_triple 240 /// The string value of the target triple. 241 /// 242 /// @return 243 /// \b True if the target triple was able to be computed, \b 244 /// false otherwise. 245 //------------------------------------------------------------------ 246 virtual bool 247 GetArchitecture (ArchSpec &arch) = 0; 248 249 //------------------------------------------------------------------ 250 /// Gets the section list for the currently selected architecture 251 /// (and object for archives). 252 /// 253 /// Section list parsing can be deferred by ObjectFile instances 254 /// until this accessor is called the first time. 255 /// 256 /// @return 257 /// The list of sections contained in this object file. 258 //------------------------------------------------------------------ 259 virtual SectionList * 260 GetSectionList () = 0; 261 262 //------------------------------------------------------------------ 263 /// Gets the symbol table for the currently selected architecture 264 /// (and object for archives). 265 /// 266 /// Symbol table parsing can be deferred by ObjectFile instances 267 /// until this accessor is called the first time. 268 /// 269 /// @return 270 /// The symbol table for this object file. 271 //------------------------------------------------------------------ 272 virtual Symtab * 273 GetSymtab () = 0; 274 275 //------------------------------------------------------------------ 276 /// Gets the UUID for this object file. 277 /// 278 /// If the object file format contains a UUID, the value should be 279 /// returned. Else ObjectFile instances should return the MD5 280 /// checksum of all of the bytes for the object file (or memory for 281 /// memory based object files). 282 /// 283 /// @return 284 /// Returns \b true if a UUID was successfully extracted into 285 /// \a uuid, \b false otherwise. 286 //------------------------------------------------------------------ 287 virtual bool 288 GetUUID (lldb_private::UUID* uuid) = 0; 289 290 //------------------------------------------------------------------ 291 /// Gets whether endian swapping should occur when extracting data 292 /// from this object file. 293 /// 294 /// @return 295 /// Returns \b true if endian swapping is needed, \b false 296 /// otherwise. 297 //------------------------------------------------------------------ 298 virtual lldb::ByteOrder 299 GetByteOrder () const = 0; 300 301 //------------------------------------------------------------------ 302 /// Attempts to parse the object header. 303 /// 304 /// This function is used as a test to see if a given plug-in 305 /// instance can parse the header data already contained in 306 /// ObjectFile::m_data. If an object file parser does not 307 /// recognize that magic bytes in a header, false should be returned 308 /// and the next plug-in can attempt to parse an object file. 309 /// 310 /// @return 311 /// Returns \b true if the header was parsed succesfully, \b 312 /// false otherwise. 313 //------------------------------------------------------------------ 314 virtual bool 315 ParseHeader () = 0; 316 317 //------------------------------------------------------------------ 318 /// Returns a reference to the UnwindTable for this ObjectFile 319 /// 320 /// The UnwindTable contains FuncUnwinders objects for any function in 321 /// this ObjectFile. If a FuncUnwinders object hasn't been created yet 322 /// (i.e. the function has yet to be unwound in a stack walk), it 323 /// will be created when requested. Specifically, we do not create 324 /// FuncUnwinders objects for functions until they are needed. 325 /// 326 /// @return 327 /// Returns the unwind table for this object file. 328 //------------------------------------------------------------------ 329 virtual lldb_private::UnwindTable& 330 GetUnwindTable () { return m_unwind_table; } 331 332 //------------------------------------------------------------------ 333 /// Similar to Process::GetImageInfoAddress(). 334 /// 335 /// Some platforms embed auxiliary structures useful to debuggers in the 336 /// address space of the inferior process. This method returns the address 337 /// of such a structure if the information can be resolved via entries in 338 /// the object file. ELF, for example, provides a means to hook into the 339 /// runtime linker so that a debugger may monitor the loading and unloading 340 /// of shared libraries. 341 /// 342 /// @return 343 /// The address of any auxiliary tables, or an invalid address if this 344 /// object file format does not support or contain such information. 345 virtual lldb_private::Address 346 GetImageInfoAddress () { return Address(); } 347 348 //------------------------------------------------------------------ 349 /// Returns the address of the Entry Point in this object file - if 350 /// the object file doesn't have an entry point (because it is not an 351 /// executable file) then an invalid address is returned. 352 /// 353 /// @return 354 /// Returns the entry address for this module. 355 //------------------------------------------------------------------ 356 virtual lldb_private::Address 357 GetEntryPointAddress () { return Address();} 358 359protected: 360 //------------------------------------------------------------------ 361 // Member variables. 362 //------------------------------------------------------------------ 363 FileSpec m_file; 364 lldb::addr_t m_offset; ///< The offset in bytes into the file, or the address in memory 365 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). 366 DataExtractor m_data; ///< The data for this object file so things can be parsed lazily. 367 lldb_private::UnwindTable m_unwind_table; /// < Table of FuncUnwinders objects created for this ObjectFile's functions 368 369 //------------------------------------------------------------------ 370 /// Sets the architecture for a module. At present the architecture 371 /// can only be set if it is invalid. It is not allowed to switch from 372 /// one concrete architecture to another. 373 /// 374 /// @param[in] new_arch 375 /// The architecture this module will be set to. 376 /// 377 /// @return 378 /// Returns \b true if the architecture was changed, \b 379 /// false otherwise. 380 //------------------------------------------------------------------ 381 bool SetModulesArchitecture (const ArchSpec &new_arch); 382 383private: 384 DISALLOW_COPY_AND_ASSIGN (ObjectFile); 385}; 386 387} // namespace lldb_private 388 389#endif // liblldb_ObjectFile_h_ 390 391