Memory interface which represents a simple, immediately accessible (blocking) address-space with support for peek and poke acceeses having no side effects other than changing the desired memory. More...

#include <DebugMemoryIF.hpp>

Inheritance diagram for sparta::memory::DebugMemoryIF:

[legend]

Collaboration diagram for sparta::memory::DebugMemoryIF:

[legend]

Classes
struct	AccessWindow
	Defines an access window within this interface. Accesses through a memory interface are constrained to this window. More...

Public Member Functions
Construction
	DebugMemoryIF ()=delete
	Default constuctor.

	DebugMemoryIF (const std::string &desc, addr_t block_size, const AccessWindow &window, TranslationIF *transif=nullptr)
	Construct a DebugMemoryInterface.

virtual	~DebugMemoryIF ()
	Virutal destructor.

Translation Information
virtual const TranslationIF *	getTranslationIF ()
	Gets the translation interface associated with this Debug memory interface (if any).

Interface Attributes
const std::string &	getDescription ()
	Returns the description specified at construction.

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).

addr_t	getRange () const
	Gets the total span of this interface's valid address range.

addr_t	getLowEnd () const
	Gets the lowest address accessible.

addr_t	getHighEnd () const
	Gets the highest address accessible + 1.

addr_t	getAccessibleSize () const
	Gets the total accessible size of this interface's valid addresses within the total size (getRange) excluding holes between access windows.

const std::vector< AccessWindow > &	getWindows () const
	Gets the vector of windows representing this interface.

General Queries
bool	isAddressInWindows (addr_t addr) const noexcept
	Determines if the given address is in an access window defined for this interface.

void	verifyInAccessWindows (addr_t addr, addr_t size) const
	Verifies that the range [addr, addr+size) is within the access windows for this interface.

bool	isInAccessWindows (addr_t addr, addr_t size) const
	Determines if the range [addr, addr+size) is within the access windows for this interface.

void	verifyNoBlockSpan (addr_t addr, addr_t size) const
	Verifies that the given address does not span block boundaries defined for this interface.

bool	doesAccessSpan (addr_t addr, addr_t size) const noexcept
	Determines if the given address spans block boundaries defined for this interface. Accesses which span blocks are illegal for read/write accesses, but allowed for peak/poke debug accesses.

Debug Memory Access
bool	tryPeek (addr_t addr, addr_t size, uint8_t *buf) const
	Attempts to 'peek' memory without having any side effects, size-limitations, alignment constraints except that all bytes peeked are inside an access window for this interface.

void	peek (addr_t addr, addr_t size, uint8_t *buf) const
	Wrapper on tryPeek which throws a MemoryAccessError if the peek is not legal.

bool	tryPoke (addr_t addr, addr_t size, const uint8_t *buf)
	Attempts to 'poke' memory without having any side effects other than changing the bytes within the range [ addr , addr + size ). Poke has no size-limitations or alignment constraints except that all bytes peeked are inside an access window for this interface.

void	poke (addr_t addr, addr_t size, const uint8_t *buf)
	Wrapper on tryPoke which throws a MemoryAccessError if the poke is not legal.

Protected Attributes
const addr_t	block_size_
	Size of a block accessed through this interface.

addr_t	block_mask_
	Mask applied to an address to get only bits representing the block ID.

addr_t	block_idx_lsb_
	rshift applied to an address to get the block ID

const std::vector< AccessWindow >	acc_windows_
	Vector of access windows representing this memory.

TranslationIF *	trans_
	Translation interface created for this interface. Externally owned.

const std::string *const	desc_ptr_
	Description pointer.

addr_t	total_range_
	Range of addresses from highest accessible to lowest.

addr_t	low_end_
	Lowest accessible address.

addr_t	high_end_
	Highest accessible address + 1.

addr_t	accessible_size_
	Number of bytes accessible through this interface.

Detailed Description

Memory interface which represents a simple, immediately accessible (blocking) address-space with support for peek and poke acceeses having no side effects other than changing the desired memory.

This interface does not support non-blocking accesses or access attributes.

This interface operates on post-translated addresses from the TranslationIF available through getTranslationIF

The object implementing this interface can perform any translation or logic to satisfy memory accesses.

Peek and Poke accesses within this interface are automatically chunked into block-constrained accesses and re-assembled.

