Pure-virtual memory interface which represents a simple, immediately accessible (blocking) address-space with meaningful read and write accees support. Partially implements DebugMemoryIF, which adds peek and poke support as well as access addr and size validation. More...

#include <BlockingMemoryIF.hpp>

Inheritance diagram for sparta::memory::BlockingMemoryIF:

[legend]

Collaboration diagram for sparta::memory::BlockingMemoryIF:

[legend]

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

Construction
	BlockingMemoryIF (const std::string &desc, addr_t block_size, const DebugMemoryIF::AccessWindow &window, TranslationIF *transif=nullptr)
	Construct a blocking memory interface.

Memory Access
virtual bool	tryRead (addr_t addr, addr_t size, uint8_t buf, const void in_supplement=nullptr, void *out_supplement=nullptr)
	Attempt to read memory of size size at address addr.

void	read (addr_t addr, addr_t size, uint8_t buf, const void in_supplement=nullptr, void *out_supplement=nullptr)
	Attempts to read memory.

virtual bool	tryWrite (addr_t addr, addr_t size, const uint8_t buf, const void in_supplement=nullptr, void *out_supplement=nullptr)
	Attempt to write memory of size size at address addr.

void	write (addr_t addr, addr_t size, const uint8_t buf, const void in_supplement=nullptr, void *out_supplement=nullptr)
	Attempts to write memory.

virtual DMIBlockingMemoryIF *	getDMI (addr_t addr, addr_t size)
	Get a DMI blocking interface to access the given address/size.

virtual void	invalidateAllDMI ()
	Invalidate all DMI's.

Public Member Functions inherited from sparta::memory::DebugMemoryIF
	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.

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

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.

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.

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 Member Functions
Access and Query Implementations
virtual bool	tryRead_ (addr_t addr, addr_t size, uint8_t buf, const void in_supplement, void *out_supplement)=0
	Implements tryRead.

virtual bool	tryWrite_ (addr_t addr, addr_t size, const uint8_t buf, const void in_supplement, void *out_supplement)=0
	Implements tryWrite.

virtual bool	tryPoke_ (addr_t addr, addr_t size, const uint8_t *buf) override
	Override of DebugMemoryIF::tryPoke_ which forwards the call to tryWrite_.

Additional Inherited Members
Protected Attributes inherited from sparta::memory::DebugMemoryIF
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

Pure-virtual memory interface which represents a simple, immediately accessible (blocking) address-space with meaningful read and write accees support. Partially implements DebugMemoryIF, which adds peek and poke support as well as access addr and size validation.

This interface and its subclasses must reject accesses where the first and last address read are on different memory blocks (based on the block size specified at construction)

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

Through DebugMemoryIF, this class is associated with, but does not use a TranslationIF

Note: The memory behind this interface is not required to have a contiguous representation in simulator host memory. This interface makes no assumptions about storage.

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

Example

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

Definition at line 59 of file BlockingMemoryIF.hpp.

Constructor & Destructor Documentation

◆ BlockingMemoryIF()

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

inline

Construct a blocking memory interface.

Parameters

desc	Refer to DebugMemoryIF::DebugMemoryIF
block_size	Refer to DebugMemoryIF::DebugMemoryIF
window	Refer to DebugMemoryIF::DebugMemoryIF
transif	Refer to DebugMemoryIF::DebugMemoryIF

Todo:: Support vectors of windows with holes

Definition at line 81 of file BlockingMemoryIF.hpp.

◆ ~BlockingMemoryIF()

virtual sparta::memory::BlockingMemoryIF::~BlockingMemoryIF ( )

inlinevirtual

Definition at line 88 of file BlockingMemoryIF.hpp.

Member Function Documentation

◆ getDMI()

virtual DMIBlockingMemoryIF * sparta::memory::BlockingMemoryIF::getDMI	(	addr_t	addr,
		addr_t	size
	)

inlinevirtual

Get a DMI blocking interface to access the given address/size.

Parameters

addr	A guest physical address that is to be accessed via DMI
size	The intended size of data to get. Must be in the access window

Reimplemented in sparta::memory::BlockingMemoryObjectIFNode, and sparta::memory::SimpleMemoryMapNode.

Definition at line 238 of file BlockingMemoryIF.hpp.

◆ invalidateAllDMI()

virtual void sparta::memory::BlockingMemoryIF::invalidateAllDMI ( )

inlinevirtual

Invalidate all DMI's.

Reimplemented in sparta::memory::BlockingMemoryObjectIFNode.

Definition at line 246 of file BlockingMemoryIF.hpp.

◆ read()

void sparta::memory::BlockingMemoryIF::read	(	addr_t	addr,
		addr_t	size,
		uint8_t *	buf,
		const void *	in_supplement = `nullptr`,
		void *	out_supplement = `nullptr`
	)

inline

Attempts to read memory.

Parameters

addr	Post-translated address from which to read (see getTranslationIF)
size	Number of bytes to read into buf. Note that addr and size cannot define an access which spans multiple blocks
buf	buffer whose content will be overwritten by size bytes read from memory
supplement	caller-defined object identifying this memory access for notifications & debug purposes. This pointer is passed to any subsequent memory interfaces. Can be any pointer, and nullptr indicates no info.

Exceptions

SpartaException if the access is invalid as defined by this interface or the underyling memory implementaiton

Postcondition: Memory state may change if memory implementation has actions triggered on reads

Definition at line 153 of file BlockingMemoryIF.hpp.

Here is the call graph for this function:

◆ stringize()

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

inline

Render description of this BlockingMemoryIF as a string.

Definition at line 254 of file BlockingMemoryIF.hpp.

◆ tryPoke_()

