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

   1 //===-- ObjectContainer.h ---------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_ObjectContainer_h_
  11 #define liblldb_ObjectContainer_h_
  12
  13 // C Includes
  14 // C++ Includes
  15 // Other libraries and framework includes
  16 // Project 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"
  23
  24 namespace lldb_private {
  25
  26 //----------------------------------------------------------------------
  27 /// @class ObjectContainer ObjectContainer.h "lldb/Symbol/ObjectContainer.h"
  28 /// @brief A plug-in interface definition class for object containers.
  29 ///
  30 /// Object containers contain object files from one or more
  31 /// architectures, and also can contain one or more named objects.
  32 ///
  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 {
  38 public:
  39   //------------------------------------------------------------------
  40   /// Construct with a parent module, offset, and header data.
  41   ///
  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() {
  52     if (file)
  53       m_file = *file;
  54     if (data_sp)
  55       m_data.SetData(data_sp, data_offset, length);
  56   }
  57
  58   //------------------------------------------------------------------
  59   /// Destructor.
  60   ///
  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;
  65
  66   //------------------------------------------------------------------
  67   /// Dump a description of this object to a Stream.
  68   ///
  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.
  73   ///
  74   /// @param[in] s
  75   ///     The stream to which to dump the object description.
  76   //------------------------------------------------------------------
  77   virtual void Dump(Stream *s) const = 0;
  78
  79   //------------------------------------------------------------------
  80   /// Gets the architecture given an index.
  81   ///
  82   /// Copies the architecture specification for index \a idx.
  83   ///
  84   /// @param[in] idx
  85   ///     The architecture index to extract.
  86   ///
  87   /// @param[out] arch
  88   ///     A architecture object that will be filled in if \a idx is a
  89   ///     architecture valid index.
  90   ///
  91   /// @return
  92   ///     Returns \b true if \a idx is valid and \a arch has been
  93   ///     filled in, \b false otherwise.
  94   ///
  95   /// @see ObjectContainer::GetNumArchitectures() const
  96   //------------------------------------------------------------------
  97   virtual bool GetArchitectureAtIndex(uint32_t idx, ArchSpec &arch) const {
  98     return false;
  99   }
 100
 101   //------------------------------------------------------------------
 102   /// Returns the offset into a file at which this object resides.
 103   ///
 104   /// Some files contain many object files, and this function allows
 105   /// access to an object's offset within the file.
 106   ///
 107   /// @return
 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; }
 112
 113   virtual lldb::addr_t GetByteSize() const { return m_length; }
 114
 115   //------------------------------------------------------------------
 116   /// Get the number of objects within this object file (archives).
 117   ///
 118   /// @return
 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; }
 123
 124   //------------------------------------------------------------------
 125   /// Get the number of architectures in this object file.
 126   ///
 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.
 131   ///
 132   /// @return
 133   ///     The number of architectures contained in this object file.
 134   //------------------------------------------------------------------
 135   virtual size_t GetNumArchitectures() const { return 0; }
 136
 137   //------------------------------------------------------------------
 138   /// Attempts to parse the object header.
 139   ///
 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.
 145   ///
 146   /// @return
 147   ///     Returns \b true if the header was parsed successfully, \b
 148   ///     false otherwise.
 149   //------------------------------------------------------------------
 150   virtual bool ParseHeader() = 0;
 151
 152   //------------------------------------------------------------------
 153   /// Selects an architecture in an object file.
 154   ///
 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.
 158   ///
 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.
 163   ///
 164   /// @return
 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;
 170
 171   virtual bool ObjectAtIndexIsContainer(uint32_t object_idx) { return false; }
 172
 173   virtual ObjectFile *GetObjectFileAtIndex(uint32_t object_idx) {
 174     return nullptr;
 175   }
 176
 177   virtual ObjectContainer *GetObjectContainerAtIndex(uint32_t object_idx) {
 178     return nullptr;
 179   }
 180
 181   virtual const char *GetObjectNameAtIndex(uint32_t object_idx) const {
 182     return nullptr;
 183   }
 184
 185 protected:
 186   //------------------------------------------------------------------
 187   // Member variables.
 188   //------------------------------------------------------------------
 189   FileSpec m_file; ///< The file that represents this container objects (which
 190                    ///can be different from the module's file).
 191   lldb::addr_t
 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).
 194   DataExtractor
 195       m_data; ///< The data for this object file so things can be parsed lazily.
 196
 197 private:
 198   DISALLOW_COPY_AND_ASSIGN(ObjectContainer);
 199 };
 200
 201 } // namespace lldb_private
 202
 203 #endif // liblldb_ObjectContainer_h_