Used to build a representation of memory regions. More...

#include <StExecutableImage.h>

Collaboration diagram for StExecutableImage:

Classes
class	address_filter_exception

struct	AddressFilter

struct	MemoryRegion

Public Types
enum	MemoryRegionType { TEXT_REGION, FILL_REGION, TEXT_REGION, FILL_REGION }
	Possible types of memory regions. More...

enum	{ REGION_READ_FLAG = 1, REGION_WRITE_FLAG = 2, REGION_EXEC_FLAG = 4, REGION_RW_FLAG = REGION_READ_FLAG \| REGION_WRITE_FLAG, REGION_PERM_FLAG_MASK = 0x7 }
	Memory region flag constants. More...

enum	AddressFilterAction { ADDR_FILTER_NONE, ADDR_FILTER_ERROR, ADDR_FILTER_WARNING, ADDR_FILTER_CROP, ADDR_FILTER_NONE, ADDR_FILTER_ERROR, ADDR_FILTER_WARNING, ADDR_FILTER_CROP }
	The possible actions for regions matching an address filter range. More...

enum	MemoryRegionType { TEXT_REGION, FILL_REGION, TEXT_REGION, FILL_REGION }
	Possible types of memory regions. More...

enum	{ REGION_READ_FLAG = 1, REGION_WRITE_FLAG = 2, REGION_EXEC_FLAG = 4, REGION_RW_FLAG = REGION_READ_FLAG \| REGION_WRITE_FLAG, REGION_PERM_FLAG_MASK = 0x7 }
	Memory region flag constants. More...

enum	AddressFilterAction { ADDR_FILTER_NONE, ADDR_FILTER_ERROR, ADDR_FILTER_WARNING, ADDR_FILTER_CROP, ADDR_FILTER_NONE, ADDR_FILTER_ERROR, ADDR_FILTER_WARNING, ADDR_FILTER_CROP }
	The possible actions for regions matching an address filter range. More...

typedef std::list< MemoryRegion >	MemoryRegionList
	A list of StExecutableImage::MemoryRegion objects.

typedef MemoryRegionList::const_iterator	const_iterator

typedef std::list< AddressFilter >	AddressFilterList
	List of StExecutableImage::AddressFilter objects.

typedef std::list< MemoryRegion >	MemoryRegionList
	A list of StExecutableImage::MemoryRegion objects.

typedef MemoryRegionList::const_iterator	const_iterator

typedef std::list< AddressFilter >	AddressFilterList
	List of StExecutableImage::AddressFilter objects.

Public Member Functions
	StExecutableImage (int inAlignment=256)
	Constructor.

	StExecutableImage (const StExecutableImage &inOther)
	Copy constructor. More...

virtual	~StExecutableImage ()
	Destructor. More...

	StExecutableImage (int inAlignment=256)
	Constructor.

	StExecutableImage (const StExecutableImage &inOther)
	Copy constructor.

virtual	~StExecutableImage ()
	Destructor.

Image name
Methods for getting and setting the image name.
virtual void	setName (const std::string &inName)
	Sets the image's name to inName. More...

virtual std::string	getName () const
	Returns a copy of the image's name.

virtual void	setName (const std::string &inName)
	Sets the image's name to inName.

virtual std::string	getName () const
	Returns a copy of the image's name.

Regions
Methods to add and access memory regions.
virtual void	addFillRegion (uint32_t inAddress, unsigned inLength)
	Add a region to be filled with zeroes. More...

virtual void	addTextRegion (uint32_t inAddress, const uint8_t *inData, unsigned inLength)
	Add a region containing data to be loaded. More...

unsigned	getRegionCount () const
	Returns the total number of regions. More...

const MemoryRegion &	getRegionAtIndex (unsigned inIndex) const
	Returns a reference to the region specified by inIndex. More...

const_iterator	getRegionBegin () const
	Return an iterator to the first region.

const_iterator	getRegionEnd () const
	Return an iterator to the next-after-last region.

virtual void	addFillRegion (uint32_t inAddress, unsigned inLength)
	Add a region to be filled with zeroes.

virtual void	addTextRegion (uint32_t inAddress, const uint8_t *inData, unsigned inLength)
	Add a region containing data to be loaded.

unsigned	getRegionCount () const
	Returns the total number of regions. More...

const MemoryRegion &	getRegionAtIndex (unsigned inIndex) const
	Returns a reference to the region specified by inIndex.

const_iterator	getRegionBegin () const
	Return an iterator to the first region.

const_iterator	getRegionEnd () const
	Return an iterator to the next-after-last region.

Entry point
void	setEntryPoint (uint32_t inEntryAddress)
	Sets the entry point address.

bool	hasEntryPoint () const
	Returns true if an entry point has been set.

uint32_t	getEntryPoint () const
	Returns the entry point address.

void	setEntryPoint (uint32_t inEntryAddress)
	Sets the entry point address.

bool	hasEntryPoint () const
	Returns true if an entry point has been set.

uint32_t	getEntryPoint () const
	Returns the entry point address.

