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