This class is intended to be an innocuous interface to some kind of "memory" from the perspective of some simulation unit with which this interface is associated. For example, if attached to a core this interface would most appropriately present the software view of virtual memory. Note that data and instruction memory views from a core may need to use different debugging interfaces. It is possible different interfaces could even be provided for each address-space avaialable per data and instruction depending on that core's mmu.

Example

using sparta::memory;
// DebugMemoryIF* dbgmi;
// addr_t varrd;
// const uint8_t data[4];
// uint8_t buf[4];
addr_t paddr = dbgmi->getTranslationIF()->translate(vaddr);
dbgmi->poke(paddr, 4, data);
dbgmi->peek(paddr, 4, buf);
// Note: Translation is only required if the interface does not
// represent direct access to physical memory

Definition at line 64 of file DebugMemoryIF.hpp.

Constructor & Destructor Documentation

◆ DebugMemoryIF()

sparta::memory::DebugMemoryIF::DebugMemoryIF	(	const std::string &	desc,
		addr_t	block_size,
		const AccessWindow &	window,
		TranslationIF *	transif = `nullptr`
	)

inline

Construct a DebugMemoryInterface.

Parameters

desc	Description of this interface. What is this an interface for and what is the perspective? For example, "core virtual data memory". This exists so that errors generated by this code can indicate which interface the error came from
block_size	Size of a block in this interface. Must be a power of 2 and greater than 0.
window	AccessWindow defining valid range of addresses. Must be block-aligned. These are post-translated addresses ready to be used in access methods
transif	Optional translation interface associated with this memory interface. This must be specified, is managed externally, and must exist for the lifetime of this interface

Exceptions

SpartaException if block_size or window is invalid

Todo:: Support vectors of windows with holes

Todo:: Check for access window overlaps (once multiple windows are supported)

Todo:: Create lookup map for identifying holes if more than 1 window is allowed

Definition at line 163 of file DebugMemoryIF.hpp.

◆ ~DebugMemoryIF()

virtual sparta::memory::DebugMemoryIF::~DebugMemoryIF ( )

inlinevirtual

Virutal destructor.

Definition at line 232 of file DebugMemoryIF.hpp.

Member Function Documentation

◆ doesAccessSpan()

bool sparta::memory::DebugMemoryIF::doesAccessSpan	(	addr_t	addr,
		addr_t	size
	)		const

inlinenoexcept

Determines if the given address spans block boundaries defined for this interface. Accesses which span blocks are illegal for read/write accesses, but allowed for peak/poke debug accesses.

Parameters

addr	Post-translated address to test (see getTranslationIF)
size	Size of access to test

Returns: true if access spans a block boundary, false otherwise

Definition at line 394 of file DebugMemoryIF.hpp.

◆ getAccessibleSize()

addr_t sparta::memory::DebugMemoryIF::getAccessibleSize ( ) const

inline

Gets the total accessible size of this interface's valid addresses within the total size (getRange) excluding holes between access windows.

Definition at line 300 of file DebugMemoryIF.hpp.

◆ getBlockSize()

addr_t sparta::memory::DebugMemoryIF::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 274 of file DebugMemoryIF.hpp.

◆ getDescription()

const std::string & sparta::memory::DebugMemoryIF::getDescription ( )

inline

Returns the description specified at construction.

Definition at line 267 of file DebugMemoryIF.hpp.

◆ getHighEnd()

addr_t sparta::memory::DebugMemoryIF::getHighEnd ( ) const

inline

Gets the highest address accessible + 1.

Definition at line 293 of file DebugMemoryIF.hpp.

◆ getLowEnd()

addr_t sparta::memory::DebugMemoryIF::getLowEnd ( ) const

inline

Gets the lowest address accessible.

Definition at line 288 of file DebugMemoryIF.hpp.

◆ getRange()

addr_t sparta::memory::DebugMemoryIF::getRange ( ) const

inline

Gets the total span of this interface's valid address range.

This is: 1 + the highest accessible address - the lowest accessible address.

Definition at line 283 of file DebugMemoryIF.hpp.

◆ getTranslationIF()

virtual const TranslationIF * sparta::memory::DebugMemoryIF::getTranslationIF ( )

inlinevirtual

Gets the translation interface associated with this Debug memory interface (if any).

This translation interface, if not nullptr, is intended to be used by a client of this class to translate addresses from some external space into a space suitable for use in memory accesses through this interface.