Address filter
virtual void	addAddressFilter (const AddressFilter &filter)
	Add a new address filter. More...

template<typename _T >
void	addAddressFilters (_T from, _T to)
	Add multiple address filters at once. More...

virtual void	clearAddressFilters ()
	Remove all active filters.

virtual void	applyAddressFilters ()
	Process all active filters and perform associated actions. More...

virtual void	addAddressFilter (const AddressFilter &filter)
	Add a new address filter.

template<typename _T >
void	addAddressFilters (_T from, _T to)
	Add multiple address filters at once. More...

virtual void	clearAddressFilters ()
	Remove all active filters.

virtual void	applyAddressFilters ()
	Process all active filters and perform associated actions.

Protected Member Functions
void	cropRegionToFilter (MemoryRegion &region, const AddressFilter &filter)
	Deletes the portion region that overlaps filter. More...

void	insertOrMergeRegion (MemoryRegion &inRegion)
	Inserts the region in sorted order or merges with one already in the image. More...

void	mergeRegions (MemoryRegion &inOldRegion, MemoryRegion &inNewRegion)
	Merges two memory regions into one. More...

void	cropRegionToFilter (MemoryRegion &region, const AddressFilter &filter)
	Deletes the portion region that overlaps filter.

void	insertOrMergeRegion (MemoryRegion &inRegion)
	Inserts the region in sorted order or merges with one already in the image.

void	mergeRegions (MemoryRegion &inOldRegion, MemoryRegion &inNewRegion)
	Merges two memory regions into one.

Protected Attributes
std::string	m_name
	The name of the image (can be a file name, for instance).

int	m_alignment
	The required address alignment for each memory region.

bool	m_hasEntry
	True if an entry point has been set.

uint32_t	m_entry
	Entry point address.

MemoryRegionList	m_image
	The memory regions.

AddressFilterList	m_filters
	List of active address filters.

Detailed Description

Used to build a representation of memory regions.

An intermediate representation of the memory regions and segments loaded from an executable file. Also used to find contiguous segments that are specified separately in the source file.

When regions are added, an attempt is made to coalesce contiguous regions. In order for this to succeed, the touching regions must be of the same type and have the same permissions. Regions are also kept sorted by their address range as they are added.

An intermediate representation of the memory regions and segments loaded from an executable file. Also used to find contiguous segments that are specified separately in the source file.

When regions are added, an attempt is made to coalesce contiguous regions. In order for this to succeed, the touching regions must be of the same type and have the same permissions. Regions are also kept sorted by their address range as they are added.

Member Typedef Documentation

typedef MemoryRegionList::const_iterator StExecutableImage::const_iterator

The iterator type used to access StExecutableImage::MemoryRegion objects. This type is used by the methods getRegionBegin() and getRegionEnd().

typedef MemoryRegionList::const_iterator StExecutableImage::const_iterator

The iterator type used to access StExecutableImage::MemoryRegion objects. This type is used by the methods getRegionBegin() and getRegionEnd().

Member Enumeration Documentation

anonymous enum

Memory region flag constants.

Enumerator
REGION_READ_FLAG	Region is readable.
REGION_WRITE_FLAG	Region is writable.
REGION_EXEC_FLAG	Region may contain executable code.
REGION_RW_FLAG	Region is read-write.
REGION_PERM_FLAG_MASK	Mask to access only permissions flags for a region.

anonymous enum

Memory region flag constants.

Enumerator
REGION_READ_FLAG	Region is readable.
REGION_WRITE_FLAG	Region is writable.
REGION_EXEC_FLAG	Region may contain executable code.
REGION_RW_FLAG	Region is read-write.
REGION_PERM_FLAG_MASK	Mask to access only permissions flags for a region.

enum StExecutableImage::AddressFilterAction

The possible actions for regions matching an address filter range.

Enumerator
ADDR_FILTER_NONE	Do nothing.
ADDR_FILTER_ERROR	Raise an error exception.
ADDR_FILTER_WARNING	Raise a warning exception.
ADDR_FILTER_CROP	Don't include the matching address range in the executable image.
ADDR_FILTER_NONE	Do nothing.
ADDR_FILTER_ERROR	Raise an error exception.
ADDR_FILTER_WARNING	Raise a warning exception.
ADDR_FILTER_CROP	Don't include the matching address range in the executable image.

enum StExecutableImage::AddressFilterAction

The possible actions for regions matching an address filter range.

Enumerator
ADDR_FILTER_NONE	Do nothing.
ADDR_FILTER_ERROR	Raise an error exception.
ADDR_FILTER_WARNING	Raise a warning exception.
ADDR_FILTER_CROP	Don't include the matching address range in the executable image.
ADDR_FILTER_NONE	Do nothing.
ADDR_FILTER_ERROR	Raise an error exception.
ADDR_FILTER_WARNING	Raise a warning exception.
ADDR_FILTER_CROP	Don't include the matching address range in the executable image.

enum StExecutableImage::MemoryRegionType

Possible types of memory regions.

