StExecutableImage Class Reference

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

`#include <StExecutableImage.h>`

Collaboration diagram for StExecutableImage:
[legend]

## 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