Candidate release of source code.

Ghidra/Features/Decompiler/src/decompile/cpp/loadimage.hh

@@ -0,0 +1,227 @@
+/* ###
+ * IP: GHIDRA
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/// \file loadimage.hh
+/// \brief Classes and API for accessing a binary load image
+
+#ifndef __CPUI_LOADIMAGE__
+#define __CPUI_LOADIMAGE__
+
+#include "address.hh"
+
+/// \brief Exception indicating data was not available
+///
+/// This exception is thrown when a request for load image
+/// data cannot be met, usually because the requested address
+/// range is not in the image.
+struct DataUnavailError : public LowlevelError {
+  DataUnavailError(const string &s) : LowlevelError(s) {} ///< Instantiate with an explanatory string
+};
+
+/// \brief A record indicating a function symbol
+///
+/// This is a lightweight object holding the Address and name of a function
+struct LoadImageFunc {
+  Address address;	///< Start of function
+  string name;		///< Name of function
+};
+
+/// \brief A record describing a section bytes in the executable
+///
+/// A lightweight object specifying the location and size of the section and basic properties
+struct LoadImageSection {
+  /// Boolean properties a section might have
+  enum {
+    unalloc = 1,		///< Not allocated in memory (debug info)
+    noload = 2,			///< uninitialized section
+    code = 4,			///< code only
+    data = 8,			///< data only
+    readonly = 16		///< read only section
+  };
+  Address address;		///< Starting address of section
+  uintb size;			///< Number of bytes in section
+  uint4 flags;			///< Properties of the section
+};
+
+/// \brief An interface into a particular binary executable image
+///
+/// This class provides the abstraction needed by the decompiler
+/// for the numerous load file formats used to encode binary
+/// executables.  The data encoding the machine instructions
+/// for the executable can be accessed via the addresses where
+/// that data would be loaded into RAM.
+/// Properties other than the main data and instructions of the
+/// binary are not supposed to repeatedly queried through this
+/// interface. This information is intended to be read from
+/// this class exactly once, during initialization, and used to
+/// populate the main decompiler database. This class currently
+/// has only rudimentary support for accessing such properties.
+class LoadImage {
+protected:
+  string filename;		///< Name of the loadimage
+public:
+  LoadImage(const string &f);	///< LoadImage constructor
+  virtual ~LoadImage(void);	///< LoadImage destructor
+  const string &getFileName(void) const; ///< Get the name of the LoadImage
+  virtual void loadFill(uint1 *ptr,int4 size,const Address &addr)=0; ///< Get data from the LoadImage
+  virtual void openSymbols(void) const; ///< Prepare to read symbols
+  virtual void closeSymbols(void) const; ///< Stop reading symbols
+  virtual bool getNextSymbol(LoadImageFunc &record) const; ///< Get the next symbol record
+  virtual void openSectionInfo(void) const; ///< Prepare to read section info
+  virtual void closeSectionInfo(void) const; ///< Stop reading section info
+  virtual bool getNextSection(LoadImageSection &sec) const; ///< Get info on the next section
+  virtual void getReadonly(RangeList &list) const; ///< Return list of \e readonly address ranges
+  virtual string getArchType(void) const=0; ///< Get a string indicating the architecture type
+  virtual void adjustVma(long adjust)=0; ///< Adjust load addresses with a global offset
+  uint1 *load(int4 size,const Address &addr);	///< Load a chunk of image
+};
+
+/// \brief A simple raw binary loadimage
+///
+/// This is probably the simplest loadimage.  Bytes from the image are read directly from a file stream.
+/// The address associated with each byte is determined by a single value, the vma, which is the address
+/// of the first byte in the file.  No symbols or sections are supported
+class RawLoadImage : public LoadImage {
+  uintb vma;			///< Address of first byte in the file
+  ifstream *thefile;		///< Main file stream for image
+  uintb filesize;		///< Total number of bytes in the loadimage/file
+  AddrSpace *spaceid;		///< Address space that the file bytes are mapped to
+public:
+  RawLoadImage(const string &f); ///< RawLoadImage constructor
+  void attachToSpace(AddrSpace *id) { spaceid = id; }	///< Attach the raw image to a particular space
+  void open(void);					///< Open the raw file for reading
+  virtual ~RawLoadImage(void);				///< RawLoadImage destructor
+  virtual void loadFill(uint1 *ptr,int4 size,const Address &addr);
+  virtual string getArchType(void) const;
+  virtual void adjustVma(long adjust);
+};
+
+/// For the base class there is no relevant initialization except
+/// the name of the image.
+/// \param f is the name of the image
+inline LoadImage::LoadImage(const string &f) {
+  filename = f;
+}
+
+/// The destructor for the load image object.
+inline LoadImage::~LoadImage(void) {
+}
+
+/// The loadimage is usually associated with a file. This routine
+/// retrieves the name as a string.
+/// \return the name of the image
+inline const string &LoadImage::getFileName(void) const {
+  return filename;
+}
+
+/// This routine should read in and parse any symbol information
+/// that the load image contains about executable.  Once this
+/// method is called, individual symbol records are read out
+/// using the getNextSymbol() method.
+inline void LoadImage::openSymbols(void) const {
+}
+
+/// Once all the symbol information has been read out from the
+/// load image via the openSymbols() and getNextSymbol() calls,
+/// the application should call this method to free up resources
+/// used in parsing the symbol information.
+inline void LoadImage::closeSymbols(void) const {
+}
+
+/// This method is used to read out an individual symbol record,
+/// LoadImageFunc, from the load image.  Right now, the only
+/// information that can be read out are function starts and the
+/// associated function name.  This method can be called repeatedly
+/// to iterate through all the symbols, until it returns \b false.
+/// This indicates the end of the symbols.
+/// \param record is a reference to the symbol record to be filled in
+/// \return \b true if there are more records to read
+inline bool LoadImage::getNextSymbol(LoadImageFunc &record) const {
+  return false;
+}
+
+/// This method initializes iteration over all the sections of
+/// bytes that are mapped by the load image.  Once this is called,
+/// information on individual sections should be read out with
+/// the getNextSection() method.
+inline void LoadImage::openSectionInfo(void) const {
+}
+
+/// Once all the section information is read from the load image
+/// using the getNextSection() method, this method should be
+/// called to free up any resources used in parsing the section info.
+inline void LoadImage::closeSectionInfo(void) const {
+}
+
+/// This method is used to read out a record that describes a
+/// single section of bytes mapped by the load image. This
+/// method can be called repeatedly until it returns \b false,
+/// to get info on additional sections.
+/// \param record is a reference to the info record to be filled in
+/// \return \b true if there are more records to read
+inline bool LoadImage::getNextSection(LoadImageSection &record) const {
+  return false;
+}
+
+/// This method should read out information about \e all
+/// address ranges within the load image that are known to be
+/// \b readonly.  This method is intended to be called only
+/// once, so all information should be written to the passed
+/// RangeList object.
+/// \param list is where readonly info will get put
+inline void LoadImage::getReadonly(RangeList &list) const {
+}
+
+/// \fn void LoadImage::adjustVma(long adjust)
+/// Most load image formats automatically encode information
+/// about the true loading address(es) for the data in the image.
+/// But if this is missing or incorrect, this routine can be
+/// used to make a global adjustment to the load address. Only
+/// one adjustment is made across \e all addresses in the image.
+/// The offset passed to this method is added to the stored
+/// or default value for any address queried in the image.
+/// This is most often used in a \e raw binary file format.  In
+/// this case, the entire executable file is intended to be
+/// read straight into RAM, as one contiguous chunk, in order to
+/// be executed.  In the absence of any other info, the first
+/// byte of the image file is loaded at offset 0. This method
+/// then would adjust the load address of the first byte.
+/// \param adjust is the offset amount to be added to default values
+
+/// \fn string LoadImage::getArchType(void) const
+/// The load image class is intended to be a generic front-end
+/// to the large variety of load formats in use.  This method
+/// should return a string that identifies the particular
+/// architecture this particular image is intended to run on.
+/// It is currently the responsibility of any derived LoadImage
+/// class to establish a format for this string, but it should
+/// generally contain some indication of the operating system
+/// and the processor.
+/// \return the identifier string
+
+/// \fn void LoadImage::loadFill(uint1 *ptr,int4 size,const Address &addr)
+/// This is the \e core routine of a LoadImage.  Given a particular
+/// address range, this routine retrieves the exact byte values
+/// that are stored at that address when the executable is loaded
+/// into RAM.  The caller must supply a pre-allocated array
+/// of bytes where the returned bytes should be stored.  If the
+/// requested address range does not exist in the image, or
+/// otherwise can't be retrieved, this method throws an
+/// DataUnavailError exception.
+/// \param ptr points to where the resulting bytes will be stored
+/// \param size is the number of bytes to retrieve from the image
+/// \param addr is the starting address of the bytes to retrieve
+
+#endif