1 //===-- ObjectContainer.h ---------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_ObjectContainer_h_
11 #define liblldb_ObjectContainer_h_
13 #include "lldb/Core/ModuleChild.h"
14 #include "lldb/Core/PluginInterface.h"
15 #include "lldb/Utility/DataExtractor.h"
16 #include "lldb/Utility/Endian.h"
17 #include "lldb/Utility/FileSpec.h"
18 #include "lldb/lldb-private.h"
20 namespace lldb_private {
22 //----------------------------------------------------------------------
23 /// @class ObjectContainer ObjectContainer.h "lldb/Symbol/ObjectContainer.h"
24 /// A plug-in interface definition class for object containers.
26 /// Object containers contain object files from one or more architectures, and
27 /// also can contain one or more named objects.
29 /// Typical object containers are static libraries (.a files) that contain
30 /// multiple named object files, and universal files that contain multiple
32 //----------------------------------------------------------------------
33 class ObjectContainer : public PluginInterface, public ModuleChild {
35 //------------------------------------------------------------------
36 /// Construct with a parent module, offset, and header data.
38 /// Object files belong to modules and a valid module must be supplied upon
39 /// construction. The at an offset within a file for objects that contain
40 /// more than one architecture or object.
41 //------------------------------------------------------------------
42 ObjectContainer(const lldb::ModuleSP &module_sp, const FileSpec *file,
43 lldb::offset_t file_offset, lldb::offset_t length,
44 lldb::DataBufferSP &data_sp, lldb::offset_t data_offset)
45 : ModuleChild(module_sp),
46 m_file(), // This file can be different than the module's file spec
47 m_offset(file_offset), m_length(length), m_data() {
51 m_data.SetData(data_sp, data_offset, length);
54 //------------------------------------------------------------------
57 /// The destructor is virtual since this class is designed to be inherited
58 /// from by the plug-in instance.
59 //------------------------------------------------------------------
60 ~ObjectContainer() override = default;
62 //------------------------------------------------------------------
63 /// Dump a description of this object to a Stream.
65 /// Dump a description of the current contents of this object to the
66 /// supplied stream \a s. The dumping should include the section list if it
67 /// has been parsed, and the symbol table if it has been parsed.
70 /// The stream to which to dump the object description.
71 //------------------------------------------------------------------
72 virtual void Dump(Stream *s) const = 0;
74 //------------------------------------------------------------------
75 /// Gets the architecture given an index.
77 /// Copies the architecture specification for index \a idx.
80 /// The architecture index to extract.
83 /// A architecture object that will be filled in if \a idx is a
84 /// architecture valid index.
87 /// Returns \b true if \a idx is valid and \a arch has been
88 /// filled in, \b false otherwise.
90 /// @see ObjectContainer::GetNumArchitectures() const
91 //------------------------------------------------------------------
92 virtual bool GetArchitectureAtIndex(uint32_t idx, ArchSpec &arch) const {
96 //------------------------------------------------------------------
97 /// Returns the offset into a file at which this object resides.
99 /// Some files contain many object files, and this function allows access to
100 /// an object's offset within the file.
103 /// The offset in bytes into the file. Defaults to zero for
104 /// simple object files that a represented by an entire file.
105 //------------------------------------------------------------------
106 virtual lldb::addr_t GetOffset() const { return m_offset; }
108 virtual lldb::addr_t GetByteSize() const { return m_length; }
110 //------------------------------------------------------------------
111 /// Get the number of objects within this object file (archives).
114 /// Zero for object files that are not archives, or the number
115 /// of objects contained in the archive.
116 //------------------------------------------------------------------
117 virtual size_t GetNumObjects() const { return 0; }
119 //------------------------------------------------------------------
120 /// Get the number of architectures in this object file.
122 /// The default implementation returns 1 as for object files that contain a
123 /// single architecture. ObjectContainer instances that contain more than
124 /// one architecture should override this function and return an appropriate
128 /// The number of architectures contained in this object file.
129 //------------------------------------------------------------------
130 virtual size_t GetNumArchitectures() const { return 0; }
132 //------------------------------------------------------------------
133 /// Attempts to parse the object header.
135 /// This function is used as a test to see if a given plug-in instance can
136 /// parse the header data already contained in ObjectContainer::m_data. If
137 /// an object file parser does not recognize that magic bytes in a header,
138 /// false should be returned and the next plug-in can attempt to parse an
142 /// Returns \b true if the header was parsed successfully, \b
144 //------------------------------------------------------------------
145 virtual bool ParseHeader() = 0;
147 //------------------------------------------------------------------
148 /// Selects an architecture in an object file.
150 /// Object files that contain a single architecture should verify that the
151 /// specified \a arch matches the architecture in in object file and return
152 /// \b true or \b false accordingly.
154 /// Object files that contain more than one architecture should attempt to
155 /// select that architecture, and if successful, clear out any previous
156 /// state from any previously selected architecture and prepare to return
157 /// information for the new architecture.
160 /// Returns a pointer to the object file of the requested \a
161 /// arch and optional \a name. Returns nullptr of no such object
162 /// file exists in the container.
163 //------------------------------------------------------------------
164 virtual lldb::ObjectFileSP GetObjectFile(const FileSpec *file) = 0;
166 virtual bool ObjectAtIndexIsContainer(uint32_t object_idx) { return false; }
168 virtual ObjectFile *GetObjectFileAtIndex(uint32_t object_idx) {
172 virtual ObjectContainer *GetObjectContainerAtIndex(uint32_t object_idx) {
176 virtual const char *GetObjectNameAtIndex(uint32_t object_idx) const {
181 //------------------------------------------------------------------
183 //------------------------------------------------------------------
184 FileSpec m_file; ///< The file that represents this container objects (which
185 ///can be different from the module's file).
187 m_offset; ///< The offset in bytes into the file, or the address in memory
188 lldb::addr_t m_length; ///< The size in bytes if known (can be zero).
190 m_data; ///< The data for this object file so things can be parsed lazily.
193 DISALLOW_COPY_AND_ASSIGN(ObjectContainer);
196 } // namespace lldb_private
198 #endif // liblldb_ObjectContainer_h_