ROSE  0.9.9.109
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Friends | List of all members
Rose::BinaryAnalysis::MemoryMap Class Reference

Description

An efficient mapping from an address space to stored data.

This class maps addresses in a 64-bit virtual address space to bytes stored in buffers and is a specialization of Sawyer::Container::AddressMap. A MemoryMap stores pairs of address ranges and segments, and each segment points to a buffer. The address space is segmented into non-overlapping, contiguous regions called "segments" (Sawyer::Container::AddressSegment) and the addresses in a segment are mapped 1:1 onto data storage containers (Sawyer::Container::Buffer).

Buffers come in a variety of kinds, all derived from Sawyer::Container::Buffer and they are reference counted via shared-ownership smart pointers (Shared ownership). Always refer to a buffer with its Ptr type. They should be created with various instance class methods, and they should never be explicitly freed.

MemoryMap objects are reference counted and always created on the heap. They are referred to by the Ptr type which can be usually treated as an ordinary C++ pointer. Objects can be created with the static method instance, or by doing a shallow copy of an existing object using the shallowCopy method. Plain assignment (operator=) is similar to shallowCopy in that after the assignment the two objects will have independent copies of the segment information but will share the underlying data buffers. MemoryMap objects should not be explicitly deleted since the shared pointers will delete the object when it's no longer referenced.

Here's an example of mapping a file into an address space at virtual address 0x08040000 and then temporarily replacing the second 1kB page of the file with our own data. We demonstrate using a Sawyer::Container::MappedBuffer because these are very fast for large files, especially if only small parts of the file are accessed due to their use of OS-level memory mapping.

using namespace Sawyer::Container;
// Create and initialize the overlay data
myData_size = 8192;
uint8_t *myData = new uint8_t[myDataSize];
initialize(myData, myDataSize);
// Create the two buffers: one for the file, one for the overlay data
Buffer::Ptr fileBuf = MappedBuffer::instance("the_file", boost::iostreams::mapped_file::readonly);
Buffer::Ptr dataBuf = StaticBuffer::instance(myData, myDataSize);
// Create the memory map.
MemoryMap::Ptr map = MemoryMap::instance();
map->insert(AddressInterval::baseSize(0x08040000, fileBuf->size()),
AddressSegment(fileBuf, 0, MemoryMap::MM_PROT_READ, "the file contents"));
map->insert(AddressInterval::baseSize(0x08040000+1024, dataBuf->size()),
AddressSegment(dataBuf, 0, MemoryMap::MM_PROT_RW, "data overlay"));

A MemoryMap provides methods to easily read from and write to the underlying data storage, addressing it in terms of the virtual address space. These functions return the addresses that were accessed, and are prefixed by calls that describe what data is to be accessed.

// read part of the data, right across the file/overlay boundary
uint8_t data[4096];
size_t nRead = map->at(0x08040100).limit(sizeof data).read(data).size();
assert(nread==sizeof data);

The Sawyer documentation contains many more examples.

Definition at line 96 of file MemoryMap.h.

#include <MemoryMap.h>

Inheritance diagram for Rose::BinaryAnalysis::MemoryMap:
Inheritance graph
[legend]
Collaboration diagram for Rose::BinaryAnalysis::MemoryMap:
Collaboration graph
[legend]

Classes

struct  Attach
 Attach with ptrace first when reading a process? More...
 
class  Exception
 Exception for MemoryMap operations. More...
 
struct  Inconsistent
 Exception for an inconsistent mapping. More...
 
struct  NoFreeSpace
 Exception thrown by find_free() when there's not enough free space left. More...
 
struct  NotMapped
 Exception for when we try to access a virtual address that isn't mapped. More...
 
struct  SyntaxError
 Exception thrown by load() when there's a syntax error in the index file. More...
 

Public Types

typedef Sawyer::SharedPointer< MemoryMapPtr
 
typedef rose_addr_t Address
 
typedef uint8_t Value
 
typedef Sawyer::Container::AddressMap< Address, Value > Super
 
typedef Sawyer::Container::Buffer< Address, Value > Buffer
 
typedef Sawyer::Container::AllocatingBuffer< Address, Value > AllocatingBuffer
 
typedef Sawyer::Container::MappedBuffer< Address, Value > MappedBuffer
 
typedef Sawyer::Container::NullBuffer< Address, Value > NullBuffer
 
typedef Sawyer::Container::StaticBuffer< Address, Value > StaticBuffer
 
typedef Sawyer::Container::SegmentPredicate< Address, Value > SegmentPredicate
 
typedef Sawyer::Container::AddressMapConstraints< Sawyer::Container::AddressMap< rose_addr_t, uint8_t > > Constraints
 
