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