Memory mapping object which maps addresses onto block-aligned destinations, each of which is a BlockingMemoryIF object. This method does not actually support memory accesses, only mapping and querying. More...

#include <SimpleMemoryMap.hpp>

Inheritance diagram for sparta::memory::SimpleMemoryMap:

[legend]

Classes
struct	Mapping
	Represents a mapping between an input address and output address for use in a destination BlockingMemoryIF. More...

Public Member Functions
std::string	stringize (bool pretty=false) const
	Render description of this SimpleMemoryMap as a string.

Construction
	SimpleMemoryMap (addr_t block_size)
	Construct a SimpleMemoryMap.

virtual	~SimpleMemoryMap ()
	Destructor.

Mapping Interface
void	addMapping (addr_t start, addr_t end, BlockingMemoryIF *memif, addr_t dest_start)
	Create a mapping from addresses entering this object to a destination memory interface.

void	dumpTree (std::ostream &o) const
	Dumps the tree to an ostream like a directory listing.

void	dumpMappings (std::ostream &o) const
	Dumps a list of mappings to an ostream with a newline after each mapping entry.

BlockingMemoryIF *	findInterface (addr_t addr)
	Returns the destination memory interface associated with a mapping containing an address.

Mapping *	findMapping (addr_t addr)
	Finds the Mapping object associated with an address.

const Mapping *	findMapping (addr_t addr) const

void	verifyHasMapping (addr_t addr, addr_t size) const
	Determines if a mapping is valid or not.

std::pair< const BlockingMemoryIF *, addr_t >	mapAddress (addr_t addr) const noexcept
	Maps an input address to a destination interface and address within that destination interface.

uint32_t	getNumMappings () const
	Returns the number of mappings successfully added to this map.

const std::vector< const Mapping * > &	getMappings () const
	Returns the vector of current mappings in the order added.

Attributes
addr_t	getBlockSize () const
	Returns the block size of memory represented by this interface. Read and write accesses must not span block boundaries (where addr % block_size == 0).

Detailed Description

Memory mapping object which maps addresses onto block-aligned destinations, each of which is a BlockingMemoryIF object. This method does not actually support memory accesses, only mapping and querying.

Mapping is performed within this map and is invisible to clients of this class. Internal mapping is not considered a translation and there is no TranslationIF associated with the internals mapping of this class.

Mapped ranges can be added only (not removed), cannot overlap, can, however, map to overlapping ranges on the same destination memory.

All mappings are Affine and contiguous. For mapping multiple regions to the same object or mapping one range to discontinuous or overlapping ranges in a destination memory object, use separate mappings.

Implemented as a red-black tree to balance the tree and make lookups more consistently log(n).

Example

using sparta::memory;
// SimpleMemoryMap* smm;
// BlockingMemoryIF* mem1;
// BlockingMemoryIF* mem2;
smm->addMapping(0x200,0x240,mem1,0);
smm->addMapping(0x240,0x280,mem2,0);
 
BlockingMemoryIF* bmi = smm->findInterface(paddr);
assert(bmi == mem1);
cout << "Addr 0x" << paddr << std::dec << " went to: " << bmi->getDescription();

Definition at line 53 of file SimpleMemoryMap.hpp.

Constructor & Destructor Documentation

◆ SimpleMemoryMap()

sparta::memory::SimpleMemoryMap::SimpleMemoryMap ( addr_t block_size )

inline

Construct a SimpleMemoryMap.

Parameters

block_size Size of blocks in mapping. Must match or be smaller than all BlockingMemoryIF instances to which this object will maps. Must be a power of 2 and greater than 0

Definition at line 149 of file SimpleMemoryMap.hpp.

◆ ~SimpleMemoryMap()

virtual sparta::memory::SimpleMemoryMap::~SimpleMemoryMap ( )

inlinevirtual

Destructor.

Definition at line 162 of file SimpleMemoryMap.hpp.

Member Function Documentation

◆ addMapping()

void sparta::memory::SimpleMemoryMap::addMapping	(	addr_t	start,
		addr_t	end,
		BlockingMemoryIF *	memif,
		addr_t	dest_start
	)

inline

Create a mapping from addresses entering this object to a destination memory interface.

Parameters

start	Start address of mapping region. Must be block-aligned
end	End address (exclusive) of mapping region. Must be block-aligned. Must be > start (mapping must be 1 or more bytes). The range defined by [start,end) cannot overlap any other mapping range already added to this object. Edges may be shared though (e.g. range 1 end can equal range 2 start).
memif	Memory interface to which accesses in the range defined by [start,end) will be forwarded with the new address of: address - start + dest_start. The block size (BlockingMemoryIF::getBlockSize) of this interface must be exactly the size of this SimpleMemoryMap block size. Requiring the block size to be equal means that no legal accesses can be made through this interface which span blocks in destination memory interfaces. This allows this class to avoid testing for mapping-spanning accesses because the destination interfaces are expected to reject them. If a destination BlockingMemoryIF were to violate this assumption, an access could be made through this map which spanned blocks and thus spanned mapping ranges - this would be undesirable behavior.
dest_start	Added address offset at destination. Must be a multiple of block_size - effectively limits granulariry of any mapping to whole-block-to-whole-block. If dest_start were 0, accesses with an address equal to start to be forwarded to memif with an address of 0. Accesses with address = start+4 would be forwarded with an address of 4. dest_start allows this to be adjusted by adding an offset to the destination address.

