ROSE  0.9.9.109
Classes | Public Types | Public Member Functions | List of all members
Sawyer::Container::AddressMap< A, T > Class Template Reference

Description

template<class A, class T = boost::uint8_t>
class Sawyer::Container::AddressMap< A, T >

A mapping from address space to values.

This object maps addresses (actually, intervals thereof) to values. Addresses must be an integral unsigned type but values may be any type as long as they are default constructible and copyable. The address type is usually an integral type whose width is the log base 2 of the size of the address space; the value type is often unsigned 8-bit bytes.

An address map accomplishes the mapping by inheriting from an IntervalMap, whose intervals are Interval and whose values are AddressSegment<A,T>. The AddressSegment objects point to reference-counted Buffer objects that hold the values. The same values can be mapped at different addresses by inserting segments at those addresses that point to a common buffer.

An address map implements read and write concepts for copying values between user-supplied buffers and the storage areas referenced by the map. Many of the address map methods operate over a region of the map described by a set of constraints that are matched within the map. Constraints are indicated by listing them before the map I/O operation, but they do not modify the map in any way–they exist outside the map. Constraints are combined by logical conjunction. For instance, the AddressMap::next method returns the lowest address that satisfies the given constraints, or nothing. If we wanted to search for the lowest address beteen 1000 and 1999 inclusive, that has read access but not write access, we would do so like this:

Optional<Address> x = map.within(1000,1999).require(READABLE).prohibit(WRITABLE).next();

In fact, by making use of the Sawyer::Optional API, we can write a loop that iterates over such addresses, although there may be more efficient ways to do this than one address at a time:

for (Address x=1000; map.within(x,1999).require(READABLE).prohibit(WRITABLE).next().assignTo(x); ++x) ...

The next example shows how to read a buffer's worth of values anchored at a particular starting value. The read method returns an address interval to indicate what addresses were accessed, but in this case we're only interested in the number of such addresses since we know the starting address.

Value buf[10];
size_t nAccessed = map.at(1000).limit(10).read(buf).size();

An interval return value is more useful when we don't know where the operation occurs until after it occurs. For instance, to read up to 10 values that are readable at or beyond some address:

Value buf[10]
Interval<Address> accessed = map.atOrAfter(1000).limit(10).require(READABLE).read(buf);

Since all map operations take the same constraints, it is possible to rewrite the previous for loop so that instead of searching for an address it actually reads data. Here's a loop that prints all the data that's readable but not writable and falls between two addresses, regardless of what other segments also exist in that same interval:

static const size_t bufsz = 256;
Value buf[bufsz];
Address addr = 1000;
while (Interval accessed = map.within(addr, 1999).require(READABLE).prohibit(WRITABLE).limit(bufsz).read(buf)) {
for (Address i=accessed.least(); i<=access.greatest(); ++i)
std::cout <<i <<": " <<buf[i-accessed.least()] <<"\n";
addr += accessed.size();
}

Most I/O methods require that constraints match only contiguous addresses. If there is an intervening address that does not satisfy the constraint, including addresses that are not mapped, then the matched range terminates at the non-matching address. However, the MATCH_NONCONTIGUOUS flag can be used to relax this, in which case the matched interval of addresses may include addresses that are not mapped. Regardless of whether contiguous addresses are required, the returned interval of addresses will never contain an address that is mapped and does not also satisfy the constraints. I/O operations (read and write) require contiguous addresses, but some other methods don't. For instance, the expressions

Interval<Address> found1 = map.within(100,200).require(READABLE).available(MATCH_CONTIGUOUS);
Interval<Address> found2 = map.within(100,200).require(READABLE).available(MATCH_NONCONTIGUOUS);

are the same except the second one returns an interval that might include non-mapped addresses. A few methods go even further and are able to operate across mapped addresses that don't satisfy the segment constraints, skipping over the addresses that don't satisfy the constraints. For instance, the prune and keep functions operate this way so that a call like:

map.within(100,200).require(READABLE).prohibit(WRITABLE).keep();

will discard all addresses except keeping those which are between 100 and 200 (inclusive) and which are readable but not writable. The documentation for each method states whether the default is contiguous matching, non-contiguous matching, or skipping over whole segments, and the method can take a bit flag (MatchFlags) to change its default behavior (with some restrictions).

One of the MatchFlags bits indicates whether the constraint should match the lowest or highest possible addresses. The default is to match the constraint at the lowest possible addresses. Matching at the highest addresses is useful when iterating backward. For instance, if one wants to read up to 1024 values that end at address 1023 but is not sure how many prior addresses are readable, he could use backward matching. This is much more efficient than the alternative of searching backward one address at a time, and is simpler than doing an explicit binary search:

Value buf[1024];
Interval<Address> accessed = map.at(1023).limit(1024).read(buf, MATCH_BACKWARD);

Backward and forward I/O behaves identically as far as which array element holds which value. In all cases array element zero contains the value at the lowest address read or written.