typedef Sawyer::Container::AddressMapConstraints< const Sawyer::Container::AddressMap< rose_addr_t, uint8_t > > ConstConstraints
 
- Public Types inherited from Sawyer::Container::AddressMap< rose_addr_t, uint8_t >
typedef rose_addr_t Address
 Type for addresses. More...
 
typedef uint8_t Value
 Type of data stored in the address space. More...
 
typedef AddressSegment< rose_addr_t, uint8_t > Segment
 Type of segments stored by this map. More...
 
typedef Sawyer::Container::Buffer< Address, ValueBuffer
 
typedef Super::Node Node
 Storage node containing interval/segment pair. More...
 
typedef Super::ValueIterator SegmentIterator
 Iterates over segments in the map. More...
 
typedef Super::ConstValueIterator ConstSegmentIterator
 Iterators over segments in the map. More...
 
typedef Super::ConstIntervalIterator ConstIntervalIterator
 Iterates over address intervals in the map. More...
 
typedef Super::NodeIterator NodeIterator
 Iterates over address interval, segment pairs in the map. More...
 
typedef Super::ConstNodeIterator ConstNodeIterator
 Iterates over address interval/segment pairs in the map. More...
 
- Public Types inherited from Sawyer::Container::IntervalMap< Interval< rose_addr_t >, AddressSegment< rose_addr_t, uint8_t >, AddressMapImpl::SegmentMergePolicy< rose_addr_t, uint8_t > >
typedef Interval< rose_addr_t > Interval
 Interval type. More...
 
typedef AddressSegment< rose_addr_t, uint8_t > Value
 Value type. More...
 
typedef Container::Map< Interval, Value, IntervalCompare > Map
 Type of the underlying map. More...
 
typedef Map::Node Node
 Storage node. More...
 
typedef Map::ConstKeyIterator ConstIntervalIterator
 Interval iterator. More...
 
typedef Map::ValueIterator ValueIterator
 Value iterator. More...
 
typedef Map::ConstValueIterator ConstValueIterator
 Value iterator. More...
 
typedef Map::NodeIterator NodeIterator
 Node iterator. More...
 
typedef Map::ConstNodeIterator ConstNodeIterator
 Node iterator. More...
 

Public Member Functions

Ptr shallowCopy ()
 Create a new copy of the memory map. More...
 
size_t insertFile (const std::string &fileName, rose_addr_t va, bool writable=false, std::string segmentName="")
 Insert file contents into memory map. More...
 
AddressInterval insertFile (const std::string &locatorString)
 Insert file contents into memory map. More...
 
void insertProcess (pid_t pid, Attach::Boolean attach)
 Insert the memory of some other process into this memory map. More...
 
void insertProcess (const std::string &locatorString)
 Insert the memory of some other process into this memory map. More...
 
void eraseZeros (size_t minsize)
 Erases regions of zero bytes that are executable and readable and at least minsize in size. More...
 
bool shrinkUnshare ()
 Shrink buffers and remove sharing. More...
 
size_t readQuick (void *buf, rose_addr_t startVa, size_t desired) const
 Read data into buffer. More...
 
std::string readString (rose_addr_t startVa, size_t desired, int(*validChar)(int)=NULL, int(*invalidChar)(int)=NULL, unsigned requiredPerms=READABLE, unsigned prohibitedPerms=0, char terminator='\0') const
 Reads a NUL-terminated string from the memory map. More...
 
SgUnsignedCharList readVector (rose_addr_t startVa, size_t desired, unsigned requiredPerms=READABLE) const
 Read quickly into a vector. More...
 
size_t writeQuick (const void *buf, rose_addr_t startVa, size_t desired)
 Write data from buffer. More...
 
Sawyer::Optional< rose_addr_t > findSequence (const AddressInterval &interval, const std::vector< uint8_t > &sequence) const
 Search for a byte sequence. More...
 
ByteOrder::Endianness byteOrder () const
 Property: byte order. More...
 
void byteOrder (ByteOrder::Endianness order)
 Property: byte order. More...
 
Sawyer::Optional< rose_addr_t > findAny (const Extent &limits, const std::vector< uint8_t > &bytesToFind, unsigned requiredPerms=READABLE, unsigned prohibitedPerms=0) const
 Search for any byte. More...
 
Sawyer::Optional< rose_addr_t > findAny (const AddressInterval &limits, const std::vector< uint8_t > &bytesToFind, unsigned requiredPerms=READABLE, unsigned prohibitedPerms=0) const
 Search for any byte. More...
 
void dump (FILE *, const char *prefix="") const
 Prints the contents of the map for debugging. More...
 
void dump (std::ostream &, std::string prefix="") const
 Prints the contents of the map for debugging. More...
 
