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" 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. 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)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 GetArchitectureAtIndex(uint32_t idx,ArchSpec & arch)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. GetOffset()93 virtual lldb::addr_t GetOffset() const { return m_offset; } 94 GetByteSize()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. GetNumObjects()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. GetNumArchitectures()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 ObjectAtIndexIsContainer(uint32_t object_idx)145 virtual bool ObjectAtIndexIsContainer(uint32_t object_idx) { return false; } 146 GetObjectFileAtIndex(uint32_t object_idx)147 virtual ObjectFile *GetObjectFileAtIndex(uint32_t object_idx) { 148 return nullptr; 149 } 150 GetObjectContainerAtIndex(uint32_t object_idx)151 virtual ObjectContainer *GetObjectContainerAtIndex(uint32_t object_idx) { 152 return nullptr; 153 } 154 GetObjectNameAtIndex(uint32_t object_idx)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 ObjectContainer(const ObjectContainer &) = delete; 171 const ObjectContainer &operator=(const ObjectContainer &) = delete; 172 }; 173 174 } // namespace lldb_private 175 176 #endif // LLDB_SYMBOL_OBJECTCONTAINER_H 177