/*
* 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_
/*!
* \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.
};
//! \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 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 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 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);
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);
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.
};