virtual bool sparta::memory::BlockingMemoryIF::tryPoke_	(	addr_t	addr,
		addr_t	size,
		const uint8_t *	buf
	)

inlineoverrideprotectedvirtual

Override of DebugMemoryIF::tryPoke_ which forwards the call to tryWrite_.

Note: Arguments addr and size are guaranteed to be within access window

Exceptions

Never throws. An implementation which throws is invalid

Subclasses must override this method

Implements sparta::memory::DebugMemoryIF.

Reimplemented in sparta::memory::BlockingMemoryObjectIFNode, and sparta::memory::SimpleMemoryMapNode.

Definition at line 304 of file BlockingMemoryIF.hpp.

Here is the call graph for this function:

◆ tryRead()

virtual bool sparta::memory::BlockingMemoryIF::tryRead	(	addr_t	addr,
		addr_t	size,
		uint8_t *	buf,
		const void *	in_supplement = `nullptr`,
		void *	out_supplement = `nullptr`
	)

inlinevirtual

Attempt to read memory of size size at address addr.

Note: Unless the underlying memory object can reject accesses within the given access window for some reason and the caller needs to be able to test this, the read function is preferred.

Parameters

addr	Post-translated address from which to read (see getTranslationIF)
size	Size of read (in bytes). addr and addr + size must not land on different sides of a block boundary. Must be > 0.
buf	Buffer of data to populate with size bytes from memory object. Content of buf is undefined if read fails
supplement	caller-defined object identifying this memory access for notifications & debug purposes. This pointer is passed to any subsequent memory interfaces. Can be any pointer, and nullptr indicates no info.

Returns: true if read successful, false if not

Postcondition: buf will be populated with read results. Even if the read was unsuccessful (returned false) the first size bytes may have been modified. Other memory state may change if the memory implementation has actions triggered on writes

Reimplemented in sparta::memory::BlockingMemoryIFNode, and sparta::memory::DMIBlockingMemoryIF.

Definition at line 119 of file BlockingMemoryIF.hpp.

Here is the call graph for this function:

◆ tryRead_()

virtual bool sparta::memory::BlockingMemoryIF::tryRead_	(	addr_t	addr,
		addr_t	size,
		uint8_t *	buf,
		const void *	in_supplement,
		void *	out_supplement
	)

protectedpure virtual

Implements tryRead.

Note: Arguments addr and size are guaranteed to be within access window

Exceptions

Never throws. An implementation which throws is invalid

Subclasses must override this method

Implemented in sparta::memory::SimpleMemoryMapNode.

◆ tryWrite()

virtual bool sparta::memory::BlockingMemoryIF::tryWrite	(	addr_t	addr,
		addr_t	size,
		const uint8_t *	buf,
		const void *	in_supplement = `nullptr`,
		void *	out_supplement = `nullptr`
	)

inlinevirtual

Attempt to write memory of size size at address addr.

Note: Unless the underlying memory object can reject accesses within the given access window for some reason and the caller needs to be able to test this, the write function is preferred.

Parameters

addr	Post-translated address to which to write (see getTranslationIF)
size	Size of write (in bytes). addr and addr + size must not land on different sides of a block boundary. Must be > 0.
buf	Buffer of data to copy size bytes into memory object
supplement	caller-defined object identifying this memory access for notifications & debug purposes. This pointer is passed to any subsequent memory interfaces. Can be any pointer, and nullptr indicates no info.

Returns: true if write successful, false if not

Postcondition: Memory state will reflect the bytes written.; Data in memory is not expected to be modified upon an illegal write If the write was unsuccessful, memory will not be modified.

Reimplemented in sparta::memory::BlockingMemoryIFNode, and sparta::memory::DMIBlockingMemoryIF.

Definition at line 186 of file BlockingMemoryIF.hpp.

Here is the call graph for this function:

◆ tryWrite_()

virtual bool sparta::memory::BlockingMemoryIF::tryWrite_	(	addr_t	addr,
		addr_t	size,
		const uint8_t *	buf,
		const void *	in_supplement,
		void *	out_supplement
	)

protectedpure virtual

Implements tryWrite.

Note: Arguments addr and size are guaranteed to be within access window

Exceptions

Never throws. An implementation which throws is invalid

Subclasses must override this method

Implemented in sparta::memory::SimpleMemoryMapNode.

◆ write()

void sparta::memory::BlockingMemoryIF::write	(	addr_t	addr,
		addr_t	size,
		const uint8_t *	buf,
		const void *	in_supplement = `nullptr`,
		void *	out_supplement = `nullptr`
	)

inline

Attempts to write memory.

Parameters

addr	Post-translated address to which to write (see getTranslationIF)
size	Number of bytes to write from buf. Note that addr and size cannot define an access which spans multiple blocks
buf	read-only buffer whose content should be written to memory.
supplement	caller-defined object identifying this memory access for notifications & debug purposes. This pointer is passed to any subsequent memory interfaces. Can be any pointer, and nullptr indicates no info.

Exceptions

SpartaException if the access is invalid as defined by this interface or the underyling memory implementaiton

Postcondition: Memory state will reflect the bytes written.; Data in memory is not expected to be modified upon an failed write

Definition at line 221 of file BlockingMemoryIF.hpp.

Here is the call graph for this function:

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

/github/workspace/sparta/sparta/memory/BlockingMemoryIF.hpp

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BlockingMemoryIF()

◆ ~BlockingMemoryIF()

Member Function Documentation

◆ getDMI()

◆ invalidateAllDMI()

◆ read()

◆ stringize()

◆ tryPoke_()

◆ tryRead()

◆ tryRead_()

◆ tryWrite()

◆ tryWrite_()

◆ write()