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