Warning: This file is not a C or C++ file. It does not have highlighting.

1//===-- ObjectContainer.h ---------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLDB_SYMBOL_OBJECTCONTAINER_H
10#define LLDB_SYMBOL_OBJECTCONTAINER_H
11
12#include "lldb/Core/ModuleChild.h"
13#include "lldb/Core/PluginInterface.h"
14#include "lldb/Utility/DataExtractor.h"
15#include "lldb/Utility/Endian.h"
16#include "lldb/Utility/FileSpec.h"
17#include "lldb/lldb-private.h"
18
19namespace lldb_private {
20
21/// \class ObjectContainer ObjectContainer.h "lldb/Symbol/ObjectContainer.h"
22/// A plug-in interface definition class for object containers.
23///
24/// Object containers contain object files from one or more architectures, and
25/// also can contain one or more named objects.
26///
27/// Typical object containers are static libraries (.a files) that contain
28/// multiple named object files, and universal files that contain multiple
29/// architectures.
30class ObjectContainer : public PluginInterface, public ModuleChild {
31public:
32 /// Construct with a parent module, offset, and header data.
33 ///
34 /// Object files belong to modules and a valid module must be supplied upon
35 /// construction. The at an offset within a file for objects that contain
36 /// more than one architecture or object.
37 ObjectContainer(const lldb::ModuleSP &module_sp, const FileSpec *file,
38 lldb::offset_t file_offset, lldb::offset_t length,
39 lldb::DataBufferSP &data_sp, lldb::offset_t data_offset)
40 : ModuleChild(module_sp),
41 m_file(), // This file can be different than the module's file spec
42 m_offset(file_offset), m_length(length) {
43 if (file)
44 m_file = *file;
45 if (data_sp)
46 m_data.SetData(data_sp, data_offset, length);
47 }
48
49 /// Destructor.
50 ///
51 /// The destructor is virtual since this class is designed to be inherited
52 /// from by the plug-in instance.
53 ~ObjectContainer() override = default;
54
55 /// Dump a description of this object to a Stream.
56 ///
57 /// Dump a description of the current contents of this object to the
58 /// supplied stream \a s. The dumping should include the section list if it
59 /// has been parsed, and the symbol table if it has been parsed.
60 ///
61 /// \param[in] s
62 /// The stream to which to dump the object description.
63 virtual void Dump(Stream *s) const = 0;
64
65 /// Gets the architecture given an index.
66 ///
67 /// Copies the architecture specification for index \a idx.
68 ///
69 /// \param[in] idx
70 /// The architecture index to extract.
71 ///
72 /// \param[out] arch
73 /// A architecture object that will be filled in if \a idx is a
74 /// architecture valid index.
75 ///
76 /// \return
77 /// Returns \b true if \a idx is valid and \a arch has been
78 /// filled in, \b false otherwise.
79 ///
80 /// \see ObjectContainer::GetNumArchitectures() const
81 virtual bool GetArchitectureAtIndex(uint32_t idx, ArchSpec &arch) const {
82 return false;
83 }
84
85 /// Returns the offset into a file at which this object resides.
86 ///
87 /// Some files contain many object files, and this function allows access to
88 /// an object's offset within the file.
89 ///
90 /// \return
91 /// The offset in bytes into the file. Defaults to zero for
92 /// simple object files that a represented by an entire file.
93 virtual lldb::addr_t GetOffset() const { return m_offset; }
94
95 virtual lldb::addr_t GetByteSize() const { return m_length; }
96
97 /// Get the number of objects within this object file (archives).
98 ///
99 /// \return
100 /// Zero for object files that are not archives, or the number
101 /// of objects contained in the archive.
102 virtual size_t GetNumObjects() const { return 0; }
103
104 /// Get the number of architectures in this object file.
105 ///
106 /// The default implementation returns 1 as for object files that contain a
107 /// single architecture. ObjectContainer instances that contain more than
108 /// one architecture should override this function and return an appropriate
109 /// value.
110 ///
111 /// \return
112 /// The number of architectures contained in this object file.
113 virtual size_t GetNumArchitectures() const { return 0; }
114
115 /// Attempts to parse the object header.
116 ///
117 /// This function is used as a test to see if a given plug-in instance can
118 /// parse the header data already contained in ObjectContainer::m_data. If
119 /// an object file parser does not recognize that magic bytes in a header,
120 /// false should be returned and the next plug-in can attempt to parse an
121 /// object file.
122 ///
123 /// \return
124 /// Returns \b true if the header was parsed successfully, \b
125 /// false otherwise.
126 virtual bool ParseHeader() = 0;
127
128 /// Selects an architecture in an object file.
129 ///
130 /// Object files that contain a single architecture should verify that the
131 /// specified \a arch matches the architecture in in object file and return
132 /// \b true or \b false accordingly.
133 ///
134 /// Object files that contain more than one architecture should attempt to
135 /// select that architecture, and if successful, clear out any previous
136 /// state from any previously selected architecture and prepare to return
137 /// information for the new architecture.
138 ///
139 /// \return
140 /// Returns a pointer to the object file of the requested \a
141 /// arch and optional \a name. Returns nullptr of no such object
142 /// file exists in the container.
143 virtual lldb::ObjectFileSP GetObjectFile(const FileSpec *file) = 0;
144
145 virtual bool ObjectAtIndexIsContainer(uint32_t object_idx) { return false; }
146
147 virtual ObjectFile *GetObjectFileAtIndex(uint32_t object_idx) {
148 return nullptr;
149 }
150
151 virtual ObjectContainer *GetObjectContainerAtIndex(uint32_t object_idx) {
152 return nullptr;
153 }
154
155 virtual const char *GetObjectNameAtIndex(uint32_t object_idx) const {
156 return nullptr;
157 }
158
159protected:
160 // Member variables.
161 FileSpec m_file; ///< The file that represents this container objects (which
162 ///can be different from the module's file).
163 lldb::addr_t
164 m_offset; ///< The offset in bytes into the file, or the address in memory
165 lldb::addr_t m_length; ///< The size in bytes if known (can be zero).
166 DataExtractor
167 m_data; ///< The data for this object file so things can be parsed lazily.
168
169private:
170 ObjectContainer(const ObjectContainer &) = delete;
171 const ObjectContainer &operator=(const ObjectContainer &) = delete;
172};
173
174} // namespace lldb_private
175
176#endif // LLDB_SYMBOL_OBJECTCONTAINER_H
177

Warning: This file is not a C or C++ file. It does not have highlighting.

source code of lldb/include/lldb/Symbol/ObjectContainer.h