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