ObjectContainer.h revision e40b6424d9e49306392bec4b44060da36414c382 
1//===-- ObjectContainer.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_ObjectContainer_h_
11#define liblldb_ObjectContainer_h_
12
13// C Includes
14// C++ Includes
15// Other libraries and framework includes
16// Project includes
17
18#include "lldb/lldb-private.h"
19#include "lldb/Core/DataExtractor.h"
20#include "lldb/Host/FileSpec.h"
21#include "lldb/Core/ModuleChild.h"
22#include "lldb/Core/PluginInterface.h"
23#include "lldb/Host/Endian.h"
24
25namespace lldb_private {
26
27//----------------------------------------------------------------------
28/// @class ObjectContainer ObjectContainer.h "lldb/Symbol/ObjectContainer.h"
29/// @brief A plug-in interface definition class for object containers.
30///
31/// Object containers contain object files from one or more
32/// architectures, and also can contain one or more named objects.
33///
34/// Typical object containers are static libraries (.a files) that
35/// contain multiple named object files, and universal files that contain
36/// multiple architectures.
37//----------------------------------------------------------------------
38class ObjectContainer :
39    public PluginInterface,
40    public ModuleChild
41{
42public:
43    //------------------------------------------------------------------
44    /// Construct with a parent module, offset, and header data.
45    ///
46    /// Object files belong to modules and a valid module must be
47    /// supplied upon construction. The at an offset within a file for
48    /// objects that contain more than one architecture or object.
49    //------------------------------------------------------------------
50    ObjectContainer (Module* module,
51                     const FileSpec *file,
52                     lldb::addr_t offset,
53                     lldb::addr_t length,
54                     lldb::DataBufferSP& headerDataSP) :
55        ModuleChild (module),
56        m_file (),  // This file can be different than the module's file spec
57        m_offset (offset),
58        m_length (length),
59        m_data (headerDataSP, lldb::endian::InlHostByteOrder(), 4)
60    {
61        if (file)
62            m_file = *file;
63    }
64
65    //------------------------------------------------------------------
66    /// Destructor.
67    ///
68    /// The destructor is virtual since this class is designed to be
69    /// inherited from by the plug-in instance.
70    //------------------------------------------------------------------
71    virtual
72    ~ObjectContainer()
73    {
74    }
75
76    //------------------------------------------------------------------
77    /// Dump a description of this object to a Stream.
78    ///
79    /// Dump a description of the current contents of this object
80    /// to the supplied stream \a s. The dumping should include the
81    /// section list if it has been parsed, and the symbol table
82    /// if it has been parsed.
83    ///
84    /// @param[in] s
85    ///     The stream to which to dump the object descripton.
86    //------------------------------------------------------------------
87    virtual void
88    Dump (Stream *s) const = 0;
89
90    //------------------------------------------------------------------
91    /// Gets the architecture given an index.
92    ///
93    /// Copies the architecture specification for index \a idx.
94    ///
95    /// @param[in] idx
96    ///     The architecture index to extract.
97    ///
98    /// @param[out] arch
99    ///     A architecture object that will be filled in if \a idx is a
100    ///     architecture valid index.
101    ///
102    /// @return
103    ///     Returns \b true if \a idx is valid and \a arch has been
104    ///     filled in, \b false otherwise.
105    ///
106    /// @see ObjectContainer::GetNumArchitectures() const
107    //------------------------------------------------------------------
108    virtual bool
109    GetArchitectureAtIndex (uint32_t idx, ArchSpec& arch) const
110    {
111        return false;
112    }
113
114    //------------------------------------------------------------------
115    /// Returns the offset into a file at which this object resides.
116    ///
117    /// Some files contain many object files, and this function allows
118    /// access to an object's offset within the file.
119    ///
120    /// @return
121    ///     The offset in bytes into the file. Defaults to zero for
122    ///     simple object files that a represented by an entire file.
123    //------------------------------------------------------------------
124    virtual lldb::addr_t
125    GetOffset () const
126    { return m_offset; }
127
128    virtual lldb::addr_t
129    GetByteSize () const
130    { return m_length; }
131
132    //------------------------------------------------------------------
133    /// Get the number of objects within this object file (archives).
134    ///
135    /// @return
136    ///     Zero for object files that are not archives, or the number
137    ///     of objects contained in the archive.
138    //------------------------------------------------------------------
139    virtual size_t
140    GetNumObjects () const
141    { return 0; }
142
143    //------------------------------------------------------------------
144    /// Get the number of architectures in this object file.
145    ///
146    /// The default implementation returns 1 as for object files that
147    /// contain a single architecture. ObjectContainer instances that
148    /// contain more than one architecture should override this function
149    /// and return an appropriate value.
150    ///
151    /// @return
152    ///     The number of architectures contained in this object file.
153    //------------------------------------------------------------------
154    virtual size_t
155    GetNumArchitectures () const
156    { return 0; }
157
158    //------------------------------------------------------------------
159    /// Attempts to parse the object header.
160    ///
161    /// This function is used as a test to see if a given plug-in
162    /// instance can parse the header data already contained in
163    /// ObjectContainer::m_data. If an object file parser does not
164    /// recognize that magic bytes in a header, false should be returned
165    /// and the next plug-in can attempt to parse an object file.
166    ///
167    /// @return
168    ///     Returns \b true if the header was parsed succesfully, \b
169    ///     false otherwise.
170    //------------------------------------------------------------------
171    virtual bool
172    ParseHeader () = 0;
173
174    //------------------------------------------------------------------
175    /// Selects an architecture in an object file.
176    ///
177    /// Object files that contain a single architecture should verify
178    /// that the specified \a arch matches the architecture in in
179    /// object file and return \b true or \b false accordingly.
180    ///
181    /// Object files that contain more than one architecture should
182    /// attempt to select that architecture, and if successful, clear
183    /// out any previous state from any previously selected architecture
184    /// and prepare to return information for the new architecture.
185    ///
186    /// @return
187    ///     Returns a pointer to the object file of the requested \a
188    ///     arch and optional \a name. Returns NULL of no such object
189    ///     file exists in the container.
190    //------------------------------------------------------------------
191    virtual lldb::ObjectFileSP
192    GetObjectFile (const FileSpec *file) = 0;
193
194    virtual bool
195    ObjectAtIndexIsContainer (uint32_t object_idx)
196    {
197        return false;
198    }
199
200    virtual ObjectFile *
201    GetObjectFileAtIndex (uint32_t object_idx)
202    {
203        return NULL;
204    }
205
206    virtual ObjectContainer *
207    GetObjectContainerAtIndex (uint32_t object_idx)
208    {
209        return NULL;
210    }
211
212    virtual const char *
213    GetObjectNameAtIndex (uint32_t object_idx) const
214    {
215        return NULL;
216    }
217
218protected:
219    //------------------------------------------------------------------
220    // Member variables.
221    //------------------------------------------------------------------
222    FileSpec m_file; ///< The file that represents this container objects (which can be different from the module's file).
223    lldb::addr_t m_offset; ///< The offset in bytes into the file, or the address in memory
224    lldb::addr_t m_length; ///< The size in bytes if known (can be zero).
225    DataExtractor m_data; ///< The data for this object file so things can be parsed lazily.
226
227private:
228    DISALLOW_COPY_AND_ASSIGN (ObjectContainer);
229};
230
231} // namespace lldb_private
232
233#endif  // liblldb_ObjectContainer_h_
234