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