ObjectFile.h revision 3a4ea24572fad1e22525f8efb718d49d41e30398
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/Core/FileSpec.h" 16#include "lldb/Core/ModuleChild.h" 17#include "lldb/Core/PluginInterface.h" 18#include "lldb/Symbol/Symtab.h" 19#include "lldb/Symbol/UnwindTable.h" 20 21namespace lldb_private { 22 23//---------------------------------------------------------------------- 24/// @class ObjectFile ObjectFile.h "lldb/Symbol/ObjectFile.h" 25/// @brief A plug-in interface definition class for object file parsers. 26/// 27/// Object files belong to Module objects and know how to extract 28/// information from executable, shared library, and object (.o) files 29/// used by operating system runtime. The symbol table and section list 30/// for an object file. 31/// 32/// Object files can be represented by the entire file, or by part of a 33/// file. Examples of object files that are part of a file include 34/// object files that contain information for multiple architectures in 35/// the same file, or archive files that contain multiple objects 36/// (ranlib archives) (possibly for multiple architectures as well). 37/// 38/// Object archive files (e.g. ranlib archives) can contain 39/// multiple .o (object) files that must be selected by index or by name. 40/// The number of objects that an ObjectFile contains can be determined 41/// using the ObjectFile::GetNumObjects() const 42/// function, and followed by a call to 43/// ObjectFile::SelectObjectAtIndex (uint32_t) to change the currently 44/// selected object. Objects can also be selected by name using the 45/// ObjectFile::SelectObject(const char *) function. 46/// 47/// Once an architecture is selected (and an object is selected for 48/// for archives), the object file information can be extracted from 49/// this abstract class. 50//---------------------------------------------------------------------- 51class ObjectFile: 52 public PluginInterface, 53 public ModuleChild 54{ 55friend class lldb_private::Module; 56 57public: 58 //------------------------------------------------------------------ 59 /// Construct with a parent module, offset, and header data. 60 /// 61 /// Object files belong to modules and a valid module must be 62 /// supplied upon construction. The at an offset within a file for 63 /// objects that contain more than one architecture or object. 64 //------------------------------------------------------------------ 65 ObjectFile (Module* module, const FileSpec *file_spec_ptr, lldb::addr_t offset, lldb::addr_t length, lldb::DataBufferSP& headerDataSP) : 66 ModuleChild (module), 67 m_file (), // This file could be different from the original module's file 68 m_offset (offset), 69 m_length (length), 70 m_data (headerDataSP, lldb::eByteOrderHost, 4), 71 m_unwind_table (*this) 72 { 73 if (file_spec_ptr) 74 m_file = *file_spec_ptr; 75 } 76 77 //------------------------------------------------------------------ 78 /// Destructor. 79 /// 80 /// The destructor is virtual since this class is designed to be 81 /// inherited from by the plug-in instance. 82 //------------------------------------------------------------------ 83 virtual 84 ~ObjectFile() 85 { 86 } 87 88 //------------------------------------------------------------------ 89 /// Dump a description of this object to a Stream. 90 /// 91 /// Dump a description of the current contents of this object 92 /// to the supplied stream \a s. The dumping should include the 93 /// section list if it has been parsed, and the symbol table 94 /// if it has been parsed. 95 /// 96 /// @param[in] s 97 /// The stream to which to dump the object descripton. 98 //------------------------------------------------------------------ 99 virtual void 100 Dump (Stream *s) = 0; 101 102 //------------------------------------------------------------------ 103 /// Find a ObjectFile plug-in that can parse \a file_spec. 104 /// 105 /// Scans all loaded plug-in interfaces that implement versions of 106 /// the ObjectFile plug-in interface and returns the first 107 /// instance that can parse the file. 108 /// 109 /// @param[in] module 110 /// The parent module that owns this object file. 111 /// 112 /// @param[in] file_spec 113 /// A file specification that indicates which file to use as the 114 /// object file. 115 /// 116 /// @param[in] file_offset 117 /// The offset into the file at which to start parsing the 118 /// object. This is for files that contain multiple 119 /// architectures or objects. 120 /// 121 /// @param[in] file_size 122 /// The size of the current object file if it can be determined 123 /// or if it is known. This can be zero. 124 /// 125 /// @see ObjectFile::ParseHeader() 126 //------------------------------------------------------------------ 127 static ObjectFile* 128 FindPlugin (Module* module, 129 const FileSpec* file_spec, 130 lldb::addr_t file_offset, 131 lldb::addr_t file_size); 132 133 //------------------------------------------------------------------ 134 /// Gets the address size in bytes for the current object file. 135 /// 136 /// @return 137 /// The size of an address in bytes for the currently selected 138 /// architecture (and object for archives). Returns zero if no 139 /// architecture or object has been selected. 140 //------------------------------------------------------------------ 141 virtual size_t 142 GetAddressByteSize () const = 0; 143 144 //------------------------------------------------------------------ 145 /// Extract the dependent modules from an object file. 146 /// 147 /// If an object file has information about which other images it 148 /// depends on (such as shared libraries), this function will 149 /// provide the list. Since many executables or shared libraries 150 /// may depend on the same files, 151 /// FileSpecList::AppendIfUnique(const FileSpec &) should be 152 /// used to make sure any files that are added are not already in 153 /// the list. 154 /// 155 /// @param[out] file_list 156 /// A list of file specification objects that gets dependent 157 /// files appended to. 158 /// 159 /// @return 160 /// The number of new files that were appended to \a file_list. 161 /// 162 /// @see FileSpecList::AppendIfUnique(const FileSpec &) 163 //------------------------------------------------------------------ 164 virtual uint32_t 165 GetDependentModules (FileSpecList& file_list) = 0; 166 167 //------------------------------------------------------------------ 168 /// Tells whether this object file is capable of being the main executable 169 /// for a process. 170 /// 171 /// @return 172 /// \b true if it is, \b false otherwise. 173 //------------------------------------------------------------------ 174 virtual bool 175 IsExecutable () const = 0; 176 177 //------------------------------------------------------------------ 178 /// Returns the offset into a file at which this object resides. 179 /// 180 /// Some files contain many object files, and this function allows 181 /// access to an object's offset within the file. 182 /// 183 /// @return 184 /// The offset in bytes into the file. Defaults to zero for 185 /// simple object files that a represented by an entire file. 186 //------------------------------------------------------------------ 187 virtual lldb::addr_t 188 GetOffset () const 189 { return m_offset; } 190 191 virtual lldb::addr_t 192 GetByteSize () const 193 { return m_length; } 194 195 //------------------------------------------------------------------ 196 /// Get accessor to the object file specification. 197 /// 198 /// @return 199 /// The file specification object pointer if there is one, or 200 /// NULL if this object is only from memory. 201 //------------------------------------------------------------------ 202 virtual FileSpec& 203 GetFileSpec() { return m_file; } 204 205 //------------------------------------------------------------------ 206 /// Get const accessor to the object file specification. 207 /// 208 /// @return 209 /// The const file specification object pointer if there is one, 210 /// or NULL if this object is only from memory. 211 //------------------------------------------------------------------ 212 virtual const FileSpec& 213 GetFileSpec() const { return m_file; } 214 215 //------------------------------------------------------------------ 216 /// Get the name of the cpu, vendor and OS for this object file. 217 /// 218 /// This value is a string that represents the target triple where 219 /// the cpu type, the vendor and the OS are encoded into a string. 220 /// 221 /// @param[out] target_triple 222 /// The string value of the target triple. 223 /// 224 /// @return 225 /// \b True if the target triple was able to be computed, \b 226 /// false otherwise. 227 //------------------------------------------------------------------ 228 virtual bool 229 GetTargetTriple(ConstString &target_triple) = 0; 230 231 //------------------------------------------------------------------ 232 /// Gets the section list for the currently selected architecture 233 /// (and object for archives). 234 /// 235 /// Section list parsing can be deferred by ObjectFile instances 236 /// until this accessor is called the first time. 237 /// 238 /// @return 239 /// The list of sections contained in this object file. 240 //------------------------------------------------------------------ 241 virtual SectionList * 242 GetSectionList () = 0; 243 244 //------------------------------------------------------------------ 245 /// Gets the symbol table for the currently selected architecture 246 /// (and object for archives). 247 /// 248 /// Symbol table parsing can be deferred by ObjectFile instances 249 /// until this accessor is called the first time. 250 /// 251 /// @return 252 /// The symbol table for this object file. 253 //------------------------------------------------------------------ 254 virtual Symtab * 255 GetSymtab () = 0; 256 257 //------------------------------------------------------------------ 258 /// Gets the UUID for this object file. 259 /// 260 /// If the object file format contains a UUID, the value should be 261 /// returned. Else ObjectFile instances should return the MD5 262 /// checksum of all of the bytes for the object file (or memory for 263 /// memory based object files). 264 /// 265 /// @return 266 /// Returns \b true if a UUID was successfully extracted into 267 /// \a uuid, \b false otherwise. 268 //------------------------------------------------------------------ 269 virtual bool 270 GetUUID (UUID* uuid) = 0; 271 272 //------------------------------------------------------------------ 273 /// Gets wether endian swapping should occur when extracting data 274 /// from this object file. 275 /// 276 /// @return 277 /// Returns \b true if endian swapping is needed, \b false 278 /// otherwise. 279 //------------------------------------------------------------------ 280 virtual lldb::ByteOrder 281 GetByteOrder () const = 0; 282 283 //------------------------------------------------------------------ 284 /// Attempts to parse the object header. 285 /// 286 /// This function is used as a test to see if a given plug-in 287 /// instance can parse the header data already contained in 288 /// ObjectFile::m_data. If an object file parser does not 289 /// recognize that magic bytes in a header, false should be returned 290 /// and the next plug-in can attempt to parse an object file. 291 /// 292 /// @return 293 /// Returns \b true if the header was parsed succesfully, \b 294 /// false otherwise. 295 //------------------------------------------------------------------ 296 virtual bool 297 ParseHeader () = 0; 298 299 //------------------------------------------------------------------ 300 /// Returns a reference to the UnwindTable for this ObjectFile 301 /// 302 /// The UnwindTable contains FuncUnwinders objects for any function in 303 /// this ObjectFile. If a FuncUnwinders object hasn't been created yet 304 /// (i.e. the function has yet to be unwound in a stack walk), it 305 /// will be created when requested. Specifically, we do not create 306 /// FuncUnwinders objects for functions until they are needed. 307 /// 308 /// @return 309 /// Returns the unwind table for this object file. 310 //------------------------------------------------------------------ 311 virtual lldb_private::UnwindTable& 312 GetUnwindTable () { return m_unwind_table; } 313 314protected: 315 //------------------------------------------------------------------ 316 // Member variables. 317 //------------------------------------------------------------------ 318 FileSpec m_file; 319 lldb::addr_t m_offset; ///< The offset in bytes into the file, or the address in memory 320 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). 321 DataExtractor m_data; ///< The data for this object file so things can be parsed lazily. 322 lldb_private::UnwindTable m_unwind_table; /// < Table of FuncUnwinders objects created for this ObjectFile's functions 323 324 //------------------------------------------------------------------ 325 /// Sets the architecture for a module. At present the architecture 326 /// can only be set if it is invalid. It is not allowed to switch from 327 /// one concrete architecture to another. 328 /// 329 /// @param[in] new_arch 330 /// The architecture this module will be set to. 331 /// 332 /// @return 333 /// Returns \b true if the architecture was changed, \b 334 /// false otherwise. 335 //------------------------------------------------------------------ 336 bool SetModulesArchitecture (const ArchSpec &new_arch); 337 338private: 339 DISALLOW_COPY_AND_ASSIGN (ObjectFile); 340}; 341 342} // namespace lldb_private 343 344#endif // liblldb_ObjectFile_h_ 345 346