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_
15 // Other libraries and framework includes
17 #include "lldb/Core/ModuleChild.h"
18 #include "lldb/Core/PluginInterface.h"
19 #include "lldb/Utility/DataExtractor.h"
20 #include "lldb/Utility/Endian.h"
21 #include "lldb/Utility/FileSpec.h"
22 #include "lldb/lldb-private.h"
24 namespace lldb_private {
26 //----------------------------------------------------------------------
27 /// @class ObjectContainer ObjectContainer.h "lldb/Symbol/ObjectContainer.h"
28 /// @brief A plug-in interface definition class for object containers.
30 /// Object containers contain object files from one or more
31 /// architectures, and also can contain one or more named objects.
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 //----------------------------------------------------------------------
37 class ObjectContainer : public PluginInterface, public ModuleChild {
39 //------------------------------------------------------------------
40 /// Construct with a parent module, offset, and header data.
42 /// Object files belong to modules and a valid module must be
43 /// supplied upon construction. The at an offset within a file for
44 /// objects that contain more than one architecture or object.
45 //------------------------------------------------------------------
46 ObjectContainer(const lldb::ModuleSP &module_sp, const FileSpec *file,
47 lldb::offset_t file_offset, lldb::offset_t length,
48 lldb::DataBufferSP &data_sp, lldb::offset_t data_offset)
49 : ModuleChild(module_sp),
50 m_file(), // This file can be different than the module's file spec
51 m_offset(file_offset), m_length(length), m_data() {
55 m_data.SetData(data_sp, data_offset, length);
58 //------------------------------------------------------------------
61 /// The destructor is virtual since this class is designed to be
62 /// inherited from by the plug-in instance.
63 //------------------------------------------------------------------
64 ~ObjectContainer() override = default;
66 //------------------------------------------------------------------
67 /// Dump a description of this object to a Stream.
69 /// Dump a description of the current contents of this object
70 /// to the supplied stream \a s. The dumping should include the
71 /// section list if it has been parsed, and the symbol table
72 /// if it has been parsed.
75 /// The stream to which to dump the object description.
76 //------------------------------------------------------------------
77 virtual void Dump(Stream *s) const = 0;
79 //------------------------------------------------------------------
80 /// Gets the architecture given an index.
82 /// Copies the architecture specification for index \a idx.
85 /// The architecture index to extract.
88 /// A architecture object that will be filled in if \a idx is a
89 /// architecture valid index.
92 /// Returns \b true if \a idx is valid and \a arch has been
93 /// filled in, \b false otherwise.
95 /// @see ObjectContainer::GetNumArchitectures() const
96 //------------------------------------------------------------------
97 virtual bool GetArchitectureAtIndex(uint32_t idx, ArchSpec &arch) const {
101 //------------------------------------------------------------------
102 /// Returns the offset into a file at which this object resides.
104 /// Some files contain many object files, and this function allows
105 /// access to an object's offset within the file.
108 /// The offset in bytes into the file. Defaults to zero for
109 /// simple object files that a represented by an entire file.
110 //------------------------------------------------------------------
111 virtual lldb::addr_t GetOffset() const { return m_offset; }
113 virtual lldb::addr_t GetByteSize() const { return m_length; }
115 //------------------------------------------------------------------
116 /// Get the number of objects within this object file (archives).
119 /// Zero for object files that are not archives, or the number
120 /// of objects contained in the archive.
121 //------------------------------------------------------------------
122 virtual size_t GetNumObjects() const { return 0; }
124 //------------------------------------------------------------------
125 /// Get the number of architectures in this object file.
127 /// The default implementation returns 1 as for object files that
128 /// contain a single architecture. ObjectContainer instances that
129 /// contain more than one architecture should override this function
130 /// and return an appropriate value.
133 /// The number of architectures contained in this object file.
134 //------------------------------------------------------------------
135 virtual size_t GetNumArchitectures() const { return 0; }
137 //------------------------------------------------------------------
138 /// Attempts to parse the object header.
140 /// This function is used as a test to see if a given plug-in
141 /// instance can parse the header data already contained in
142 /// ObjectContainer::m_data. If an object file parser does not
143 /// recognize that magic bytes in a header, false should be returned
144 /// and the next plug-in can attempt to parse an object file.
147 /// Returns \b true if the header was parsed successfully, \b
149 //------------------------------------------------------------------
150 virtual bool ParseHeader() = 0;
152 //------------------------------------------------------------------
153 /// Selects an architecture in an object file.
155 /// Object files that contain a single architecture should verify
156 /// that the specified \a arch matches the architecture in in
157 /// object file and return \b true or \b false accordingly.
159 /// Object files that contain more than one architecture should
160 /// attempt to select that architecture, and if successful, clear
161 /// out any previous state from any previously selected architecture
162 /// and prepare to return information for the new architecture.
165 /// Returns a pointer to the object file of the requested \a
166 /// arch and optional \a name. Returns nullptr of no such object
167 /// file exists in the container.
168 //------------------------------------------------------------------
169 virtual lldb::ObjectFileSP GetObjectFile(const FileSpec *file) = 0;
171 virtual bool ObjectAtIndexIsContainer(uint32_t object_idx) { return false; }
173 virtual ObjectFile *GetObjectFileAtIndex(uint32_t object_idx) {
177 virtual ObjectContainer *GetObjectContainerAtIndex(uint32_t object_idx) {
181 virtual const char *GetObjectNameAtIndex(uint32_t object_idx) const {
186 //------------------------------------------------------------------
188 //------------------------------------------------------------------
189 FileSpec m_file; ///< The file that represents this container objects (which
190 ///can be different from the module's file).
192 m_offset; ///< The offset in bytes into the file, or the address in memory
193 lldb::addr_t m_length; ///< The size in bytes if known (can be zero).
195 m_data; ///< The data for this object file so things can be parsed lazily.
198 DISALLOW_COPY_AND_ASSIGN(ObjectContainer);
201 } // namespace lldb_private
203 #endif // liblldb_ObjectContainer_h_