LLDB  mainline
ObjectContainer.h
Go to the documentation of this file.
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"
15 #include "lldb/Utility/Endian.h"
16 #include "lldb/Utility/FileSpec.h"
17 #include "lldb/lldb-private.h"
18 
19 namespace 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.
31 public:
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), m_data() {
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 
152  return nullptr;
153  }
154 
155  virtual const char *GetObjectNameAtIndex(uint32_t object_idx) const {
156  return nullptr;
157  }
158 
159 protected:
160  // Member variables.
161  FileSpec m_file; ///< The file that represents this container objects (which
162  ///can be different from the module's file).
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).
167  m_data; ///< The data for this object file so things can be parsed lazily.
168 
169 private:
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
lldb_private::ObjectContainer::GetByteSize
virtual lldb::addr_t GetByteSize() const
Definition: ObjectContainer.h:95
lldb_private::ArchSpec
Definition: ArchSpec.h:33
lldb_private::ModuleChild
Definition: ModuleChild.h:19
lldb_private::ObjectContainer::Dump
virtual void Dump(Stream *s) const =0
Dump a description of this object to a Stream.
lldb_private::ObjectContainer::GetObjectFileAtIndex
virtual ObjectFile * GetObjectFileAtIndex(uint32_t object_idx)
Definition: ObjectContainer.h:147
lldb_private::PluginInterface
Definition: PluginInterface.h:16
lldb_private::ObjectContainer
Definition: ObjectContainer.h:30
lldb::offset_t
uint64_t offset_t
Definition: lldb-types.h:87
lldb_private::ObjectContainer::m_data
DataExtractor m_data
The data for this object file so things can be parsed lazily.
Definition: ObjectContainer.h:167
lldb_private::Stream
Definition: Stream.h:28
lldb::addr_t
uint64_t addr_t
Definition: lldb-types.h:83
lldb_private::ObjectContainer::GetNumArchitectures
virtual size_t GetNumArchitectures() const
Get the number of architectures in this object file.
Definition: ObjectContainer.h:113
lldb_private::ObjectContainer::GetObjectFile
virtual lldb::ObjectFileSP GetObjectFile(const FileSpec *file)=0
Selects an architecture in an object file.
lldb_private::DataExtractor::SetData
lldb::offset_t SetData(const void *bytes, lldb::offset_t length, lldb::ByteOrder byte_order)
Set data with a buffer that is caller owned.
Definition: DataExtractor.cpp:225
lldb_private::FileSpec
Definition: FileSpec.h:56
lldb_private::DataExtractor
Definition: DataExtractor.h:48
lldb_private::ObjectContainer::m_offset
lldb::addr_t m_offset
The offset in bytes into the file, or the address in memory.
Definition: ObjectContainer.h:164
lldb_private::ObjectContainer::GetObjectContainerAtIndex
virtual ObjectContainer * GetObjectContainerAtIndex(uint32_t object_idx)
Definition: ObjectContainer.h:151
lldb_private::ObjectContainer::GetObjectNameAtIndex
virtual const char * GetObjectNameAtIndex(uint32_t object_idx) const
Definition: ObjectContainer.h:155
PluginInterface.h
lldb_private::ObjectContainer::operator=
const ObjectContainer & operator=(const ObjectContainer &)=delete
lldb_private::ObjectContainer::m_file
FileSpec m_file
The file that represents this container objects (which can be different from the module's file).
Definition: ObjectContainer.h:161
lldb_private::ObjectContainer::GetArchitectureAtIndex
virtual bool GetArchitectureAtIndex(uint32_t idx, ArchSpec &arch) const
Gets the architecture given an index.
Definition: ObjectContainer.h:81
lldb-private.h
lldb_private::ObjectContainer::ParseHeader
virtual bool ParseHeader()=0
Attempts to parse the object header.
uint32_t
ModuleChild.h
lldb_private::ObjectContainer::~ObjectContainer
~ObjectContainer() override=default
Destructor.
DataExtractor.h
lldb_private::ObjectContainer::ObjectAtIndexIsContainer
virtual bool ObjectAtIndexIsContainer(uint32_t object_idx)
Definition: ObjectContainer.h:145
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::ObjectContainer::GetOffset
virtual lldb::addr_t GetOffset() const
Returns the offset into a file at which this object resides.
Definition: ObjectContainer.h:93
FileSpec.h
lldb_private::ObjectContainer::m_length
lldb::addr_t m_length
The size in bytes if known (can be zero).
Definition: ObjectContainer.h:165
lldb_private::ObjectContainer::GetNumObjects
virtual size_t GetNumObjects() const
Get the number of objects within this object file (archives).
Definition: ObjectContainer.h:102
Endian.h
lldb_private::ObjectFile
Definition: ObjectFile.h:58
lldb_private::ObjectContainer::ObjectContainer
ObjectContainer(const lldb::ModuleSP &module_sp, const FileSpec *file, lldb::offset_t file_offset, lldb::offset_t length, lldb::DataBufferSP &data_sp, lldb::offset_t data_offset)
Construct with a parent module, offset, and header data.
Definition: ObjectContainer.h:37