Enumerator
TEXT_REGION	A region containing data or instructions.
FILL_REGION	Region to be initialized with zero bytes.
TEXT_REGION	A region containing data or instructions.
FILL_REGION	Region to be initialized with zero bytes.

enum StExecutableImage::MemoryRegionType

Possible types of memory regions.

Enumerator
TEXT_REGION	A region containing data or instructions.
FILL_REGION	Region to be initialized with zero bytes.
TEXT_REGION	A region containing data or instructions.
FILL_REGION	Region to be initialized with zero bytes.

Constructor & Destructor Documentation

StExecutableImage::StExecutableImage ( const StExecutableImage & inOther )

Copy constructor.

Makes a duplicate of each memory region.

StExecutableImage::~StExecutableImage ( )

virtual

Destructor.

Disposes of memory allocated for each region.

Member Function Documentation

void StExecutableImage::addAddressFilter ( const AddressFilter & filter )

virtual

Add a new address filter.

The list of address filters is kept sorted as filters are added.

template<typename _T >

void StExecutableImage::addAddressFilters	(	_T	from,
		_T	to
	)

inline

Add multiple address filters at once.

The template argument _T must be an iterator or const iterator that dereferences to an StExecutableImage::AddressFilter reference. All filters from from to to will be added to the address filter list.

template<typename _T >

void StExecutableImage::addAddressFilters	(	_T	from,
		_T	to
	)

inline

Add multiple address filters at once.

The template argument _T must be an iterator or const iterator that dereferences to an StExecutableImage::AddressFilter reference. All filters from from to to will be added to the address filter list.

void StExecutableImage::addFillRegion	(	uint32_t	inAddress,
		unsigned	inLength
	)

virtual

Add a region to be filled with zeroes.

Exceptions

std::runtime_error will be thrown if the new overlaps an existing region.

void StExecutableImage::addTextRegion	(	uint32_t	inAddress,
		const uint8_t *	inData,
		unsigned	inLength
	)

virtual

Add a region containing data to be loaded.

A copy of inData is made before returning. The copy will be deleted when the executable image is destructed. Currently, the text region is created with read, write, and executable flags set.

Exceptions

std::runtime_error	will be thrown if the new overlaps an existing region.
std::bad_alloc	is thrown if memory for the copy of inData cannot be allocated.

void StExecutableImage::applyAddressFilters ( )

virtual

Process all active filters and perform associated actions.

Exceptions

StExecutableImage::address_filter_exception Raised when a filter with the type ADDR_FILTER_ERROR or ADDR_FILTER_WARNING is matched.

Exceptions

StExecutableImage::address_filter_exception Raised when a filter with the type ADDR_FILTER_ERROR or ADDR_FILTER_WARNING is matched.

void StExecutableImage::cropRegionToFilter	(	MemoryRegion &	region,
		const AddressFilter &	filter
	)

protected

Deletes the portion region that overlaps filter.

There are several possible cases here:

No overlap at all. Nothing is done.
All of the memory region is matched by the filter. The region is removed from StExecutableImage::m_image and its data memory freed.
The remaining portion of the region is one contiguous chunk. In this case, region is simply modified.
The region is split in the middle by the filter. The original region is modified to match the first remaining chunk. And a new StExecutableImage::MemoryRegion instance is created to hold the other leftover piece.

const StExecutableImage::MemoryRegion & StExecutableImage::getRegionAtIndex ( unsigned inIndex ) const

Returns a reference to the region specified by inIndex.

Exceptions

std::out_of_range is thrown if inIndex is out of range.

unsigned StExecutableImage::getRegionCount ( ) const

inline

Returns the total number of regions.

Note that this count may not be the same as the number of calls to addFillRegion() and addTextRegion() due to region coalescing.

unsigned StExecutableImage::getRegionCount ( ) const

inline

Returns the total number of regions.

Note that this count may not be the same as the number of calls to addFillRegion() and addTextRegion() due to region coalescing.

void StExecutableImage::insertOrMergeRegion ( MemoryRegion & inRegion )

protected

Inserts the region in sorted order or merges with one already in the image.

Exceptions

std::runtime_error will be thrown if inRegion overlaps an existing region.

Exceptions

std::runtime_error will be thrown if inRegion overlaps an existing region.

void StExecutableImage::mergeRegions	(	MemoryRegion &	inOldRegion,
		MemoryRegion &	inNewRegion
	)

protected

Merges two memory regions into one.

Extends inNewRegion to include the data in inOldRegion. It is assumed that the two regions are compatible. The new region may come either before or after the old region in memory. Note that while the two regions don't necessarily have to be touching, it's probably a good idea. That's because any data between the regions will be set to 0.

For TEXT_REGION types, the two original regions will have their data deleted during the merge. Thus, this method is not safe if any outside callers may be accessing the region's data.

void StExecutableImage::setName ( const std::string & inName )

virtual

Sets the image's name to inName.

A copy of inName is made, so the original may be disposed of by the caller after this method returns.

The documentation for this class was generated from the following files:

apps/elftosb/common/StExecutableImage.h
apps/elftosb/common/StExecutableImage.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation