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:
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:
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.
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:
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:
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
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:
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:
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:
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 1003 of file AddressMap.h.
#include <util/Sawyer/AddressMap.h>
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, Value > | Buffer |
| 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< Address > | next (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const |
| Minimum or maximum address that satisfies constraints. More... | |
| Sawyer::Container::Interval< Address > | available (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< Address > | unmapped (Address boundary, MatchFlags flags=0) const |
| Find unmapped interval. More... | |
| Optional< Address > | findFreeSpace (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 AddressMap > | require (unsigned x) const |
| Constraint: required access bits. More... | |
| AddressMapConstraints< AddressMap > | require (unsigned x) |
| Constraint: required access bits. More... | |
| AddressMapConstraints< const AddressMap > | prohibit (unsigned x) const |
| Constraint: prohibited access bits. More... | |
| AddressMapConstraints< AddressMap > | prohibit (unsigned x) |
| Constraint: prohibited access bits. More... | |
| AddressMapConstraints< const AddressMap > | access (unsigned x) const |
| Constraint: required and prohibited access bits. More... | |
| AddressMapConstraints< AddressMap > | access (unsigned x) |
| Constraint: required and prohibited access bits. More... | |
| AddressMapConstraints< const AddressMap > | substr (const std::string &x) const |
| Constraint: segment name substring. More... | |
| AddressMapConstraints< AddressMap > | substr (const std::string &x) |
| Constraint: segment name substring. More... | |
| AddressMapConstraints< const AddressMap > | at (Address x) const |
| Constraint: anchor point. More... | |
| AddressMapConstraints< AddressMap > | at (Address x) |
| Constraint: anchor point. More... | |
| AddressMapConstraints< const AddressMap > | at (const Sawyer::Container::Interval< Address > &x) const |
| Constraint: anchored interval. More... | |
| AddressMapConstraints< AddressMap > | at (const Sawyer::Container::Interval< Address > &x) |
| Constraint: anchored interval. More... | |
| AddressMapConstraints< const AddressMap > | limit (size_t x) const |
| Constraint: limit matched size. More... | |
| AddressMapConstraints< AddressMap > | limit (size_t x) |
| Constraint: limit matched size. More... | |
| AddressMapConstraints< const AddressMap > | atOrAfter (Address x) const |
| Constraint: address lower bound. More... | |
| AddressMapConstraints< AddressMap > | atOrAfter (Address x) |
| Constraint: address lower bound. More... | |
| AddressMapConstraints< const AddressMap > | atOrBefore (Address x) const |
| Constraint: address upper bound. More... | |
| AddressMapConstraints< AddressMap > | atOrBefore (Address x) |
| Constraint: address upper bound. More... | |
| AddressMapConstraints< const AddressMap > | within (const Sawyer::Container::Interval< Address > &x) const |
| Constraint: address lower and upper bounds. More... | |
| AddressMapConstraints< AddressMap > | within (const Sawyer::Container::Interval< Address > &x) |
| Constraint: address lower and upper bounds. More... | |
| AddressMapConstraints< const AddressMap > | within (Address x, Address y) const |
| Constraint: address lower and upper bounds. More... | |
| AddressMapConstraints< AddressMap > | within (Address x, Address y) |
| Constraint: address lower and upper bounds. More... | |
| AddressMapConstraints< const AddressMap > | baseSize (Address base, Address size) const |
| Constraint: address lower and upper bounds. More... | |
| AddressMapConstraints< AddressMap > | baseSize (Address base, Address size) |
| Constraint: address lower and upper bounds. More... | |
| AddressMapConstraints< const AddressMap > | after (Address x) const |
| Constraint: address lower bound. More... | |
| AddressMapConstraints< AddressMap > | after (Address x) |
| Constraint: address lower bound. More... | |
| AddressMapConstraints< const AddressMap > | before (Address x) const |
| Constraint: address upper bound. More... | |
| AddressMapConstraints< AddressMap > | before (Address x) |
| Constraint: address upper bound. More... | |
| AddressMapConstraints< const AddressMap > | singleSegment () const |
| Constraint: single segment. More... | |
| AddressMapConstraints< AddressMap > | singleSegment () |
| Constraint: single segment. More... | |
| AddressMapConstraints< const AddressMap > | segmentPredicate (SegmentPredicate< Address, Value > *p) const |
| Constraint: arbitrary segment constraint. More... | |
| AddressMapConstraints< AddressMap > | segmentPredicate (SegmentPredicate< Address, Value > *p) |
| Constraint: arbitrary segment constraint. More... | |
| AddressMapConstraints< const AddressMap > | any () const |
| Constraint: matches anything. More... | |
| AddressMapConstraints< AddressMap > | any () |
| Constraint: matches anything. More... | |
| AddressMapConstraints< const AddressMap > | none () const |
| Constraint: matches nothing. More... | |
| AddressMapConstraints< AddressMap > | none () |
| Constraint: matches nothing. More... | |
| boost::iterator_range< SegmentIterator > | segments () |
| Iterator range for all segments. More... | |
| boost::iterator_range< ConstSegmentIterator > | segments () const |
| Iterator range for all segments. More... | |
| boost::iterator_range< ConstSegmentIterator > | segments (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const |
| Segments that overlap with constraints. More... | |
| boost::iterator_range< SegmentIterator > | segments (const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0) |
| Iterator range for all segments. More... | |
| boost::iterator_range< NodeIterator > | nodes () |
| Iterator range for nodes. More... | |
| boost::iterator_range< ConstNodeIterator > | nodes () const |
| Iterator range for nodes. More... | |
| boost::iterator_range< ConstNodeIterator > | nodes (const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const |
| Nodes that overlap with constraints. More... | |
| boost::iterator_range< NodeIterator > | nodes (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< Address > | read (Value *buf, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const |
| Reads data into the supplied buffer. More... | |
| Sawyer::Container::Interval< Address > | read (std::vector< Value > &buf, const AddressMapConstraints< const AddressMap > &c, MatchFlags flags=0) const |
| Reads data into the supplied buffer. More... | |
| Sawyer::Container::Interval< Address > | write (const Value *buf, const AddressMapConstraints< AddressMap > &c, MatchFlags flags=0) |
| Writes data from the supplied buffer. More... | |
| Sawyer::Container::Interval< Address > | write (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... | |
| IntervalMap & | operator= (const IntervalMap< Interval2, T2, Policy2 > &other) |
| Assignment operator. More... | |
| boost::iterator_range< ConstIntervalIterator > | intervals () 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< Value > | getOptional (const typename Interval::Value &scalar) const |
| Lookup and return a value or nothing. More... | |
| const Value & | getOrDefault (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 | overlaps (const Interval &interval) const |
| bool | overlaps (const IntervalMap< Interval, T2, Policy2 > &other) const |
| 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< NodeIterator > | nodes () |
| Iterators for traversing nodes. More... | |
| boost::iterator_range< ConstNodeIterator > | nodes () const |
| Iterators for traversing nodes. More... | |
| boost::iterator_range< ValueIterator > | values () |
| Iterators for traversing values. More... | |
| boost::iterator_range< ConstValueIterator > | values () 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 Value & | operator[] (const typename Interval::Value &scalar) const |
| Returns a reference to an existing value. More... | |
| const Value & | get (const typename Interval::Value &scalar) const |
| Returns a reference to an existing value. More... | |
| Value & | getOrElse (const typename Interval::Value &scalar, Value &dflt) |
| Lookup and return a value or something else. More... | |
| const Value & | getOrElse (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< NodeIterator > | findAll (const Interval &interval) |
| Finds all nodes overlapping the specified interval. More... | |
| boost::iterator_range< ConstNodeIterator > | findAll (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 >::ConstNodeIterator > | findFirstOverlap (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 >::ConstNodeIterator > | findFirstOverlap (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 >::NodeIterator > | findAllImpl (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 >::ConstNodeIterator > | findFirstOverlapImpl (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
| typedef A Sawyer::Container::AddressMap< A, T >::Address |
| typedef T Sawyer::Container::AddressMap< A, T >::Value |
Type of data stored in the address space.
Definition at line 1009 of file AddressMap.h.
| typedef AddressSegment<A, T> Sawyer::Container::AddressMap< A, T >::Segment |
Type of segments stored by this map.
Definition at line 1010 of file AddressMap.h.
| typedef Super::Node Sawyer::Container::AddressMap< A, T >::Node |
Storage node containing interval/segment pair.
Definition at line 1012 of file AddressMap.h.
| typedef Super::ValueIterator Sawyer::Container::AddressMap< A, T >::SegmentIterator |
Iterates over segments in the map.
Definition at line 1013 of file AddressMap.h.
| typedef Super::ConstValueIterator Sawyer::Container::AddressMap< A, T >::ConstSegmentIterator |
Iterators over segments in the map.
Definition at line 1014 of file AddressMap.h.
| typedef Super::ConstIntervalIterator Sawyer::Container::AddressMap< A, T >::ConstIntervalIterator |
Iterates over address intervals in the map.
Definition at line 1015 of file AddressMap.h.
| typedef Super::NodeIterator Sawyer::Container::AddressMap< A, T >::NodeIterator |
Iterates over address interval, segment pairs in the map.
Definition at line 1016 of file AddressMap.h.
| typedef Super::ConstNodeIterator Sawyer::Container::AddressMap< A, T >::ConstNodeIterator |
Iterates over address interval/segment pairs in the map.
Definition at line 1017 of file AddressMap.h.
Constructor & Destructor Documentation
|
inline |
Constructs an empty address map.
Definition at line 1029 of file AddressMap.h.
|
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 1046 of file AddressMap.h.
Member Function Documentation
|
inline |
Constraint: required access bits.
Constrains address to those that have all of the access bits that are set in x.
Definition at line 1060 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::require().
|
inline |
Constraint: required access bits.
Constrains address to those that have all of the access bits that are set in x.
Definition at line 1063 of file AddressMap.h.
|
inline |
Constraint: prohibited access bits.
Constrains addresses to those that have none of the access bits that are set in x.
Definition at line 1073 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::prohibit().
|
inline |
Constraint: prohibited access bits.
Constrains addresses to those that have none of the access bits that are set in x.
Definition at line 1076 of file AddressMap.h.
|
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 1087 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::access().
|
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 1090 of file AddressMap.h.
|
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 1100 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::substr().
|
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 1103 of file AddressMap.h.
|
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 1114 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::at().
|
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 1117 of file AddressMap.h.
|
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:
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 1141 of file AddressMap.h.
|
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:
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 1144 of file AddressMap.h.
|
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 1155 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::limit().
|
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 1158 of file AddressMap.h.
|
inline |
Constraint: address lower bound.
Constrains matched addresses so that they are all greater than or equal to x.
Definition at line 1168 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::atOrAfter().
|
inline |
Constraint: address lower bound.
Constrains matched addresses so that they are all greater than or equal to x.
Definition at line 1171 of file AddressMap.h.
|
inline |
Constraint: address upper bound.
Constrains matched addresses so that they are all less than or equal to x.
Definition at line 1181 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::atOrBefore().
|
inline |
Constraint: address upper bound.
Constrains matched addresses so that they are all less than or equal to x.
Definition at line 1184 of file AddressMap.h.
|
inline |
Constraint: address lower and upper bounds.
Constrains matched addresses so they are all within the specified interval.
Definition at line 1194 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::within().
|
inline |
Constraint: address lower and upper bounds.
Constrains matched addresses so they are all within the specified interval.
Definition at line 1197 of file AddressMap.h.
|
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 1207 of file AddressMap.h.
|
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 1210 of file AddressMap.h.
|
inline |
Constraint: address lower and upper bounds.
Specifies lower and upper bounds. The upper bound is specified indirectly by a size.
Definition at line 1220 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::baseSize().
|
inline |
Constraint: address lower and upper bounds.
Specifies lower and upper bounds. The upper bound is specified indirectly by a size.
Definition at line 1223 of file AddressMap.h.
|
inline |
Constraint: address lower bound.
Constrains matched addresses so that they are all greater than x.
Definition at line 1233 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::after().
|
inline |
Constraint: address lower bound.
Constrains matched addresses so that they are all greater than x.
Definition at line 1236 of file AddressMap.h.
|
inline |
Constraint: address upper bound.
Constrains matched addresses so that they are all less than x.
Definition at line 1246 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::before().
|
inline |
Constraint: address upper bound.
Constrains matched addresses so that they are all less than x.
Definition at line 1249 of file AddressMap.h.
|
inline |
Constraint: single segment.
Constrains matched addresses so that they all come from the same segment.
Definition at line 1259 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::singleSegment().
|
inline |
Constraint: single segment.
Constrains matched addresses so that they all come from the same segment.
Definition at line 1262 of file AddressMap.h.
|
inline |
Constraint: arbitrary segment constraint.
Constraints matched addresses to those for which the chain of segment predicates return true.
Definition at line 1272 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::segmentPredicate().
|
inline |
Constraint: arbitrary segment constraint.
Constraints matched addresses to those for which the chain of segment predicates return true.
Definition at line 1275 of file AddressMap.h.
|
inline |
Constraint: matches anything.
The null constraint matches any mapped address.
Definition at line 1285 of file AddressMap.h.
|
inline |
Constraint: matches anything.
The null constraint matches any mapped address.
Definition at line 1288 of file AddressMap.h.
|
inline |
Constraint: matches nothing.
Constrains addresses so that none of them can match.
Definition at line 1298 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::none().
|
inline |
Constraint: matches nothing.
Constrains addresses so that none of them can match.
Definition at line 1301 of file AddressMap.h.
|
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 1313 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().
|
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 1338 of file AddressMap.h.
|
inline |
Iterator range for all segments.
This is just an alias for the values method defined in the super class.
Definition at line 1345 of file AddressMap.h.
|
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.
|
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.
Definition at line 1369 of file AddressMap.h.
|
inline |
Iterator range for all segments.
This is just an alias for the values method defined in the super class.
Definition at line 1378 of file AddressMap.h.
|
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 1393 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().
|
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 1394 of file AddressMap.h.
|
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:
Definition at line 1417 of file AddressMap.h.
|
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:
Definition at line 1426 of file AddressMap.h.
|
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).
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:
Backward iterating is similar:
Definition at line 1473 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::exists().
|
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 1487 of file AddressMap.h.
|
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:
Definition at line 1503 of file AddressMap.h.
|
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 1512 of file AddressMap.h.
|
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 1515 of file AddressMap.h.
|
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 1528 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::findFreeSpace().
|
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 1541 of file AddressMap.h.
|
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:
Definition at line 1623 of file AddressMap.h.
|
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:
Definition at line 1634 of file AddressMap.h.
|
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:
Definition at line 1644 of file AddressMap.h.
|
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:
Definition at line 1647 of file AddressMap.h.
|
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:
The following loop reads and prints all the readable values from a memory map using a large buffer for efficiency:
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.
Definition at line 1691 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::read().
|
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:
The following loop reads and prints all the readable values from a memory map using a large buffer for efficiency:
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.
Definition at line 1714 of file AddressMap.h.
|
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.
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.
Definition at line 1752 of file AddressMap.h.
Referenced by Sawyer::Container::AddressMap< rose_addr_t, uint8_t >::write().
|
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.
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.
Definition at line 1789 of file AddressMap.h.
|
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:
- See also
- keep
Definition at line 1806 of file AddressMap.h.
|
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:
- See also
- prune
Definition at line 1833 of file AddressMap.h.
|
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":
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:
Definition at line 1867 of file AddressMap.h.
The documentation for this class was generated from the following file:
