dist/common/DataSource.h

/*
 * File:	DataSource.h
 *
 * Copyright (c) Freescale Semiconductor, Inc. All rights reserved.
 * See included license file for license details.
 */
#if !defined(_DataSource_h_)
#define _DataSource_h_

#include <vector>
#include "Value.h"
#include "smart_ptr.h"
#include "StExecutableImage.h"

namespace elftosb
{

// Forward declaration
class DataTarget;

/*!
 * \brief Abstract base class for data sources.
 *
 * Data sources represent any sort of data that can be placed or loaded
 * into a target region. Sources may be a single blob of data read from
 * a file or may consist of many segments.
 *
 * The three most important features of data sources are:
 * - Sources may be multi-segmented.
 * - Sources and/or segments can have a "natural" or default target location.
 * - The target for a source may be taken into consideration when the source
 *		describes itself.
 */
class DataSource
{
public:
	/*!
	 * \brief Discrete, contiguous part of the source's data.
	 *
	 * This class is purely abstract and subclasses of DataSource are expected
	 * to subclass it to implement a segment particular to their needs.
	 */
	class Segment
	{
	public:
		//! \brief Default constructor.
		Segment(DataSource & source) : m_source(source) {}

		//! \brief Destructor.
		virtual ~Segment() {}

		//! \brief Gets all or a portion of the segment's data.
		//!
		//! The data is copied into \a buffer. Up to \a maxBytes bytes may be
		//! copied, so \a buffer must be at least that large.
		//!
		//! \param offset Index of the first byte to start copying from.
		//! \param maxBytes The maximum number of bytes that can be returned. \a buffer
		//!		must be at least this large.
		//! \param buffer Pointer to buffer where the data is copied.
		//! \return The number of bytes copied into \a buffer.
		virtual unsigned getData(unsigned offset, unsigned maxBytes, uint8_t * buffer)=0;

		//! \brief Gets the length of the segment's data.
		virtual unsigned getLength()=0;

		//! \brief Returns whether the segment has an associated address.
		virtual bool hasNaturalLocation()=0;

		//! \brief Returns the address associated with the segment.
		virtual uint32_t getBaseAddress() { return 0; }

	protected:
		DataSource & m_source;	//!< The data source to which this segment belongs.
	};

	/*!
	 * \brief This is a special type of segment containing a repeating pattern.
	 *
	 * By default the segment doesn't have a specific length or data. The length depends
	 * on the target's address range. And the data is just the pattern, repeated
	 * many times. In addition, pattern segments do not have a natural location.
	 *
	 * Calling code should look for instances of PatternSegment and handle them
	 * as special cases that can be optimized.
	 */
	class PatternSegment : public Segment
	{
	public:
		//! \brief Default constructor.
		PatternSegment(DataSource & source);

		//! \brief Constructor taking a fill pattern.
		PatternSegment(DataSource & source, const SizedIntegerValue & pattern);

		//! \brief Constructor taking a byte fill pattern.
		PatternSegment(DataSource & source, uint8_t pattern);

		//! \brief Constructor taking a half-word fill pattern.
		PatternSegment(DataSource & source, uint16_t pattern);

		//! \brief Constructor taking a word fill pattern.
		PatternSegment(DataSource & source, uint32_t pattern);

		//! \name Segment methods
		//@{
		//! \brief Pattern segments have no natural address.
		virtual bool hasNaturalLocation() { return false; }

		//! \brief Performs a pattern fill into the \a buffer.
		virtual unsigned getData(unsigned offset, unsigned maxBytes, uint8_t * buffer);

		//! \brief Returns a length based on the data target's address range.
		virtual unsigned getLength();
		//@}

		//! \name Pattern accessors
		//@{
		//! \brief Assigns a new fill pattern.
		inline void setPattern(const SizedIntegerValue & newPattern) { m_pattern = newPattern; }

		//! \brief Return the fill pattern for the segment.
		inline SizedIntegerValue & getPattern() { return m_pattern; }

		//! \brief Assignment operator, sets the pattern value and length.
		PatternSegment & operator = (const SizedIntegerValue & value) { m_pattern = value; return *this; }
		//@}

	protected:
		SizedIntegerValue m_pattern;	//!< The fill pattern.
	};

public:
	//! \brief Default constructor.
	DataSource() : m_target(0) {}

	//! \brief Destructor.
	virtual ~DataSource() {}

	//! \name Data target
	//@{
	//! \brief Sets the associated data target.
	inline void setTarget(DataTarget * target) { m_target = target; }

	//! \brief Gets the associated data target.
	inline DataTarget * getTarget() const { return m_target; }
	//@}