The DebugMemoryIF does not use this translation interface. This association is present as a hint for toos and UIs.

Definition at line 253 of file DebugMemoryIF.hpp.

◆ getWindows()

const std::vector< AccessWindow > & sparta::memory::DebugMemoryIF::getWindows ( ) const

inline

Gets the vector of windows representing this interface.

These windows define the post-translated access space for this interface

Definition at line 308 of file DebugMemoryIF.hpp.

◆ isAddressInWindows()

bool sparta::memory::DebugMemoryIF::isAddressInWindows ( addr_t addr ) const

inlinenoexcept

Determines if the given address is in an access window defined for this interface.

Returns: true if in some window, false otherwise

Warning: This is not a high-performance method.

See also: verifyInAccessWindows_

Definition at line 326 of file DebugMemoryIF.hpp.

◆ isInAccessWindows()

bool sparta::memory::DebugMemoryIF::isInAccessWindows	(	addr_t	addr,
		addr_t	size
	)		const

inline

Determines if the range [addr, addr+size) is within the access windows for this interface.

Parameters

addr	Post-translated address to test (see getTranslationIF)
size	Size of access to test

Returns: false if access does not fall entirely within access windows of this interface

Definition at line 363 of file DebugMemoryIF.hpp.

◆ peek()

void sparta::memory::DebugMemoryIF::peek	(	addr_t	addr,
		addr_t	size,
		uint8_t *	buf
	)		const

inline

Wrapper on tryPeek which throws a MemoryAccessError if the peek is not legal.

Definition at line 461 of file DebugMemoryIF.hpp.

Here is the call graph for this function:

◆ poke()

void sparta::memory::DebugMemoryIF::poke	(	addr_t	addr,
		addr_t	size,
		const uint8_t *	buf
	)

inline

Wrapper on tryPoke which throws a MemoryAccessError if the poke is not legal.

Definition at line 531 of file DebugMemoryIF.hpp.

Here is the call graph for this function:

◆ tryPeek()

bool sparta::memory::DebugMemoryIF::tryPeek	(	addr_t	addr,
		addr_t	size,
		uint8_t *	buf
	)		const

inline

Attempts to 'peek' memory without having any side effects, size-limitations, alignment constraints except that all bytes peeked are inside an access window for this interface.

Parameters

addr	Post-translated address from which to peek (see getTranslationIF)
size	Number of bytes to read from buf. Note that addr and size can span block boundaries in a peek/poke method
buf	Buffer to which size peeked bytes will be copied if the peek was legal. Content of buf is undefined if peek is illegal

Returns: true if the peek is legal and false if not. It is up to the caller to determine if the addr and size are legal values for this interface (i.e. in an access window and not spanning a block boundary). Further restriction on alignment may be imposed by the implementation but generally should not be.

Postcondition: Has NO side-effects on simulation. Simply gets data if possible.

Note: Peek is a const-qualified method and is thus allowed in const instances of DebugMemoryIF to provide clients with read-onlydebug access to memory; Peeking has no performance requirements and may be slower than read.

Peeking is intended as a debugger/tool interface to the simulation

Definition at line 432 of file DebugMemoryIF.hpp.

Here is the call graph for this function:

◆ tryPoke()

bool sparta::memory::DebugMemoryIF::tryPoke	(	addr_t	addr,
		addr_t	size,
		const uint8_t *	buf
	)

inline

Attempts to 'poke' memory without having any side effects other than changing the bytes within the range [ addr , addr + size ). Poke has no size-limitations or alignment constraints except that all bytes peeked are inside an access window for this interface.

Parameters

addr	Post-translated address to which to poke (see getTranslationIF)
size	Number of bytes to write from buf. Note that addr and size can span block boundaries in a peek/poke method
buf	read-only buffer whose content should be written to memory.

Returns: true if the poke is legal and false if not. It is up to the caller to determine if the addr and size are legal values for this interface (i.e. in an access window and not spanning a block boundary). Further restriction on alignment may be imposed by the implementation but generally should not be.

Postcondition: Memory state will reflect the bytes poked.; Data in memory is not expected to be modified upon an illegal poke; Has NO side-effects on simulation but can modify memory storage. Has the effect of simply replacing the specified bytes in the memory model storage. The model storage internal data structures (e.g. sprarse mapping, checkpointing helpers, etc) can be modified to support a poke (i.e. a new block needed allocation) if it is required to store the poked data.