void print (std::ostream &o, std::string prefix="") const
 Prints the contents of the map for debugging. More...
 
- Public Member Functions inherited from Sawyer::Container::AddressMap< rose_addr_t, uint8_t >
 AddressMap ()
 Constructs an empty address map. More...
 
 AddressMap (const AddressMap &other, bool copyOnWrite=false)
 Copy constructor. More...
 
void checkConsistency () const
 Check map consistency. More...
 
Address nSegments () const
 Number of segments contained in the map. More...
 
Optional< Addressnext (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Minimum or maximum address that satisfies constraints. More...
 
Sawyer::Container::Interval< Addressavailable (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Adress interval that satisfies constraints. More...
 
bool exists (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Determines if an address exists with the specified constraints. More...
 
Sawyer::Container::Interval< Addressunmapped (Address boundary, MatchFlags flags=0) const
 Find unmapped interval. More...
 
Optional< AddressfindFreeSpace (size_t nValues, size_t alignment=1, Sawyer::Container::Interval< Address > restriction=Sawyer::Container::Interval< Address >::whole(), MatchFlags flags=0) const
 Find free space. More...
 
void prune (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
 Prune away addresses that match constraints. More...
 
void keep (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
 Keep only addresses that match constraints. More...
 
void changeAccess (unsigned requiredAccess, unsigned prohibitedAccess, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
 Change access bits for addresses that match constraints. More...
 
AddressMapConstraints< const AddressMaprequire (unsigned x) const
 Constraint: required access bits. More...
 
AddressMapConstraints< AddressMaprequire (unsigned x)
 Constraint: required access bits. More...
 
AddressMapConstraints< const AddressMapprohibit (unsigned x) const
 Constraint: prohibited access bits. More...
 
AddressMapConstraints< AddressMapprohibit (unsigned x)
 Constraint: prohibited access bits. More...
 
AddressMapConstraints< const AddressMapaccess (unsigned x) const
 Constraint: required and prohibited access bits. More...
 
AddressMapConstraints< AddressMapaccess (unsigned x)
 Constraint: required and prohibited access bits. More...
 
AddressMapConstraints< const AddressMapsubstr (const std::string &x) const
 Constraint: segment name substring. More...
 
AddressMapConstraints< AddressMapsubstr (const std::string &x)
 Constraint: segment name substring. More...
 
AddressMapConstraints< const AddressMapat (Address x) const
 Constraint: anchor point. More...
 
AddressMapConstraints< AddressMapat (Address x)
 Constraint: anchor point. More...
 
AddressMapConstraints< const AddressMapat (const Sawyer::Container::Interval< Address > &x) const
 Constraint: anchored interval. More...
 
AddressMapConstraints< AddressMapat (const Sawyer::Container::Interval< Address > &x)
 Constraint: anchored interval. More...
 
AddressMapConstraints< const AddressMaplimit (size_t x) const
 Constraint: limit matched size. More...
 
AddressMapConstraints< AddressMaplimit (size_t x)
 Constraint: limit matched size. More...
 
AddressMapConstraints< const AddressMapatOrAfter (Address x) const
 Constraint: address lower bound. More...
 
AddressMapConstraints< AddressMapatOrAfter (Address x)
 Constraint: address lower bound. More...
 
AddressMapConstraints< const AddressMapatOrBefore (Address x) const
 Constraint: address upper bound. More...
 
AddressMapConstraints< AddressMapatOrBefore (Address x)
 Constraint: address upper bound. More...
 
AddressMapConstraints< const AddressMapwithin (const Sawyer::Container::Interval< Address > &x) const
 Constraint: address lower and upper bounds. More...
 
AddressMapConstraints< AddressMapwithin (const Sawyer::Container::Interval< Address > &x)
 Constraint: address lower and upper bounds. More...
 
AddressMapConstraints< const AddressMapwithin (Address x, Address y) const
 Constraint: address lower and upper bounds. More...
 
AddressMapConstraints< AddressMapwithin (Address x, Address y)
 Constraint: address lower and upper bounds. More...
 
AddressMapConstraints< const AddressMapbaseSize (Address base, Address size) const
 Constraint: address lower and upper bounds. More...
 
AddressMapConstraints< AddressMapbaseSize (Address base, Address size)
 Constraint: address lower and upper bounds. More...
 
AddressMapConstraints< const AddressMapafter (Address x) const
 Constraint: address lower bound. More...
 
AddressMapConstraints< AddressMapafter (Address x)
 Constraint: address lower bound. More...
 
AddressMapConstraints< const AddressMapbefore (Address x) const
 Constraint: address upper bound. More...
 
AddressMapConstraints< AddressMapbefore (Address x)
 Constraint: address upper bound. More...
 
AddressMapConstraints< const AddressMapsingleSegment () const
 Constraint: single segment. More...
 
AddressMapConstraints< AddressMapsingleSegment ()
 Constraint: single segment. More...
 
AddressMapConstraints< const AddressMapsegmentPredicate (SegmentPredicate< Address, Value > *p) const
 Constraint: arbitrary segment constraint. More...
 
AddressMapConstraints< AddressMapsegmentPredicate (SegmentPredicate< Address, Value > *p)
 Constraint: arbitrary segment constraint. More...
 
AddressMapConstraints< const AddressMapany () const
 Constraint: matches anything. More...
 
AddressMapConstraints< AddressMapany ()
 Constraint: matches anything. More...
 
AddressMapConstraints< const AddressMapnone () const
 Constraint: matches nothing. More...
 
AddressMapConstraints< AddressMapnone ()
 Constraint: matches nothing. More...
 
boost::iterator_range< SegmentIteratorsegments ()
 Iterator range for all segments. More...
 
boost::iterator_range< ConstSegmentIteratorsegments () const
 Iterator range for all segments. More...
 
boost::iterator_range< ConstSegmentIteratorsegments (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Segments that overlap with constraints. More...
 
boost::iterator_range< SegmentIteratorsegments (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
 Iterator range for all segments. More...
 
boost::iterator_range< NodeIteratornodes ()
 Iterator range for nodes. More...
 
boost::iterator_range< ConstNodeIteratornodes () const
 Iterator range for nodes. More...
 
boost::iterator_range< ConstNodeIteratornodes (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Nodes that overlap with constraints. More...
 
boost::iterator_range< NodeIteratornodes (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
 Nodes that overlap with constraints. More...
 
ConstNodeIterator findNode (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Find node containing address. More...
 
NodeIterator findNode (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
 Find node containing address. More...
 
void traverse (Functor &functor, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Invoke a function on each address interval. More...
 
void traverse (Functor &functor, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
 Invoke a function on each address interval. More...
 
void traverse (Visitor &visitor, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Invoke a function on each address interval. More...
 
void traverse (Visitor &visitor, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
 Invoke a function on each address interval. More...
 
Sawyer::Container::Interval< Addressread (Value *buf, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Reads data into the supplied buffer. More...
 
Sawyer::Container::Interval< Addressread (std::vector< Value > &buf, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Reads data into the supplied buffer. More...
 
Sawyer::Container::Interval< Addresswrite (const Value *buf, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
 Writes data from the supplied buffer. More...
 
Sawyer::Container::Interval< Addresswrite (const std::vector< Value > &buf, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0)
 Writes data from the supplied buffer. More...
 
- Public Member Functions inherited from Sawyer::Container::IntervalMap< Interval< rose_addr_t >, AddressSegment< rose_addr_t, uint8_t >, AddressMapImpl::SegmentMergePolicy< rose_addr_t, uint8_t > >
 IntervalMap ()
 Default constructor. More...
 
 IntervalMap (const IntervalMap< Interval2, T2, Policy2 > &other)
 Copy constructor. More...
 
IntervalMapoperator= (const IntervalMap< Interval2, T2, Policy2 > &other)
 Assignment operator. More...
 
boost::iterator_range< ConstIntervalIteratorintervals () const
 Iterators for traversing keys. More...
 
Interval firstUnmapped (typename Interval::Value minAddr) const
 Find the first unmapped region. More...
 
Interval lastUnmapped (typename Interval::Value maxAddr) const
 Find the last unmapped region. More...
 
bool exists (const typename Interval::Value &size) const
 Returns true if element exists. More...
 
Optional< ValuegetOptional (const typename Interval::Value &scalar) const
 Lookup and return a value or nothing. More...
 
const ValuegetOrDefault (const typename Interval::Value &scalar) const
 Lookup and return a value or a default. More...
 
bool isEmpty () const
 Determine if the container is empty. More...
 
size_t nIntervals () const
 Number of nodes in the container. More...
 
Interval::Value size () const
 Returns the number of values represented by this container. More...
 
Interval::Value least () const
 Returns the minimum scalar key. More...
 
Optional< typename Interval::Value > least (typename Interval::Value lowerLimit) const
 Returns the limited-minimum scalar key. More...
 
Interval::Value greatest () const
 Returns the maximum scalar key. More...
 
Optional< typename Interval::Value > greatest (typename Interval::Value upperLimit) const
 Returns the limited-maximum scalar key. More...
 
Optional< typename Interval::Value > leastUnmapped (typename Interval::Value lowerLimit) const
 Returns the limited-minimum unmapped scalar key. More...
 
Optional< typename Interval::Value > greatestUnmapped (typename Interval::Value upperLimit) const
 Returns the limited-maximum unmapped scalar key. More...
 
Interval hull () const
 Returns the range of values in this map. More...
 
void clear ()
 Empties the container. More...
 
void erase (const Interval &erasure)
 Erase the specified interval. More...
 
void eraseMultiple (const IntervalMap< Interval, T2, Policy2 > &other)
 Erase intervals specified in another IntervalMap. More...
 
void insert (Interval key, Value value, bool makeHole=true)
 Insert a key/value pair. More...
 
void insertMultiple (const IntervalMap< Interval, T2, Policy2 > &other, bool makeHole=true)
 Insert values from another container. More...
 
bool isOverlapping (const Interval &interval) const
 
bool isOverlapping (const IntervalMap< Interval, T2, Policy2 > &other) const
 
bool isDistinct (const Interval &interval) const
 
bool isDistinct (const IntervalMap< Interval, T2, Policy2 > &other) const
 
bool contains (Interval key) const
 
bool contains (const IntervalMap< Interval, T2, Policy2 > &other) const
 
boost::iterator_range< NodeIteratornodes ()
 Iterators for traversing nodes. More...
 
boost::iterator_range< ConstNodeIteratornodes () const
 Iterators for traversing nodes. More...
 
boost::iterator_range< ValueIteratorvalues ()
 Iterators for traversing values. More...
 
boost::iterator_range< ConstValueIteratorvalues () const
 Iterators for traversing values. More...
 
NodeIterator lowerBound (const typename Interval::Value &scalar)
 Find the first node whose interval ends at or above the specified scalar key. More...
 
ConstNodeIterator lowerBound (const typename Interval::Value &scalar) const
 Find the first node whose interval ends at or above the specified scalar key. More...
 
NodeIterator upperBound (const typename Interval::Value &scalar)
 Find the first node whose interval begins above the specified scalar key. More...
 
ConstNodeIterator upperBound (const typename Interval::Value &scalar) const
 Find the first node whose interval begins above the specified scalar key. More...
 
const Valueoperator[] (const typename Interval::Value &scalar) const
 Returns a reference to an existing value. More...
 
const Valueget (const typename Interval::Value &scalar) const
 Returns a reference to an existing value. More...
 
ValuegetOrElse (const typename Interval::Value &scalar, Value &dflt)
 Lookup and return a value or something else. More...
 
const ValuegetOrElse (const typename Interval::Value &scalar, const Value &dflt) const
 Lookup and return a value or something else. More...
 
NodeIterator findPrior (const typename Interval::Value &scalar)
 Find the last node whose interval starts at or below the specified scalar key. More...
 
ConstNodeIterator findPrior (const typename Interval::Value &scalar) const
 Find the last node whose interval starts at or below the specified scalar key. More...
 
NodeIterator find (const typename Interval::Value &scalar)
 Find the node containing the specified scalar key. More...
 
ConstNodeIterator find (const typename Interval::Value &scalar) const
 Find the node containing the specified scalar key. More...
 
boost::iterator_range< NodeIteratorfindAll (const Interval &interval)
 Finds all nodes overlapping the specified interval. More...
 
boost::iterator_range< ConstNodeIteratorfindAll (const Interval &interval) const
 Finds all nodes overlapping the specified interval. More...
 
NodeIterator findFirstOverlap (const Interval &interval)
 Find first interval that overlaps with the specified interval. More...
 
ConstNodeIterator findFirstOverlap (const Interval &interval) const
 Find first interval that overlaps with the specified interval. More...
 
std::pair< NodeIterator, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIteratorfindFirstOverlap (typename IntervalMap::NodeIterator thisIter, const IntervalMap< Interval, T2, Policy2 > &other, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIterator otherIter)
 Find first interval that overlaps with any in another container. More...
 
std::pair< ConstNodeIterator, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIteratorfindFirstOverlap (typename IntervalMap::ConstNodeIterator thisIter, const IntervalMap< Interval, T2, Policy2 > &other, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIterator otherIter) const
 Find first interval that overlaps with any in another container. More...
 
NodeIterator firstFit (const typename Interval::Value &size, NodeIterator start)
 Find the first fit node at or after a starting point. More...
 
ConstNodeIterator firstFit (const typename Interval::Value &size, ConstNodeIterator start) const
 Find the first fit node at or after a starting point. More...
 
NodeIterator bestFit (const typename Interval::Value &size, NodeIterator start)
 Find the best fit node at or after a starting point. More...
 
ConstNodeIterator bestFit (const typename Interval::Value &size, ConstNodeIterator start) const
 Find the best fit node at or after a starting point. More...
 
- Public Member Functions inherited from Sawyer::SharedObject
 SharedObject ()
 Default constructor. More...
 
 SharedObject (const SharedObject &)
 Copy constructor. More...
 
virtual ~SharedObject ()
 Virtual destructor. More...
 
SharedObjectoperator= (const SharedObject &)
 Assignment. More...
 

Static Public Member Functions

static Ptr instance ()
 Construct an empty memory map. More...
 
static std::string insertFileDocumentation ()
 Documentation string for insertFile. More...
 
static std::string insertProcessDocumentation ()
 Documentation string for insertProcess. More...
 
static std::string segmentTitle (const Segment &)
 Title of a segment when printing the map. More...
 
- Static Public Member Functions inherited from Sawyer::Container::IntervalMap< Interval< rose_addr_t >, AddressSegment< rose_addr_t, uint8_t >, AddressMapImpl::SegmentMergePolicy< rose_addr_t, uint8_t > >
static IntervalMapTraits< IMap >::NodeIterator findPriorImpl (IMap &imap, const typename Interval::Value &scalar)
 Find the last node whose interval starts at or below the specified scalar key. More...
 
static IntervalMapTraits< IMap >::NodeIterator findImpl (IMap &imap, const typename Interval::Value &scalar)
 Find the node containing the specified scalar key. More...
 
static boost::iterator_range< typename IntervalMapTraits< IMap >::NodeIteratorfindAllImpl (IMap &imap, const Interval &interval)
 Finds all nodes overlapping the specified interval. More...
 
static IntervalMapTraits< IMap >::NodeIterator findFirstOverlapImpl (IMap &imap, const Interval &interval)
 Find first interval that overlaps with the specified interval. More...
 
static std::pair< typename IntervalMapTraits< IMap >::NodeIterator, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIteratorfindFirstOverlapImpl (IMap &imap, typename IntervalMapTraits< IMap >::NodeIterator thisIter, const IntervalMap< Interval, T2, Policy2 > &other, typename IntervalMap< Interval, T2, Policy2 >::ConstNodeIterator otherIter)
 Find first interval that overlaps with any in another container. More...
 
static IntervalMapTraits< IMap >::NodeIterator firstFitImpl (IMap &imap, const typename Interval::Value &size, typename IntervalMapTraits< IMap >::NodeIterator start)
 Find the first fit node at or after a starting point. More...
 
static IntervalMapTraits< IMap >::NodeIterator bestFitImpl (IMap &imap, const typename Interval::Value &size, typename IntervalMapTraits< IMap >::NodeIterator start)
 Find the best fit node at or after a starting point. More...
 

Static Public Attributes

static const unsigned NO_ACCESS = 0
 
static const unsigned READABLE = Sawyer::Access::READABLE
 
static const unsigned WRITABLE = Sawyer::Access::WRITABLE
 
static const unsigned EXECUTABLE = Sawyer::Access::EXECUTABLE
 
static const unsigned IMMUTABLE = Sawyer::Access::IMMUTABLE
 
static const unsigned PRIVATE = 0x00000100
 
static const unsigned INITIALIZED = 0x00000200
 
static const unsigned READ_WRITE = READABLE | WRITABLE
 
static const unsigned READ_EXECUTE = READABLE | EXECUTABLE
 
static const unsigned READ_WRITE_EXECUTE = READABLE | WRITABLE | EXECUTABLE
 
static const unsigned RESERVED_ACCESS_BITS = 0x0000ffff
 

Protected Member Functions

 MemoryMap ()
 Constructs an empty memory map. More...
 

Friends

std::ostream & operator<< (std::ostream &, const MemoryMap &)
 

Constructor & Destructor Documentation

Rose::BinaryAnalysis::MemoryMap::MemoryMap ( )
inlineprotected

Constructs an empty memory map.

Definition at line 238 of file MemoryMap.h.

Referenced by shallowCopy().

Member Function Documentation

static Ptr Rose::BinaryAnalysis::MemoryMap::instance ( )
inlinestatic

Construct an empty memory map.

Definition at line 242 of file MemoryMap.h.

Ptr Rose::BinaryAnalysis::MemoryMap::shallowCopy ( )
inline

Create a new copy of the memory map.

The copy maintains its own independent list of segments, but points to the same data buffers as the source map.

Definition at line 249 of file MemoryMap.h.

References MemoryMap().

ByteOrder::Endianness Rose::BinaryAnalysis::MemoryMap::byteOrder ( ) const
inline

Property: byte order.

Every map has a default byte order property which can be used by functions that read and write multi-byte values when the user does not provide a byte order to those functions. The MemoryMap constructors initialize this property to ByteOrder::ORDER_UNSPECIFIED.

Definition at line 260 of file MemoryMap.h.

void Rose::BinaryAnalysis::MemoryMap::byteOrder ( ByteOrder::Endianness  order)
inline

Property: byte order.

Every map has a default byte order property which can be used by functions that read and write multi-byte values when the user does not provide a byte order to those functions. The MemoryMap constructors initialize this property to ByteOrder::ORDER_UNSPECIFIED.

Definition at line 261 of file MemoryMap.h.

size_t Rose::BinaryAnalysis::MemoryMap::insertFile ( const std::string &  fileName,
rose_addr_t  va,
bool  writable = false,
std::string  segmentName = "" 
)

Insert file contents into memory map.

Insert the contents of a file into the memory map at the specified address. This is just a convenience wrapper that creates a new MappedBuffer and inserts it into the mapping. Returns the size of the file mapping.

AddressInterval Rose::BinaryAnalysis::MemoryMap::insertFile ( const std::string &  locatorString)

Insert file contents into memory map.

Uses a locator string to load a file into a memory map.

Returns the address interval that was inserted into this memory map, or throws an std::runtime_error for syntax errors and problems reading the file.

Locator Syntax

The locator string is a file name preceded by various other parameters to control where the file is loaded in memory. It takes the form:

*  :[ADDR][+VMSIZE][=PERM]:[OFFSET[+FSIZE]]:FILENAME
* 

The fields between the first and second colon are parameters for virtual memory; the fields between the second and third colon are parameters for the file. Their meanings are:

  • ADDR: The virtual address where the first byte of the file is mapped. This can be specified in decimal, octal, or hexadecimal using the usual C syntax. If no address is specified then the file is mapped at the lowest unmapped region which is large enough to hold the file.
  • VMSIZE: Size of virtual memory to map. If VMSIZE is not specified then it is either the FSIZE (if specified) or the file size. On POSIX systems the file size is that which is reported by stat, and on other systems it is the number of bytes that can be read from the file. The size can be specified as decimal, octal, or hexadecimal with the usual C syntax. If VMSIZE is greater than the specified or calculated FSIZE then the data from the file is padded with zero bytes.
  • PERM: Accessibility for the mapped segment. If present, it should be any of the letters "r", "w", and/or "x" in that order to indicate readable, writable, and/or executable. If not present, the accessibility of the segment is the same as the user's accessibility of the file (on POSIX systems; "rwx" on Windows systems).
  • OFFSET: Byte offset within file for first byte to map. If no offset is specified then zero is assumed. The size can be decimal, octal, or hexadecimal in the usual C sytax.
  • FSIZE: Number of file bytes to map. If not specified the entire readable content of the file is mapped beginning at the specified OFFSET but not exceeding a specified VMSIZE. If this number of bytes cannot be read from the file then an error is thrown.
  • FILENAME: Name of file to read. The file must be readable by the user and its contents are copied into the memory map. Once inside the memory map, the segment can be given any accessibility according to PERM. The name of the segment will be the non-directory part of the FILENAME (e.g., on POSIX systems, the part after the final slash).

Examples

To load a couple raw files at the lowest available addresses:

:::myfile1.bin :::myfile2.bin

To load a 4k page of zeros with read and execute permission at address 0x7ffff000 (won't work on Microsoft systems):

:0x7ffff000+0x1000=rx::/dev/zero
@code
On Microsoft Windows one could create a large file containing zeros:
@code
:0x7ffff000+0x1000=rx::myzeros.dat

To load the .text and .data segments from a PE file when we know where they occur in the PE file but the PE file is damaged to the point where it cannot be loaded by ROSE's frontend. Both sections are zero-padded since the memory segment size is larger than the file size. But if one wants to more closely emulate the Windows loader, leave off the file sizes:

:0x01000400+0xa00=rx:0x1000+0x9a8:proxycfg.exe
:0x01000e00+0x200=rw:0x3000+8:proxycfg.exe
See also
insertFileDocumentation
static std::string Rose::BinaryAnalysis::MemoryMap::insertFileDocumentation ( )
static

Documentation string for insertFile.

void Rose::BinaryAnalysis::MemoryMap::insertProcess ( pid_t  pid,
Attach::Boolean  attach 
)

Insert the memory of some other process into this memory map.

void Rose::BinaryAnalysis::MemoryMap::insertProcess ( const std::string &  locatorString)

Insert the memory of some other process into this memory map.

The locator string follows the syntax described in insertProcessDocumentation.

static std::string Rose::BinaryAnalysis::MemoryMap::insertProcessDocumentation ( )
static

Documentation string for insertProcess.

void Rose::BinaryAnalysis::MemoryMap::eraseZeros ( size_t  minsize)

Erases regions of zero bytes that are executable and readable and at least minsize in size.

bool Rose::BinaryAnalysis::MemoryMap::shrinkUnshare ( )

Shrink buffers and remove sharing.

Creates a new buffer per segment and copies the data for that segment into the new buffer. The new buffers are allocated to be just large enough to hold the data for the segment's interval. Segments that shared the same underlying data no longer share data.

Returns true if new buffers could be allocated for all segments, and false otherwise. A false return value could occur if a buffer does not support the Sawyer::Container::Buffer::data. As of this writing (Nov 2016) the only buffer type that doesn't support data is NullBuffer, which doesn't appear in memory maps created by ROSE's binary specimen mappers.

size_t Rose::BinaryAnalysis::MemoryMap::readQuick ( void *  buf,
rose_addr_t  startVa,
size_t  desired 
) const
inline

Read data into buffer.

Definition at line 381 of file MemoryMap.h.

References Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::at().

std::string Rose::BinaryAnalysis::MemoryMap::readString ( rose_addr_t  startVa,
size_t  desired,
int(*)(int)  validChar = NULL,
int(*)(int)  invalidChar = NULL,
unsigned  requiredPerms = READABLE,
unsigned  prohibitedPerms = 0,
char  terminator = '\0' 
) const

Reads a NUL-terminated string from the memory map.

Reads data beginning at startVa in the memory map and continuing until one of the following conditions is met:

  • The desired number of characters has been read (returns empty string)
  • The next character is the termination character (defaults to NUL)
  • An invalidChar function is specified and the next character causes it to return true (returns empty string)
  • A validChar function is specified and the next character causes it to return false (returns empty string)

The empty string is returned unless the terminator character is encountered.

The validChar and invalidChar take an integer argument and return an integer value so that the C character classification functions from <ctype.h> can be used directly.

SgUnsignedCharList Rose::BinaryAnalysis::MemoryMap::readVector ( rose_addr_t  startVa,
size_t  desired,
unsigned  requiredPerms = READABLE 
) const

Read quickly into a vector.

size_t Rose::BinaryAnalysis::MemoryMap::writeQuick ( const void *  buf,
rose_addr_t  startVa,
size_t  desired 
)
inline

Write data from buffer.

Definition at line 404 of file MemoryMap.h.

References Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::at().

Sawyer::Optional<rose_addr_t> Rose::BinaryAnalysis::MemoryMap::findAny ( const Extent limits,
const std::vector< uint8_t > &  bytesToFind,
unsigned  requiredPerms = READABLE,
unsigned  prohibitedPerms = 0 
) const

Search for any byte.

Searches for all of the specified bytes simultaneously and returns the lowest address (subject to limits) where one of the specified values appears. If none of the specified bytes appear within the given address extent, then this method returns none.

Sawyer::Optional<rose_addr_t> Rose::BinaryAnalysis::MemoryMap::findAny ( const AddressInterval limits,
const std::vector< uint8_t > &  bytesToFind,
unsigned  requiredPerms = READABLE,
unsigned  prohibitedPerms = 0 
) const

Search for any byte.

Searches for all of the specified bytes simultaneously and returns the lowest address (subject to limits) where one of the specified values appears. If none of the specified bytes appear within the given address extent, then this method returns none.

Sawyer::Optional<rose_addr_t> Rose::BinaryAnalysis::MemoryMap::findSequence ( const AddressInterval interval,
const std::vector< uint8_t > &  sequence 
) const

Search for a byte sequence.

Searches for the bytes specified by sequence occuring within the specified interval. If the interval is empty or the sequence cannot be found then nothing is returned. Otherwise, the virtual address for the start of the sequence is returned. An empty sequence matches at the beginning of the interval.

void Rose::BinaryAnalysis::MemoryMap::dump ( FILE *  ,
const char *  prefix = "" 
) const

Prints the contents of the map for debugging.

The prefix string is added to the beginning of every line of output and typically is used to indent the output.

Referenced by print().

void Rose::BinaryAnalysis::MemoryMap::dump ( std::ostream &  ,
std::string  prefix = "" 
) const

Prints the contents of the map for debugging.

The prefix string is added to the beginning of every line of output and typically is used to indent the output.

void Rose::BinaryAnalysis::MemoryMap::print ( std::ostream &  o,
std::string  prefix = "" 
) const
inline

Prints the contents of the map for debugging.

The prefix string is added to the beginning of every line of output and typically is used to indent the output.

Definition at line 433 of file MemoryMap.h.

References dump().

static std::string Rose::BinaryAnalysis::MemoryMap::segmentTitle ( const Segment )
static

Title of a segment when printing the map.


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