Note: Validates memif to ensure that the entire range specified by [ start, end ) can actually be mapped to accessible values within; Mappings are allowed to span blocks, but endpoints must be block-aligned. By requiring this alignment, and forwarding accesses onto BlockingMemoryIFs which require non-block-spanning accesses, it is guaranteed that accesses will not span mappings in this map. This is also why dest_start must be a block multiple.; Accesses will be allowed to span blocks within this interface. It is the responsibility of the recieving memif to check accesses for block-spanning.; The minimum address that will be accessed in the destination memif is dest_start. The maximum address that will be accessed in the destination memif is dest_start + (end-start) - 1 memif must support this range of accesses

Definition at line 222 of file SimpleMemoryMap.hpp.

Here is the call graph for this function:

◆ dumpMappings()

void sparta::memory::SimpleMemoryMap::dumpMappings ( std::ostream & o ) const

inline

Dumps a list of mappings to an ostream with a newline after each mapping entry.

Parameters

o	ostream to which mappings will be printed

Definition at line 443 of file SimpleMemoryMap.hpp.

◆ dumpTree()

void sparta::memory::SimpleMemoryMap::dumpTree ( std::ostream & o ) const

inline

Dumps the tree to an ostream like a directory listing.

Parameters

o	ostream to which tree will be printed

Definition at line 432 of file SimpleMemoryMap.hpp.

◆ findInterface()

BlockingMemoryIF * sparta::memory::SimpleMemoryMap::findInterface ( addr_t addr )

inline

Returns the destination memory interface associated with a mapping containing an address.

Returns: Memory interface for the mapping containing this address. If not found, returns nullptr.

Definition at line 479 of file SimpleMemoryMap.hpp.

Here is the call graph for this function:

◆ findMapping() [1/2]

Mapping * sparta::memory::SimpleMemoryMap::findMapping ( addr_t addr )

inline

Finds the Mapping object associated with an address.

Returns: Mapping associated with an address if address is contained in a mapping. If not found, returns nullptr.

Definition at line 492 of file SimpleMemoryMap.hpp.

◆ findMapping() [2/2]

const Mapping * sparta::memory::SimpleMemoryMap::findMapping ( addr_t addr ) const

inline

const-qualified version of findMapping

Definition at line 524 of file SimpleMemoryMap.hpp.

◆ getBlockSize()

addr_t sparta::memory::SimpleMemoryMap::getBlockSize ( ) const

inline

Returns the block size of memory represented by this interface. Read and write accesses must not span block boundaries (where addr % block_size == 0).

Definition at line 644 of file SimpleMemoryMap.hpp.

◆ getMappings()

const std::vector< const Mapping * > & sparta::memory::SimpleMemoryMap::getMappings ( ) const

inline

Returns the vector of current mappings in the order added.

Definition at line 628 of file SimpleMemoryMap.hpp.

◆ getNumMappings()

uint32_t sparta::memory::SimpleMemoryMap::getNumMappings ( ) const

inline

Returns the number of mappings successfully added to this map.

Definition at line 621 of file SimpleMemoryMap.hpp.

◆ mapAddress()

std::pair< const BlockingMemoryIF *, addr_t > sparta::memory::SimpleMemoryMap::mapAddress ( addr_t addr ) const

inlinenoexcept

Maps an input address to a destination interface and address within that destination interface.

Parameters

add	Input address to map

Returns: Pair containing destination BlockingMemoryIF and an address within that interface If no mapping is found for the given address, the memory interface (first) will be nullptr

Note: As long as accesses to the resulting destination are constrained to blocks, the result can be cached for future accesses of any size provided that they are within the same block as the resulting address

Example:

// uint8_t data[12];
auto mapping = map.mapAddress(0xf3);
if(mapping.first != nullptr){
  mapping.first.write(mapping.second, 12, data);
}

Definition at line 609 of file SimpleMemoryMap.hpp.

Here is the call graph for this function:

◆ stringize()

std::string sparta::memory::SimpleMemoryMap::stringize ( bool pretty = false ) const

inline

Render description of this SimpleMemoryMap as a string.

Definition at line 652 of file SimpleMemoryMap.hpp.

◆ verifyHasMapping()

void sparta::memory::SimpleMemoryMap::verifyHasMapping	(	addr_t	addr,
		addr_t	size
	)		const

inline

Determines if a mapping is valid or not.

Exceptions

MemoryAccessError if mapping is not valid

Note that normal read/write paths may not perform a check this careful for performance reasons

Definition at line 559 of file SimpleMemoryMap.hpp.

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

/github/workspace/sparta/sparta/memory/SimpleMemoryMap.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SimpleMemoryMap()

◆ ~SimpleMemoryMap()

Member Function Documentation

◆ addMapping()

◆ dumpMappings()

◆ dumpTree()

◆ findInterface()

◆ findMapping() [1/2]

◆ findMapping() [2/2]

◆ getBlockSize()

◆ getMappings()

◆ getNumMappings()

◆ mapAddress()

◆ stringize()

◆ verifyHasMapping()