Here's an example that creates two buffers (they happen to point to arrays that the Buffer objects do not own), maps them at addresses in such a way that part of the smaller of the two buffers occludes the larger buffer, and then performs a write operation that touches parts of both buffers. We then rewrite part of the mapping and do another write operation:

using namespace Sawyer::Container;
typedef unsigned Address;
typedef Interval<Address> Addresses;
typedef Buffer<Address, char>::Ptr BufferPtr;
typedef AddressMap<Address, char> MemoryMap;
// Create some buffer objects
char data1[15];
memcpy(data1, "---------------", 15);
char data2[5];
memcpy(data2, "##########", 10);
BufferPtr buf2 = Sawyer::Container::StaticBuffer<Address, char>::instance(data2, 5); // using only first 5 bytes
// Map data2 into the middle of data1
MemoryMap map;
map.insert(Addresses::baseSize(1000, 15), Segment(buf1));
map.insert(Addresses::baseSize(1005, 5), Segment(buf2));
// Write across both buffers and check that data2 occluded data1
Addresses accessed = map.at(1001).limit(13).write("bcdefghijklmn");
ASSERT_always_require(accessed.size()==13);
ASSERT_always_require(0==memcmp(data1, "-bcde-----klmn-", 15));
ASSERT_always_require(0==memcmp(data2, "fghij#####", 10));
// Map the middle of data1 over the top of data2 again and check that the mapping has one element. I.e., the three
// separate parts were recombined into a single entry since they are three consecutive areas of a single buffer.
map.insert(Addresses::baseSize(1005, 5), Segment(buf1, 5));
ASSERT_always_require(map.nSegments()==1);
// Write some data again
accessed = map.at(1001).limit(13).write("BCDEFGHIJKLMN");
ASSERT_always_require(accessed.size()==13);
ASSERT_always_require(0==memcmp(data1, "-BCDEFGHIJKLMN-", 15));
ASSERT_always_require(0==memcmp(data2, "fghij#####", 10));

Microsoft C++ compilers

Microsoft Visual Studio 12 2013 (MSVC 18.0.30501.0) and possibly other versions look up non-dependent names in template base classes in violation of C++ standards and apparently no switch to make their behavior compliant with the standard. This causes problems for AddressMap because unqualified references to Interval should refer to the Sawyer::Container::Interval class template, but instead they refer to the Interval typedef in the base class. Our work around is to qualify all occurrences of Interval where Microsoft compilers go wrong.

Definition at line 971 of file AddressMap.h.

#include <AddressMap.h>

Inheritance diagram for Sawyer::Container::AddressMap< A, T >:
Inheritance graph
[legend]
Collaboration diagram for Sawyer::Container::AddressMap< A, T >:
Collaboration graph
[legend]

Classes

class  Visitor
 Base class for traversals. More...
 

Public Types

typedef A Address
 Type for addresses. More...
 
typedef T Value
 Type of data stored in the address space. More...
 
typedef AddressSegment< A, 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< A >, AddressSegment< A, T >, AddressMapImpl::SegmentMergePolicy< A, T > >
typedef Interval< A > Interval
 Interval type. More...
 
typedef AddressSegment< A, 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

 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...
 