	//! \name Segments
	//@{
	//! \brief Returns the number of segments in this data source.
	virtual unsigned getSegmentCount()=0;

	//! \brief Returns segment number \a index of the data source.
	virtual Segment * getSegmentAt(unsigned index)=0;
	//@}

protected:
	DataTarget * m_target;	//!< Corresponding target for this source.
};

/*!
 * \brief Data source for a repeating pattern.
 *
 * The pattern is represented by a SizedIntegerValue object. Thus the pattern
 * can be either byte, half-word, or word sized.
 *
 * This data source has only one segment, and the PatternSource instance acts
 * as its own single segment.
 */
class PatternSource : public DataSource, public DataSource::PatternSegment
{
public:
	//! \brief Default constructor.
	PatternSource();

	//! \brief Constructor taking the pattern value.
	PatternSource(const SizedIntegerValue & value);

	//! \brief There is only one segment.
	virtual unsigned getSegmentCount() { return 1; }

	//! \brief Returns this object, as it is its own segment.
	virtual DataSource::Segment * getSegmentAt(unsigned index) { return this; }

	//! \brief Assignment operator, sets the pattern value and length.
	PatternSource & operator = (const SizedIntegerValue & value) { setPattern(value); return *this; }
};

/*!
 * \brief Data source for data that is not memory mapped (has no natural address).
 *
 * This data source can only manage a single block of data, which has no
 * associated address. It acts as its own Segment.
 */
class UnmappedDataSource : public DataSource, public DataSource::Segment
{
public:
	//! \brief Default constructor.
	UnmappedDataSource();

	//! \brief Constructor taking the data, which is copied.
	UnmappedDataSource(const uint8_t * data, unsigned length);

	//! \brief Sets the source's data.
	void setData(const uint8_t * data, unsigned length);

	//! \brief There is only one segment.
	virtual unsigned getSegmentCount() { return 1; }

	//! \brief Returns this object, as it is its own segment.
	virtual DataSource::Segment * getSegmentAt(unsigned index) { return this; }

	//! \name Segment methods
	//@{
	//! \brief Unmapped data sources have no natural address.
	virtual bool hasNaturalLocation() { return false; }

	//! \brief Copies a portion of the data into \a buffer.
	virtual unsigned getData(unsigned offset, unsigned maxBytes, uint8_t * buffer);

	//! \brief Returns the number of bytes of data managed by the source.
	virtual unsigned getLength() { return m_length; }
	//@}

protected:
	smart_array_ptr<uint8_t> m_data;	//!< The data.
	unsigned m_length;	//!< Byte count of the data.
};

/*!
 * \brief Data source that takes its data from an executable image.
 *
 * \see StExecutableImage
 */
class MemoryImageDataSource : public DataSource
{
public:
	//! \brief Default constructor.
	MemoryImageDataSource(StExecutableImage * image);

	//! \brief Destructor.
	virtual ~MemoryImageDataSource();

	//! \brief Returns the number of memory regions in the image.
	virtual unsigned getSegmentCount();

	//! \brief Returns the data source segment at position \a index.
	virtual DataSource::Segment * getSegmentAt(unsigned index);

protected:
	/*!
	 * \brief Segment corresponding to a text region of the executable image.
	 */
	class TextSegment : public DataSource::Segment
	{
	public:
		//! \brief Default constructor
		TextSegment(MemoryImageDataSource & source, StExecutableImage * image, unsigned index);

		virtual unsigned getData(unsigned offset, unsigned maxBytes, uint8_t * buffer);
		virtual unsigned getLength();

		virtual bool hasNaturalLocation() { return true; }
		virtual uint32_t getBaseAddress();

	protected:
		StExecutableImage * m_image;	//!< Coalesced image of the file.
		unsigned m_index;	//!< Record index.
	};

	/*!
	 * \brief Segment corresponding to a fill region of the executable image.
	 */
	class FillSegment : public DataSource::PatternSegment
	{
	public:
		FillSegment(MemoryImageDataSource & source, StExecutableImage * image, unsigned index);

		virtual unsigned getLength();

		virtual bool hasNaturalLocation() { return true; }
		virtual uint32_t getBaseAddress();

	protected:
		StExecutableImage * m_image;	//!< Coalesced image of the file.
		unsigned m_index;	//!< Record index.
	};

protected:
	StExecutableImage * m_image;	//!< The memory image that is the data source.

	typedef std::vector<DataSource::Segment*> segment_array_t;	//!< An array of segments.
	segment_array_t m_segments;	//!< The array of Segment instances.
};

}; // namespace elftosb

#endif // _DataSource_h_