contrib/llvm/tools/lldb/include/lldb/Symbol/ObjectContainer.h

   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 liblldb_ObjectContainer_h_
  10 #define liblldb_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
  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.
  30 class ObjectContainer : public PluginInterface, public ModuleChild {
  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
 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
 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).
 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
 169 private:
 170   DISALLOW_COPY_AND_ASSIGN(ObjectContainer);
 171 };
 172
 173 } // namespace lldb_private
 174
 175 #endif // liblldb_ObjectContainer_h_