template<typename Functor >
void traverse (Functor &functor, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const
 Invoke a function on each address interval. More...
 
template<typename Functor >
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< A >, AddressSegment< A, T >, AddressMapImpl::SegmentMergePolicy< A, 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...
 

Additional Inherited Members

- Static Public Member Functions inherited from Sawyer::Container::IntervalMap< Interval< A >, AddressSegment< A, T >, AddressMapImpl::SegmentMergePolicy< A, 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...
 

Member Typedef Documentation

template<class A, class T = boost::uint8_t>
typedef A Sawyer::Container::AddressMap< A, T >::Address

Type for addresses.

This should be an unsigned type.

Definition at line 976 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
typedef T Sawyer::Container::AddressMap< A, T >::Value

Type of data stored in the address space.

Definition at line 977 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
typedef AddressSegment<A, T> Sawyer::Container::AddressMap< A, T >::Segment

Type of segments stored by this map.

Definition at line 978 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
typedef Super::Node Sawyer::Container::AddressMap< A, T >::Node

Storage node containing interval/segment pair.

Definition at line 980 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
typedef Super::ValueIterator Sawyer::Container::AddressMap< A, T >::SegmentIterator

Iterates over segments in the map.

Definition at line 981 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
typedef Super::ConstValueIterator Sawyer::Container::AddressMap< A, T >::ConstSegmentIterator

Iterators over segments in the map.

Definition at line 982 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
typedef Super::ConstIntervalIterator Sawyer::Container::AddressMap< A, T >::ConstIntervalIterator

Iterates over address intervals in the map.

Definition at line 983 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
typedef Super::NodeIterator Sawyer::Container::AddressMap< A, T >::NodeIterator

Iterates over address interval, segment pairs in the map.

Definition at line 984 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
typedef Super::ConstNodeIterator Sawyer::Container::AddressMap< A, T >::ConstNodeIterator

Iterates over address interval/segment pairs in the map.

Definition at line 985 of file AddressMap.h.

Constructor & Destructor Documentation

template<class A, class T = boost::uint8_t>
Sawyer::Container::AddressMap< A, T >::AddressMap ( )
inline

Constructs an empty address map.

Definition at line 997 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
Sawyer::Container::AddressMap< A, T >::AddressMap ( const AddressMap< A, T > &  other,
bool  copyOnWrite = false 
)
inline

Copy constructor.

The new address map has the same addresses mapped to the same buffers as the other map. The buffers themselves are not copied since they are reference counted.

If copyOnWrite is set then the buffers are marked so that any subsequent write to that buffer via the write method from any AddressMap object will cause a new copy to be created and used by the AddressMap that's doing the writing. One should be careful when buffers are intended to be shared because setting the copy-on-write bit on the buffer will cause the sharing to be broken. For example, if map1 is created and then copied into map2 with the copy-on-write bit cleared, then any writes to the buffer via map1 will be visible when reading from map2 and vice versa. However, if map3 is then created by copying either map1 or map2 with the copy-on-write bit set, then writes to any of the three maps will cause that map to obtain an independent copy of the buffer, effectively removing the sharing that was intended between map1 and map2. Another thing to be aware of is that some buffer types will return a different buffer type when they're copied. For instance, copying a StaticBuffer or MappedBuffer will return an AllocatingBuffer.

Definition at line 1014 of file AddressMap.h.

Member Function Documentation

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::require ( unsigned  x) const
inline

Constraint: required access bits.

Constrains address to those that have all of the access bits that are set in x.

Definition at line 1028 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::require().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::require ( unsigned  x)
inline

Constraint: required access bits.

Constrains address to those that have all of the access bits that are set in x.

Definition at line 1031 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::prohibit ( unsigned  x) const
inline

Constraint: prohibited access bits.

Constrains addresses to those that have none of the access bits that are set in x.

Definition at line 1041 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::prohibit().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::prohibit ( unsigned  x)
inline

Constraint: prohibited access bits.

Constrains addresses to those that have none of the access bits that are set in x.

Definition at line 1044 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::access ( unsigned  x) const
inline

Constraint: required and prohibited access bits.

Constrains address to those that have the specified access bits. This method is the same as calling require with the specified bit vector, and prohibit with the inverted bit vector.

Definition at line 1055 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::access().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::access ( unsigned  x)
inline

Constraint: required and prohibited access bits.

Constrains address to those that have the specified access bits. This method is the same as calling require with the specified bit vector, and prohibit with the inverted bit vector.

Definition at line 1058 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::substr ( const std::string &  x) const
inline

Constraint: segment name substring.

Constrains addresses to those that belong to a segment that contains string x as part of its name.

Definition at line 1068 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::substr().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::substr ( const std::string &  x)
inline

Constraint: segment name substring.

Constrains addresses to those that belong to a segment that contains string x as part of its name.

Definition at line 1071 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::at ( Address  x) const
inline

Constraint: anchor point.

Constrains addresses to a sequence that begins at x. If address x is not part of the addresses matched by the other constraints, then no address matches.

Definition at line 1082 of file AddressMap.h.

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

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::at ( Address  x)
inline

Constraint: anchor point.

Constrains addresses to a sequence that begins at x. If address x is not part of the addresses matched by the other constraints, then no address matches.

Definition at line 1085 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::at ( const Sawyer::Container::Interval< Address > &  x) const
inline

Constraint: anchored interval.

Constrains addresses so that the lowest or highest matched address is the specified anchor point. When matching constraints in the forward direction (the default) then the anchor must be the lowest address, and when matching in the backward direction the anchor must be the highest address. The direction is specified by an argument to the operation.

For instance:

map.at(100).limit(10).read(buf); // 1
map.at(100).limit(10).read(buf, MATCH_BACKWARD); // 2

Expression 1 reads up to 10 values such that the lowest value read is at address 100, while expression 2 reads up to 10 values such that the highest value read is at address 100. In both cases, if address 100 is not mapped (or otherwise does not satisfy the constraints) then nothing is read.

Definition at line 1109 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::at ( const Sawyer::Container::Interval< Address > &  x)
inline

Constraint: anchored interval.

Constrains addresses so that the lowest or highest matched address is the specified anchor point. When matching constraints in the forward direction (the default) then the anchor must be the lowest address, and when matching in the backward direction the anchor must be the highest address. The direction is specified by an argument to the operation.

For instance:

map.at(100).limit(10).read(buf); // 1
map.at(100).limit(10).read(buf, MATCH_BACKWARD); // 2

Expression 1 reads up to 10 values such that the lowest value read is at address 100, while expression 2 reads up to 10 values such that the highest value read is at address 100. In both cases, if address 100 is not mapped (or otherwise does not satisfy the constraints) then nothing is read.

Definition at line 1112 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::limit ( size_t  x) const
inline

Constraint: limit matched size.

Constrains the matched addresses so that at most x addresses match. Forward matching matches the first x addresses while backward matching matches the last x addresses.

Definition at line 1123 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::limit().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::limit ( size_t  x)
inline

Constraint: limit matched size.

Constrains the matched addresses so that at most x addresses match. Forward matching matches the first x addresses while backward matching matches the last x addresses.

Definition at line 1126 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::atOrAfter ( Address  x) const
inline

Constraint: address lower bound.

Constrains matched addresses so that they are all greater than or equal to x.

Definition at line 1136 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::atOrAfter().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::atOrAfter ( Address  x)
inline

Constraint: address lower bound.

Constrains matched addresses so that they are all greater than or equal to x.

Definition at line 1139 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::atOrBefore ( Address  x) const
inline

Constraint: address upper bound.

Constrains matched addresses so that they are all less than or equal to x.

Definition at line 1149 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::atOrBefore().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::atOrBefore ( Address  x)
inline

Constraint: address upper bound.

Constrains matched addresses so that they are all less than or equal to x.

Definition at line 1152 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::within ( const Sawyer::Container::Interval< Address > &  x) const
inline

Constraint: address lower and upper bounds.

Constrains matched addresses so they are all within the specified interval.

Definition at line 1162 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::within().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::within ( const Sawyer::Container::Interval< Address > &  x)
inline

Constraint: address lower and upper bounds.

Constrains matched addresses so they are all within the specified interval.

Definition at line 1165 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::within ( Address  x,
Address  y 
) const
inline

Constraint: address lower and upper bounds.

Constrains matched addresses so they are all greater than or equal to x and less than or equal to y.

Definition at line 1175 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::within ( Address  x,
Address  y 
)
inline

Constraint: address lower and upper bounds.

Constrains matched addresses so they are all greater than or equal to x and less than or equal to y.

Definition at line 1178 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::baseSize ( Address  base,
Address  size 
) const
inline

Constraint: address lower and upper bounds.

Specifies lower and upper bounds. The upper bound is specified indirectly by a size.

Definition at line 1188 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::baseSize().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::baseSize ( Address  base,
Address  size 
)
inline

Constraint: address lower and upper bounds.

Specifies lower and upper bounds. The upper bound is specified indirectly by a size.

Definition at line 1191 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::after ( Address  x) const
inline

Constraint: address lower bound.

Constrains matched addresses so that they are all greater than x.

Definition at line 1201 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::after().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::after ( Address  x)
inline

Constraint: address lower bound.

Constrains matched addresses so that they are all greater than x.

Definition at line 1204 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::before ( Address  x) const
inline

Constraint: address upper bound.

Constrains matched addresses so that they are all less than x.

Definition at line 1214 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::before().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::before ( Address  x)
inline

Constraint: address upper bound.

Constrains matched addresses so that they are all less than x.

Definition at line 1217 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::singleSegment ( ) const
inline

Constraint: single segment.

Constrains matched addresses so that they all come from the same segment.

Definition at line 1227 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::singleSegment().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::singleSegment ( )
inline

Constraint: single segment.

Constrains matched addresses so that they all come from the same segment.

Definition at line 1230 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::segmentPredicate ( SegmentPredicate< Address, Value > *  p) const
inline

Constraint: arbitrary segment constraint.

Constraints matched addresses to those for which the chain of segment predicates return true.

Definition at line 1240 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::segmentPredicate().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::segmentPredicate ( SegmentPredicate< Address, Value > *  p)
inline

Constraint: arbitrary segment constraint.

Constraints matched addresses to those for which the chain of segment predicates return true.

Definition at line 1243 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::any ( ) const
inline

Constraint: matches anything.

The null constraint matches any mapped address.

Definition at line 1253 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::any ( )
inline

Constraint: matches anything.

The null constraint matches any mapped address.

Definition at line 1256 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
AddressMapConstraints<const AddressMap> Sawyer::Container::AddressMap< A, T >::none ( ) const
inline

Constraint: matches nothing.

Constrains addresses so that none of them can match.

Definition at line 1266 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::none().

template<class A, class T = boost::uint8_t>
AddressMapConstraints<AddressMap> Sawyer::Container::AddressMap< A, T >::none ( )
inline

Constraint: matches nothing.

Constrains addresses so that none of them can match.

Definition at line 1269 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
void Sawyer::Container::AddressMap< A, T >::checkConsistency ( ) const
inline

Check map consistency.

Performs the following consistency checks and throws an std::runtime_error if something is wrong.

  • A segment should not have a null buffer pointer.
  • Checks that the buffers of the map are appropriate sizes for the address interval in which they're mapped.

Definition at line 1281 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::read(), and Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::write().

template<class A, class T = boost::uint8_t>
Address Sawyer::Container::AddressMap< A, T >::nSegments ( ) const
inline

Number of segments contained in the map.

Multiple segments may be pointing to the same underlying buffer, and the number of segments is not necessarily the same as the net number of segments inserted and erased. For instance, if a segment is inserted for addresses [0,99] and then a different segment is inserted at [50,59], the map will contain three segments at addresses [0,49], [50,59], and [60,99], although the first and third segment point into different parts of the same buffer.

Definition at line 1306 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
boost::iterator_range<SegmentIterator> Sawyer::Container::AddressMap< A, T >::segments ( )
inline

Iterator range for all segments.

This is just an alias for the values method defined in the super class.

Definition at line 1313 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
boost::iterator_range<ConstSegmentIterator> Sawyer::Container::AddressMap< A, T >::segments ( ) const
inline

Iterator range for all segments.

This is just an alias for the values method defined in the super class.

Definition at line 1314 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
boost::iterator_range<ConstSegmentIterator> Sawyer::Container::AddressMap< A, T >::segments ( const AddressMapConstraints< const AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
) const
inline

Segments that overlap with constraints.

Returns an iterator range for the first longest sequence of segments that all at least partly satisfy the specified constraints. Constraints are always matched at the address level and the return value consists of those segments that contain at least one matched address. Constraints normally match contiguous addresses, and therefore the returned list will be segments that are contiguous. Disabling the contiguous constraint with the MATCH_NONCONTIGUOUS flag relaxes the requirement that addresses be contiguous, although it still enforces that the matched interval contains only addresses that satisfy the constraints or addresses that are not mapped.

The following example finds the first sequence of one or more segments having "IAT" as a substring in their name and returns the longest sequence at that position. The sequence is then used to remove execute permission from each segment.

typedef AddressMap<Address,Value>::Segment Segment;
BOOST_FOREACH (Segment &segment, map.substr("IAT").segments(MATCH_NONCONTIGUOUS))
segment.accessibility(segment.accessibility() & ~EXECUTABLE);

Definition at line 1337 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
boost::iterator_range<SegmentIterator> Sawyer::Container::AddressMap< A, T >::segments ( const AddressMapConstraints< AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
)
inline

Iterator range for all segments.

This is just an alias for the values method defined in the super class.

Definition at line 1346 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
boost::iterator_range<NodeIterator> Sawyer::Container::AddressMap< A, T >::nodes ( )
inline

Iterator range for nodes.

This is just an alias for the Vertices and Edges method defined in the super class. See also the overloaded method of the same name that takes a constraint and thus returns only some nodes.

Definition at line 1361 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::checkConsistency(), Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::findNode(), and Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::write().

template<class A, class T = boost::uint8_t>
boost::iterator_range<ConstNodeIterator> Sawyer::Container::AddressMap< A, T >::nodes ( ) const
inline

Iterator range for nodes.

This is just an alias for the Vertices and Edges method defined in the super class. See also the overloaded method of the same name that takes a constraint and thus returns only some nodes.

Definition at line 1362 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
boost::iterator_range<ConstNodeIterator> Sawyer::Container::AddressMap< A, T >::nodes ( const AddressMapConstraints< const AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
) const
inline

Nodes that overlap with constraints.

Returns an iterator range for the first longest sequence of interval/segment nodes that all at least partly satisfy the specified constraints. Constraints are always matched at the address level and the return value consists of those nodes that contain at least one matched address. Constraints normally match contiguous addresses, and therefore the returned list will be nodes that are contiguous. Disabling the contiguous constraint with the MATCH_NONCONTIGUOUS flag relaxes the requirement that addresses be contiguous, although it still enforces that the matched interval contains only addresses that satisfy the constraints or addresses that are not mapped.

The following example finds the first sequence of one or more segments having addresses between 1000 and 2000 and "IAT" as part of their name and prints their address interval and name:

typedef AddressMap<Address,Value>::Node Node;
BOOST_FOREACH (const Node &node, map.within(1000,2000).substr("IAT").nodes(MATCH_NONCONTIGUOUS))
std::cout <<"segment at " <<node.key() <<" named " <<node.value().name() <<"\n";

Definition at line 1385 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
boost::iterator_range<NodeIterator> Sawyer::Container::AddressMap< A, T >::nodes ( const AddressMapConstraints< AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
)
inline

Nodes that overlap with constraints.

Returns an iterator range for the first longest sequence of interval/segment nodes that all at least partly satisfy the specified constraints. Constraints are always matched at the address level and the return value consists of those nodes that contain at least one matched address. Constraints normally match contiguous addresses, and therefore the returned list will be nodes that are contiguous. Disabling the contiguous constraint with the MATCH_NONCONTIGUOUS flag relaxes the requirement that addresses be contiguous, although it still enforces that the matched interval contains only addresses that satisfy the constraints or addresses that are not mapped.

The following example finds the first sequence of one or more segments having addresses between 1000 and 2000 and "IAT" as part of their name and prints their address interval and name:

typedef AddressMap<Address,Value>::Node Node;
BOOST_FOREACH (const Node &node, map.within(1000,2000).substr("IAT").nodes(MATCH_NONCONTIGUOUS))
std::cout <<"segment at " <<node.key() <<" named " <<node.value().name() <<"\n";

Definition at line 1394 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
Optional<Address> Sawyer::Container::AddressMap< A, T >::next ( const AddressMapConstraints< const AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
) const
inline

Minimum or maximum address that satisfies constraints.

This method returns the minimum or maximum address that satisfies the constraints, depending on whether the direction is forward or backward. It is named "next" because it is often used in loops that iterate over addresses. For instance, the following loop iterates over all readable addresses one at a time (there are more efficient ways to do this).

typedef AddressMap<Address,Value> Map;
Map map = ...;
for (Address a=0; map.atOrAfter(a).require(READABLE).next().assignTo(a); ++a) {
...
if (a == map.hull().greatest())
break;
}

The conditional break at the end of the loop is to handle the case where a is the largest possible address, and incrementing it would result in an overflow back to a smaller address. The hull method returns in constant time, but a slightly faster test (that is also more self-documenting) is:

if (a == boost::integer_traits<Address>::const_max)
break;

Backward iterating is similar:

typedef AddressMap<Address,Value> Map;
Map map = ...;
for (Address a=map.hull().greatest(); map.atOrBefore(a).require(READABLE).next(MATCH_BACKWARD).assignTo(a); --a) {
...
if (a == map.hull().least())
break;
}

Definition at line 1441 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::exists().

template<class A, class T = boost::uint8_t>
Sawyer::Container::Interval<Address> Sawyer::Container::AddressMap< A, T >::available ( const AddressMapConstraints< const AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
) const
inline

Adress interval that satisfies constraints.

Returns the lowest or highest (depending on direction) largest address interval that satisfies the specified constraints. The interval can be contiguous (the default), or it may contain unmapped addresses. In any case, all mapped addresses in the returned interval satisfy the constraints.

Definition at line 1455 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
bool Sawyer::Container::AddressMap< A, T >::exists ( const AddressMapConstraints< const AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
) const
inline

Determines if an address exists with the specified constraints.

Checking for existence is just a wrapper around next. For instance, these two statements both check whether the address 1000 exists and has execute permission:

if (map.at(1000).require(EXECUTABLE).exists()) ...
if (map.at(1000).require(EXECUTABLE).next()) ...

Definition at line 1471 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
ConstNodeIterator Sawyer::Container::AddressMap< A, T >::findNode ( const AddressMapConstraints< const AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
) const
inline

Find node containing address.

Finds the node that contains the first (or last, depending on direction) address that satisfies the constraints.

Definition at line 1480 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
NodeIterator Sawyer::Container::AddressMap< A, T >::findNode ( const AddressMapConstraints< AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
)
inline

Find node containing address.

Finds the node that contains the first (or last, depending on direction) address that satisfies the constraints.

Definition at line 1483 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
Sawyer::Container::Interval<Address> Sawyer::Container::AddressMap< A, T >::unmapped ( Address  boundary,
MatchFlags  flags = 0 
) const
inline

Find unmapped interval.

Searches for the lowest (or highest if direction is MATCH_BACKWARD) interval that is not mapped and returns its address and size. The returned interval will not contain addresses that are less than (or greater than) than boundary. If no such unmapped intervals exist then the empty interval is returned.

This method does not use constraints since it searches for addresses that do not exist in the map.

Definition at line 1496 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::findFreeSpace().

template<class A, class T = boost::uint8_t>
Optional<Address> Sawyer::Container::AddressMap< A, T >::findFreeSpace ( size_t  nValues,
size_t  alignment = 1,
Sawyer::Container::Interval< Address restriction = Sawyer::Container::Interval<Address>::whole(),
MatchFlags  flags = 0 
) const
inline

Find free space.

Finds a suitable region of unmapped address space in which nValues values can be mapped. The return value is either an address where the values can be mapped, or nothing if no such unmapped region is available. The restriction can be used to restrict which addresses are considered. The return value will have the specified alignment and will be either the lowest or highest possible address depending on whether direction is forward or backward.

This method does not use constraints since it searches for addresses that do not exist in the map.

Definition at line 1509 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
template<typename Functor >
void Sawyer::Container::AddressMap< A, T >::traverse ( Functor &  functor,
const AddressMapConstraints< const AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
) const
inline

Invoke a function on each address interval.

The functor is invoked with the following arguments: the memory map and an interval. If the functor returns false then the traversal is terminated. To facilitate the use of function-local types for the functor without requiring the use of explicit template parameters, one may pass a subclass of Visitor as the functor.

This example shows one way to print the names of segments that overlap with a given interval:

typedef AddressMap<unsigned, char> Map;
struct: Visitor {
bool operator()(const Map &map, const Interval<unsigned> &interval) {
const Map::Segment &segment = map.at(interval.least()).findNode()->value();
std::cerr <<"segment \"" <<segment.name() <<"\"\n";
return true;
}
} visitor;
Map map = ...;
Interval<unsigned> where = ...;
map.within(where).traverse(visitor);

Definition at line 1589 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
template<typename Functor >
void Sawyer::Container::AddressMap< A, T >::traverse ( Functor &  functor,
const AddressMapConstraints< AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
)
inline

Invoke a function on each address interval.

The functor is invoked with the following arguments: the memory map and an interval. If the functor returns false then the traversal is terminated. To facilitate the use of function-local types for the functor without requiring the use of explicit template parameters, one may pass a subclass of Visitor as the functor.

This example shows one way to print the names of segments that overlap with a given interval:

typedef AddressMap<unsigned, char> Map;
struct: Visitor {
bool operator()(const Map &map, const Interval<unsigned> &interval) {
const Map::Segment &segment = map.at(interval.least()).findNode()->value();
std::cerr <<"segment \"" <<segment.name() <<"\"\n";
return true;
}
} visitor;
Map map = ...;
Interval<unsigned> where = ...;
map.within(where).traverse(visitor);

Definition at line 1600 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
void Sawyer::Container::AddressMap< A, T >::traverse ( Visitor visitor,
const AddressMapConstraints< const AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
) const
inline

Invoke a function on each address interval.

The functor is invoked with the following arguments: the memory map and an interval. If the functor returns false then the traversal is terminated. To facilitate the use of function-local types for the functor without requiring the use of explicit template parameters, one may pass a subclass of Visitor as the functor.

This example shows one way to print the names of segments that overlap with a given interval:

typedef AddressMap<unsigned, char> Map;
struct: Visitor {
bool operator()(const Map &map, const Interval<unsigned> &interval) {
const Map::Segment &segment = map.at(interval.least()).findNode()->value();
std::cerr <<"segment \"" <<segment.name() <<"\"\n";
return true;
}
} visitor;
Map map = ...;
Interval<unsigned> where = ...;
map.within(where).traverse(visitor);

Definition at line 1610 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
void Sawyer::Container::AddressMap< A, T >::traverse ( Visitor visitor,
const AddressMapConstraints< AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
)
inline

Invoke a function on each address interval.

The functor is invoked with the following arguments: the memory map and an interval. If the functor returns false then the traversal is terminated. To facilitate the use of function-local types for the functor without requiring the use of explicit template parameters, one may pass a subclass of Visitor as the functor.

This example shows one way to print the names of segments that overlap with a given interval:

typedef AddressMap<unsigned, char> Map;
struct: Visitor {
bool operator()(const Map &map, const Interval<unsigned> &interval) {
const Map::Segment &segment = map.at(interval.least()).findNode()->value();
std::cerr <<"segment \"" <<segment.name() <<"\"\n";
return true;
}
} visitor;
Map map = ...;
Interval<unsigned> where = ...;
map.within(where).traverse(visitor);

Definition at line 1613 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
Sawyer::Container::Interval<Address> Sawyer::Container::AddressMap< A, T >::read ( Value buf,
const AddressMapConstraints< const AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
) const
inline

Reads data into the supplied buffer.

Reads data into an array or STL vector according to the specified constraints. If the array is a null pointer then no data is read or copied and the return value indicates what addresses would have been accessed. When the buffer is an STL vector the constraints are augmented by also limiting the number of items accessed; the caller must do that explicitly for arrays. The return value is the interval of addresses that were read.

The constraints are usually curried before the actual read call, as in this example that reads up to 10 values starting at some address and returns the number of values read:

Value buf[10];
size_t nRead = map.at(start).limit(10).read(buf).size();

The following loop reads and prints all the readable values from a memory map using a large buffer for efficiency:

std::vector<Value> buf(1024);
while (Interval<Address> accessed = map.atOrAfter(a).read(buf)) {
a = accessed.least();
BOOST_FOREACH (const Value &v, buf)
std::cout <<a++ <<": " <<v <<"\n";
if (accessed.greatest()==map.hull().greatest())
break; // to handle case when a++ overflowed
}

Reading can also be performed backward, such as this example that reads up to ten values such that the last value read is at address 999. The buffer will always contain results in address order, with the first element of the buffer being the value that was read with the lowest address.

Value buf[10];
size_t nRead = map.at(999).limit(10).read(buf, MATCH_BACKWARD).size();

Definition at line 1657 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::read().

template<class A, class T = boost::uint8_t>
Sawyer::Container::Interval<Address> Sawyer::Container::AddressMap< A, T >::read ( std::vector< Value > &  buf,
const AddressMapConstraints< const AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
) const
inline

Reads data into the supplied buffer.

Reads data into an array or STL vector according to the specified constraints. If the array is a null pointer then no data is read or copied and the return value indicates what addresses would have been accessed. When the buffer is an STL vector the constraints are augmented by also limiting the number of items accessed; the caller must do that explicitly for arrays. The return value is the interval of addresses that were read.

The constraints are usually curried before the actual read call, as in this example that reads up to 10 values starting at some address and returns the number of values read:

Value buf[10];
size_t nRead = map.at(start).limit(10).read(buf).size();

The following loop reads and prints all the readable values from a memory map using a large buffer for efficiency:

std::vector<Value> buf(1024);
while (Interval<Address> accessed = map.atOrAfter(a).read(buf)) {
a = accessed.least();
BOOST_FOREACH (const Value &v, buf)
std::cout <<a++ <<": " <<v <<"\n";
if (accessed.greatest()==map.hull().greatest())
break; // to handle case when a++ overflowed
}

Reading can also be performed backward, such as this example that reads up to ten values such that the last value read is at address 999. The buffer will always contain results in address order, with the first element of the buffer being the value that was read with the lowest address.

Value buf[10];
size_t nRead = map.at(999).limit(10).read(buf, MATCH_BACKWARD).size();

Definition at line 1680 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
Sawyer::Container::Interval<Address> Sawyer::Container::AddressMap< A, T >::write ( const Value buf,
const AddressMapConstraints< AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
)
inline

Writes data from the supplied buffer.

Copies data from an array or STL vector into the underlying address map buffers corresponding to the specified constraints. If the array is a null pointer then no data is written and the return value indicates what addresses would have been accessed. The constraints are agumented by also requiring that the addresses be contiguous and lack the IMMUTABLE bit, and in the case of STL vectors that not more data is written thn what is in the vector. The return value is the interval of addresses that were written.

The Access::IMMUTABLE bit is usually used to indicate that a buffer cannot be modified (for instance, the buffer is memory allocated with read-only access by POSIX mmap).

The constraints are usually curried before the actual read call, as in this example that writes the vector's values into the map at the first writable address greater than or equal to 1000.

std::vector<Value> buffer = {...};
Interval<Address> written = map.atOrAfter(1000).require(WRITABLE).write(buffer);

Writing can also be performed backward, such as this example that writes up to ten values such that the last value written is at address 999. The buffer contains values in their address order.

Value buf[10] = { ... };
size_t nWritten = map.at(999).limit(10).write(buf, MATCH_BACKWARD).size();

Definition at line 1718 of file AddressMap.h.

Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::write().

template<class A, class T = boost::uint8_t>
Sawyer::Container::Interval<Address> Sawyer::Container::AddressMap< A, T >::write ( const std::vector< Value > &  buf,
const AddressMapConstraints< AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
)
inline

Writes data from the supplied buffer.

Copies data from an array or STL vector into the underlying address map buffers corresponding to the specified constraints. If the array is a null pointer then no data is written and the return value indicates what addresses would have been accessed. The constraints are agumented by also requiring that the addresses be contiguous and lack the IMMUTABLE bit, and in the case of STL vectors that not more data is written thn what is in the vector. The return value is the interval of addresses that were written.

The Access::IMMUTABLE bit is usually used to indicate that a buffer cannot be modified (for instance, the buffer is memory allocated with read-only access by POSIX mmap).

The constraints are usually curried before the actual read call, as in this example that writes the vector's values into the map at the first writable address greater than or equal to 1000.

std::vector<Value> buffer = {...};
Interval<Address> written = map.atOrAfter(1000).require(WRITABLE).write(buffer);

Writing can also be performed backward, such as this example that writes up to ten values such that the last value written is at address 999. The buffer contains values in their address order.

Value buf[10] = { ... };
size_t nWritten = map.at(999).limit(10).write(buf, MATCH_BACKWARD).size();

Definition at line 1755 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
void Sawyer::Container::AddressMap< A, T >::prune ( const AddressMapConstraints< AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
)
inline

Prune away addresses that match constraints.

Removes all addresses for which the constraints match. The addresses need not be contiguous in memory (in fact, noncontiguous is the default), and the matching segments need not be consecutive segments. In other words, the interval over which this function operates can include segments that do not satisfy the constraints (and are not pruned). For instance, to remove all segments that are writable regardless of whether other segments are interspersed:

map.require(WRITABLE).contiguous(false).prune();
See also
keep

Definition at line 1772 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
void Sawyer::Container::AddressMap< A, T >::keep ( const AddressMapConstraints< AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
)
inline

Keep only addresses that match constraints.

Keeps only those addresses that satisfy the given constraints, discarding all others. The addresses need not be contiguous (in fact, noncontiguous is the default), and the matching segments need not be consecutive segments. In other words, the interval over which this function operates can include segments that do not satisfy the constraints (and are pruned). For instance, to remove all segments that are not writable regardless of whether other segments are interspersed:

map.require(WRITABLE).contiguous(false).keep();
See also
prune

Definition at line 1799 of file AddressMap.h.

template<class A, class T = boost::uint8_t>
void Sawyer::Container::AddressMap< A, T >::changeAccess ( unsigned  requiredAccess,
unsigned  prohibitedAccess,
const AddressMapConstraints< AddressMap< A, T > > &  c,
MatchFlags  flags = 0 
)
inline

Change access bits for addresses that match constraints.

For all addresses that satisfy the specified constraints, add the requiredAccess and remove the prohibitedAccess bits. The addresses need not be contiguous (in fact, noncontiguous is the default), and the matching segments need not be consecutive segments. In other words, the interval over which this function operates can include addresses that do not satisfy the constraints and whose access bits are not modified. For instance, to add execute permission and remove write permission for all segments containing the string ".text":

map.substr(".text").changeAccess(EXECUTABLE, WRITABLE);

To set access bits to a specific value, supply the complement as the second argument. The following code changes all addresses between a specified range so that only the READABLE and WRITABLE bits are set and no others:

unsigned newAccess = READABLE | WRITABLE;
map.within(100,200).changeAccess(newAccess, ~newAccess);

Definition at line 1833 of file AddressMap.h.


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