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
  18 #include "lldb/lldb-private.h"
  19 #include "lldb/Core/DataExtractor.h"
  20 #include "lldb/Host/FileSpec.h"
  21 #include "lldb/Core/ModuleChild.h"
  22 #include "lldb/Core/PluginInterface.h"
  23 #include "lldb/Host/Endian.h"
  24
  25 namespace lldb_private {
  26
  27 //----------------------------------------------------------------------
  28 /// @class ObjectContainer ObjectContainer.h "lldb/Symbol/ObjectContainer.h"
  29 /// @brief A plug-in interface definition class for object containers.
  30 ///
  31 /// Object containers contain object files from one or more
  32 /// architectures, and also can contain one or more named objects.
  33 ///
  34 /// Typical object containers are static libraries (.a files) that
  35 /// contain multiple named object files, and universal files that contain
  36 /// multiple architectures.
  37 //----------------------------------------------------------------------
  38 class ObjectContainer :
  39     public PluginInterface,
  40     public ModuleChild
  41 {
  42 public:
  43     //------------------------------------------------------------------
  44     /// Construct with a parent module, offset, and header data.
  45     ///
  46     /// Object files belong to modules and a valid module must be
  47     /// supplied upon construction. The at an offset within a file for
  48     /// objects that contain more than one architecture or object.
  49     //------------------------------------------------------------------
  50     ObjectContainer (const lldb::ModuleSP &module_sp,
  51                      const FileSpec *file,
  52                      lldb::offset_t file_offset,
  53                      lldb::offset_t length,
  54                      lldb::DataBufferSP& data_sp,
  55                      lldb::offset_t data_offset) :
  56         ModuleChild (module_sp),
  57         m_file (),  // This file can be different than the module's file spec
  58         m_offset (file_offset),
  59         m_length (length),
  60         m_data ()
  61     {
  62         if (file)
  63             m_file = *file;
  64         if (data_sp)
  65             m_data.SetData (data_sp, data_offset, length);
  66     }
  67
  68     //------------------------------------------------------------------
  69     /// Destructor.
  70     ///
  71     /// The destructor is virtual since this class is designed to be
  72     /// inherited from by the plug-in instance.
  73     //------------------------------------------------------------------
  74     virtual
  75     ~ObjectContainer()
  76     {
  77     }
  78
  79     //------------------------------------------------------------------
  80     /// Dump a description of this object to a Stream.
  81     ///
  82     /// Dump a description of the current contents of this object
  83     /// to the supplied stream \a s. The dumping should include the
  84     /// section list if it has been parsed, and the symbol table
  85     /// if it has been parsed.
  86     ///
  87     /// @param[in] s
  88     ///     The stream to which to dump the object descripton.
  89     //------------------------------------------------------------------
  90     virtual void
  91     Dump (Stream *s) const = 0;
  92
  93     //------------------------------------------------------------------
  94     /// Gets the architecture given an index.
  95     ///
  96     /// Copies the architecture specification for index \a idx.
  97     ///
  98     /// @param[in] idx
  99     ///     The architecture index to extract.
 100     ///
 101     /// @param[out] arch
 102     ///     A architecture object that will be filled in if \a idx is a
 103     ///     architecture valid index.
 104     ///
 105     /// @return
 106     ///     Returns \b true if \a idx is valid and \a arch has been
 107     ///     filled in, \b false otherwise.
 108     ///
 109     /// @see ObjectContainer::GetNumArchitectures() const
 110     //------------------------------------------------------------------
 111     virtual bool
 112     GetArchitectureAtIndex (uint32_t idx, ArchSpec& arch) const
 113     {
 114         return false;
 115     }
 116
 117     //------------------------------------------------------------------
 118     /// Returns the offset into a file at which this object resides.
 119     ///
 120     /// Some files contain many object files, and this function allows
 121     /// access to an object's offset within the file.
 122     ///
 123     /// @return
 124     ///     The offset in bytes into the file. Defaults to zero for
 125     ///     simple object files that a represented by an entire file.
 126     //------------------------------------------------------------------
 127     virtual lldb::addr_t
 128     GetOffset () const
 129     { return m_offset; }
 130
 131     virtual lldb::addr_t
 132     GetByteSize () const
 133     { return m_length; }
 134
 135     //------------------------------------------------------------------
 136     /// Get the number of objects within this object file (archives).
 137     ///
 138     /// @return
 139     ///     Zero for object files that are not archives, or the number
 140     ///     of objects contained in the archive.
 141     //------------------------------------------------------------------
 142     virtual size_t
 143     GetNumObjects () const
 144     { return 0; }
 145
 146     //------------------------------------------------------------------
 147     /// Get the number of architectures in this object file.
 148     ///
 149     /// The default implementation returns 1 as for object files that
 150     /// contain a single architecture. ObjectContainer instances that
 151     /// contain more than one architecture should override this function
 152     /// and return an appropriate value.
 153     ///
 154     /// @return
 155     ///     The number of architectures contained in this object file.
 156     //------------------------------------------------------------------
 157     virtual size_t
 158     GetNumArchitectures () const
 159     { return 0; }
 160
 161     //------------------------------------------------------------------
 162     /// Attempts to parse the object header.
 163     ///
 164     /// This function is used as a test to see if a given plug-in
 165     /// instance can parse the header data already contained in
 166     /// ObjectContainer::m_data. If an object file parser does not
 167     /// recognize that magic bytes in a header, false should be returned
 168     /// and the next plug-in can attempt to parse an object file.
 169     ///
 170     /// @return
 171     ///     Returns \b true if the header was parsed succesfully, \b
 172     ///     false otherwise.
 173     //------------------------------------------------------------------
 174     virtual bool
 175     ParseHeader () = 0;
 176
 177     //------------------------------------------------------------------
 178     /// Selects an architecture in an object file.
 179     ///
 180     /// Object files that contain a single architecture should verify
 181     /// that the specified \a arch matches the architecture in in
 182     /// object file and return \b true or \b false accordingly.
 183     ///
 184     /// Object files that contain more than one architecture should
 185     /// attempt to select that architecture, and if successful, clear
 186     /// out any previous state from any previously selected architecture
 187     /// and prepare to return information for the new architecture.
 188     ///
 189     /// @return
 190     ///     Returns a pointer to the object file of the requested \a
 191     ///     arch and optional \a name. Returns NULL of no such object
 192     ///     file exists in the container.
 193     //------------------------------------------------------------------
 194     virtual lldb::ObjectFileSP
 195     GetObjectFile (const FileSpec *file) = 0;
 196
 197     virtual bool
 198     ObjectAtIndexIsContainer (uint32_t object_idx)
 199     {
 200         return false;
 201     }
 202
 203     virtual ObjectFile *
 204     GetObjectFileAtIndex (uint32_t object_idx)
 205     {
 206         return NULL;
 207     }
 208
 209     virtual ObjectContainer *
 210     GetObjectContainerAtIndex (uint32_t object_idx)
 211     {
 212         return NULL;
 213     }
 214
 215     virtual const char *
 216     GetObjectNameAtIndex (uint32_t object_idx) const
 217     {
 218         return NULL;
 219     }
 220
 221 protected:
 222     //------------------------------------------------------------------
 223     // Member variables.
 224     //------------------------------------------------------------------
 225     FileSpec m_file; ///< The file that represents this container objects (which can be different from the module's file).
 226     lldb::addr_t m_offset; ///< The offset in bytes into the file, or the address in memory
 227     lldb::addr_t m_length; ///< The size in bytes if known (can be zero).
 228     DataExtractor m_data; ///< The data for this object file so things can be parsed lazily.
 229
 230 private:
 231     DISALLOW_COPY_AND_ASSIGN (ObjectContainer);
 232 };
 233
 234 } // namespace lldb_private
 235
 236 #endif  // liblldb_ObjectContainer_h_