Note: Poking has no performance requirements and may be slower than write.

Poking is intended as a debugger/tool interface to the simulation

Definition at line 502 of file DebugMemoryIF.hpp.

Here is the call graph for this function:

◆ verifyInAccessWindows()

void sparta::memory::DebugMemoryIF::verifyInAccessWindows	(	addr_t	addr,
		addr_t	size
	)		const

inline

Verifies that the range [addr, addr+size) is within the access windows for this interface.

Parameters

addr	Post-translated address to which to test (see getTranslationIF)
size	Size of access to test

Exceptions

MemoryAccessError if the access is not entirely contained in access windows.

Definition at line 344 of file DebugMemoryIF.hpp.

◆ verifyNoBlockSpan()

void sparta::memory::DebugMemoryIF::verifyNoBlockSpan	(	addr_t	addr,
		addr_t	size
	)		const

inline

Verifies that the given address does not span block boundaries defined for this interface.

Parameters

addr	Post-translated address to test (see getTranslationIF)
size	Size of access to test

Exceptions

MemoryAccessError if true if access spans a block boundary, false otherwise

Definition at line 377 of file DebugMemoryIF.hpp.

Here is the call graph for this function:

Member Data Documentation

◆ acc_windows_

const std::vector<AccessWindow> sparta::memory::DebugMemoryIF::acc_windows_

protected

Vector of access windows representing this memory.

Definition at line 564 of file DebugMemoryIF.hpp.

◆ accessible_size_

addr_t sparta::memory::DebugMemoryIF::accessible_size_

protected

Number of bytes accessible through this interface.

Definition at line 595 of file DebugMemoryIF.hpp.

◆ block_idx_lsb_

addr_t sparta::memory::DebugMemoryIF::block_idx_lsb_

protected

rshift applied to an address to get the block ID

Definition at line 559 of file DebugMemoryIF.hpp.

◆ block_mask_

addr_t sparta::memory::DebugMemoryIF::block_mask_

protected

Mask applied to an address to get only bits representing the block ID.

Definition at line 554 of file DebugMemoryIF.hpp.

◆ block_size_

const addr_t sparta::memory::DebugMemoryIF::block_size_

protected

Size of a block accessed through this interface.

Definition at line 548 of file DebugMemoryIF.hpp.

◆ desc_ptr_

const std::string* const sparta::memory::DebugMemoryIF::desc_ptr_

protected

Description pointer.

Definition at line 575 of file DebugMemoryIF.hpp.

◆ high_end_

addr_t sparta::memory::DebugMemoryIF::high_end_

protected

Highest accessible address + 1.

Definition at line 590 of file DebugMemoryIF.hpp.

◆ low_end_

addr_t sparta::memory::DebugMemoryIF::low_end_

protected

Lowest accessible address.

Definition at line 585 of file DebugMemoryIF.hpp.

◆ total_range_

addr_t sparta::memory::DebugMemoryIF::total_range_

protected

Range of addresses from highest accessible to lowest.

Definition at line 580 of file DebugMemoryIF.hpp.

◆ trans_

TranslationIF* sparta::memory::DebugMemoryIF::trans_

protected

Translation interface created for this interface. Externally owned.

Definition at line 570 of file DebugMemoryIF.hpp.

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

/github/workspace/sparta/sparta/memory/DebugMemoryIF.hpp

Classes

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DebugMemoryIF()

◆ ~DebugMemoryIF()

Member Function Documentation

◆ doesAccessSpan()

◆ getAccessibleSize()

◆ getBlockSize()

◆ getDescription()

◆ getHighEnd()

◆ getLowEnd()

◆ getRange()

◆ getTranslationIF()

◆ getWindows()

◆ isAddressInWindows()

◆ isInAccessWindows()

◆ peek()

◆ poke()

◆ tryPeek()

◆ tryPoke()

◆ verifyInAccessWindows()

◆ verifyNoBlockSpan()

Member Data Documentation

◆ acc_windows_

◆ accessible_size_

◆ block_idx_lsb_

◆ block_mask_

◆ block_size_

◆ desc_ptr_

◆ high_end_

◆ low_end_

◆ total_range_

◆ trans_