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