#include <MemoryMap.h>
The source bytes can be bytes of a file, bytes stored in some memory buffer, or bytes initialized to zero and are described by the MemoryMap::MapElement class. The mapping can be built piecemeal and the data structure will coalesce adjacent memory areas when possible. If an attempt is made to define a mapping from a virtual address to multiple source bytes then an exception is raised.
Public Types | |
| typedef std::map< std::string, std::set< std::string > > | NamePairings |
| Data structure for memory map names. | |
| MM_PROT_BITS = 0x00000007 | |
| Bits used to indication memory region protections. | |
| MM_PROT_READ = 0x00000001 | |
| Pages can be read. | |
| MM_PROT_WRITE = 0x00000002 | |
| Pages can be written. | |
| MM_PROT_EXEC = 0x00000004 | |
| Pages can be executed. | |
| MM_PROT_NONE = 0x00000000 | |
| Pages cannot be accessed. | |
| MM_PROT_ANY = 0x00000007 | |
| Any access. | |
| MM_PROT_RW = (MM_PROT_READ|MM_PROT_WRITE) | |
| Read or write. | |
| MM_PROT_RX = (MM_PROT_READ|MM_PROT_EXEC) | |
| Read or execute. | |
| MM_PROT_RWX = (MM_PROT_ANY) | |
| MM_PROT_FLAGS = 0xfffffff0 | |
| Mask of protection bits that are available for use by other layers. | |
| MM_PROT_PRIVATE = 0x00000010 | |
| Pages are not shared between mapped regions. | |
| enum | Protection { MM_PROT_BITS = 0x00000007, MM_PROT_READ = 0x00000001, MM_PROT_WRITE = 0x00000002, MM_PROT_EXEC = 0x00000004, MM_PROT_NONE = 0x00000000, MM_PROT_ANY = 0x00000007, MM_PROT_RW = (MM_PROT_READ|MM_PROT_WRITE), MM_PROT_RX = (MM_PROT_READ|MM_PROT_EXEC), MM_PROT_RWX = (MM_PROT_ANY), MM_PROT_FLAGS = 0xfffffff0, MM_PROT_PRIVATE = 0x00000010 } |
| Mapping permissions. More... | |
Public Member Functions | |
| MemoryMap () | |
| void | clear () |
| Clear the entire memory map by erasing all addresses that are defined. | |
| void | insert (MapElement elmt) |
| Insert the specified map element. | |
| void | erase (MapElement elmt) |
| Erase parts of the mapping that correspond to the specified virtual address range. | |
| const MapElement * | find (rose_addr_t va) const |
| Search for the specified virtual address and return the map element that contains it. | |
| rose_addr_t | find_free (rose_addr_t start_va, size_t size, rose_addr_t mem_alignment=1) const |
| Search for free space in the mapping. | |
| rose_addr_t | find_last_free (rose_addr_t max=(rose_addr_t)(-1)) const |
| Finds the highest area of unmapped addresses. | |
| const std::vector< MapElement > & | get_elements () const |
| Returns the currently defined map elements sorted by virtual address. | |
| void | prune (bool(*predicate)(const MapElement &)) |
Prunes the map elements by removing those for which predicate returns true. | |
| void | prune (unsigned required, unsigned prohibited=MM_PROT_NONE) |
| Prunes away map elements based on permissions. | |
| size_t | read (void *dst_buf, rose_addr_t start_va, size_t desired, unsigned req_perms=MM_PROT_READ) const |
| Copies data from a contiguous region of the virtual address space into a user supplied buffer. | |
| SgUnsignedCharList | read (rose_addr_t start_va, size_t desired, unsigned req_perms=MM_PROT_READ) const |
| Reads data from a memory map. | |
| size_t | read1 (void *dst_buf, rose_addr_t va, size_t desired, unsigned req_perms=MM_PROT_READ, const MemoryMap::MapElement **mep=NULL) const |
| Reads from a single memory segment. | |
| size_t | write (const void *src_buf, rose_addr_t start_va, size_t size, unsigned req_perms=MM_PROT_WRITE) const |
| Copies data from a supplied buffer into the specified virtual addresses. | |
| size_t | write1 (const void *src_buf, rose_addr_t va, size_t size, unsigned req_perms=MM_PROT_WRITE, const MemoryMap::MapElement **mep=NULL) const |
| Writes to a single memory segment. | |
| ExtentMap | va_extents () const |
| Returns just the virtual address extents for a memory map. | |
| void | mprotect (const MapElement &elmt, bool relax=false) |
| Sets protection bits for the specified address range. | |
| void | dump (FILE *, const char *prefix="") const |
| Prints the contents of the map for debugging. | |
| void | dump (const std::string &basename) const |
| Dumps the entire map and its contents into a set of files. | |
| bool | load (const std::string &basename) |
| Read a memory map from a set of memory dump files. | |
Private Attributes | |
| std::vector< MapElement > | elements |
| Map elements, sorted by virtual address. | |
Classes | |
| struct | Exception |
| Exceptions for MemoryMap operations. More... | |
| struct | Inconsistent |
| Exception for an inconsistent mapping. More... | |
| class | MapElement |
| A MemoryMap is composed of zero or more MapElements. More... | |
| struct | NoFreeSpace |
| Exception thrown by find_free() when there's not enough free space left. More... | |
| struct | NotMapped |
| Exception for when we try to access a virtual address that isn't mapped. More... | |
| struct | Syntax |
| Exception thrown by load() when there's a syntax error in the index file. More... | |
| typedef std::map<std::string, std::set<std::string> > MemoryMap::NamePairings |
Data structure for memory map names.
Often, memory map element names used for debugging are of the form
FILE1(NAME1a+NAME1b+...)+FILE2(NAME2a+NAME2b+...)+...
where the file names are all unique. We'd like to be able to operate on these name strings in order to do things like merging two elements. This data type facilitates these kinds of operations.
Mapping permissions.
| MemoryMap::MemoryMap | ( | ) | [inline] |
| void MemoryMap::clear | ( | ) |
Clear the entire memory map by erasing all addresses that are defined.
Erasing an address range frees reference counted anonymous mappings but not user-provided buffers.
| void MemoryMap::insert | ( | MapElement | elmt | ) |
Insert the specified map element.
Adjacent elements are coalesced when possible (see MapElement::merge()).
| void MemoryMap::erase | ( | MapElement | elmt | ) |
Erase parts of the mapping that correspond to the specified virtual address range.
The addresses to be erased don't necessarily need to correspond to a similar add() call; for instance, it's possible to add a large address space and then erase parts of it to make holes.
| const MemoryMap::MapElement * MemoryMap::find | ( | rose_addr_t | va | ) | const |
Search for the specified virtual address and return the map element that contains it.
Returns null if the address is not mapped.
| rose_addr_t MemoryMap::find_free | ( | rose_addr_t | start_va, | |
| size_t | size, | |||
| rose_addr_t | mem_alignment = 1 | |||
| ) | const |
Search for free space in the mapping.
This is done by looking for the lowest possible address not less than start_va and with the specified alignment where there are at least size free bytes. Throws a MemoryMap::NoFreeSpace exception if the search fails to find free space.
| rose_addr_t MemoryMap::find_last_free | ( | rose_addr_t | max = (rose_addr_t)(-1) |
) | const |
Finds the highest area of unmapped addresses.
The return value is the starting address of the highest contiguous region of unmapped address space that starts at or below the specified maximum. If no unmapped region exists then a MemoryMap::NoFreeSpace exception is thrown.
| const std::vector< MemoryMap::MapElement > & MemoryMap::get_elements | ( | ) | const |
Returns the currently defined map elements sorted by virtual address.
| void MemoryMap::prune | ( | bool(*)(const MapElement &) | predicate | ) |
Prunes the map elements by removing those for which predicate returns true.
| void MemoryMap::prune | ( | unsigned | required, | |
| unsigned | prohibited = MM_PROT_NONE | |||
| ) |
Prunes away map elements based on permissions.
Keeps map elements that have any of the required bits and none of the prohibited bits.
| size_t MemoryMap::read | ( | void * | dst_buf, | |
| rose_addr_t | start_va, | |||
| size_t | desired, | |||
| unsigned | req_perms = MM_PROT_READ | |||
| ) | const |
Copies data from a contiguous region of the virtual address space into a user supplied buffer.
The portion of the virtual address space to copy begins at start_va and continues for desired bytes. The data is copied into the beginning of the dst_buf buffer. The return value is the number of bytes that were copied, which might be fewer than the number of bytes desired if the mapping does not include part of the address space requested or part of the address space does not have MM_PROT_READ permission (or the specified permissions). The dst_buf bytes that do not correpond to mapped virtual addresses will be zero filled so that desired bytes are always initialized.
| SgUnsignedCharList MemoryMap::read | ( | rose_addr_t | start_va, | |
| size_t | desired, | |||
| unsigned | req_perms = MM_PROT_READ | |||
| ) | const |
Reads data from a memory map.
Reads data beginning at the start_va virtual address in the memory map and continuing for up to desired bytes, returning the result as an SgUnsignedCharList. The read may be shorter than requested if we reach a point in the memory map that is not defined or which does not have the requested permissions.
| size_t MemoryMap::read1 | ( | void * | dst_buf, | |
| rose_addr_t | va, | |||
| size_t | desired, | |||
| unsigned | req_perms = MM_PROT_READ, |
|||
| const MemoryMap::MapElement ** | mep = NULL | |||
| ) | const |
Reads from a single memory segment.
Reads up to desired bytes beginning at virtual address va from the specified memory map. Returns the number of bytes read.
If dst_buf is the null pointer, then everything described above still happens, but no data is copied.
| size_t MemoryMap::write | ( | const void * | src_buf, | |
| rose_addr_t | start_va, | |||
| size_t | size, | |||
| unsigned | req_perms = MM_PROT_WRITE | |||
| ) | const |
Copies data from a supplied buffer into the specified virtual addresses.
If part of the destination address space is not mapped, then all bytes up to that location are copied and no additional bytes are copied. The write is also aborted early if a map element is marked read-only or if its protection lacks the MM_PROT_WRITE bit (or specified bits). The return value is the number of bytes copied.
| size_t MemoryMap::write1 | ( | const void * | src_buf, | |
| rose_addr_t | va, | |||
| size_t | size, | |||
| unsigned | req_perms = MM_PROT_WRITE, |
|||
| const MemoryMap::MapElement ** | mep = NULL | |||
| ) | const |
Writes to a single memory segment.
Writes up to nbytes bytes beginning at virtual address va into the specified memory map. Returns the number of bytes written.
| ExtentMap MemoryMap::va_extents | ( | ) | const |
Returns just the virtual address extents for a memory map.
| void MemoryMap::mprotect | ( | const MapElement & | elmt, | |
| bool | relax = false | |||
| ) |
Sets protection bits for the specified address range.
The entire address range must already be mapped, but if relax is set then no exception is thrown if part of the range is not mapped (that part is just ignored).
| void MemoryMap::dump | ( | FILE * | , | |
| const char * | prefix = "" | |||
| ) | const |
Prints the contents of the map for debugging.
The prefix string is added to the beginning of every line of output and typically is used to indent the output.
| void MemoryMap::dump | ( | const std::string & | basename | ) | const |
Dumps the entire map and its contents into a set of files.
The file names are constructed from the basename by appending a hypen and a hexadecimal address (without the leading "0x") and the extension ".data". The text file whose name is constructed by appending ".index" to the basename contains an index of the memory map.
| bool MemoryMap::load | ( | const std::string & | basename | ) |
Read a memory map from a set of memory dump files.
The argument should be the same basename that was given to an invocation of the dump() method. The memory map is adjusted according to the contents of the index file. Returns true if the data was successfully read in its entirety; note that when returning false, this memory map object might be partially changed (although still in a consistent state).
This method also understands a more user-friendly dump index format. Each line of the index is either blank (containing only white space), a comment (introduced with a '#') or a map element specification. A map element specification contains the following fields separated by white space (and/or a comma):
If an error occurs an exception is thrown.
std::vector<MapElement> MemoryMap::elements [mutable, private] |
Map elements, sorted by virtual address.
1.4.7