Implementation of a memory space where the values are not stored in a contiguous storage area but are read and written via callbacks. More...

#include <VirtualMemorySpace.hxx>

Inheritance diagram for openlcb::VirtualMemorySpace:

Classes
struct	DataComparator
	STL-compatible comparator function for sorting DataElements. More...

struct	DataElement
	We keep one of these for each variable that was declared. More...

struct	RepeatComparator
	STL-compatible comparator function for sorting RepeatElements. More...

struct	RepeatElement
	Represents a repeated group. More...

Public Member Functions
bool	read_only () override

address_t	min_address () override

address_t	max_address () override

size_t	write (address_t destination, const uint8_t data, size_t len, errorcode_t error, Notifiable *again) override

size_t	read (address_t source, uint8_t dst, size_t len, errorcode_t error, Notifiable *again) override

Public Member Functions inherited from openlcb::MemorySpace
virtual bool	set_node (Node *node)
	Specifies which node the next operation pertains.

virtual errorcode_t	freeze ()
	Handles space freeze command.

virtual errorcode_t	unfreeze ()
	Handles space unfreeze command.

Protected Types
using	WriteFunction = std::function< void(unsigned repeat, string contents, BarrierNotifiable *done)>
	Function that will be called for writes.

using	ReadFunction = std::function< void(unsigned repeat, string contents, BarrierNotifiable done)>
	Function that will be called for reads.

template<typename T >
using	TypedWriteFunction = typename std::function< void(unsigned repeat, T contents, BarrierNotifiable *done)>
	Typed WriteFunction for primitive types.

template<typename T >
using	TypedReadFunction = typename std::function< T(unsigned repeat, BarrierNotifiable *done)>
	Typed ReadFunction for primitive types.

Protected Member Functions
template<class G >
void	set_bounds_from_group (const G &group)
	Setup the address bounds from a single CDI group declaration.

template<class G >
void	expand_bounds_from_group (const G &group)
	Expand the address bounds from a single CDI group declaration.

void	register_element (address_t address, address_t size, ReadFunction read_f, WriteFunction write_f)
	Register an untyped element.

template<unsigned SIZE>
void	register_string (const StringConfigEntry< SIZE > &entry, ReadFunction read_f, WriteFunction write_f)
	Registers a string typed element.

template<typename T >
void	register_numeric (const NumericConfigEntry< T > &entry, TypedReadFunction< T > read_f, TypedWriteFunction< T > write_f)
	Registers a numeric typed element.

template<class Group , unsigned N>
void	register_repeat (const RepeatedGroup< Group, N > &group)
	Registers a repeated group.

Protected Attributes
address_t	minAddress_ = 0xFFFFFFFFu
	Bounds for valid addresses.

address_t	maxAddress_ = 0
	Bounds for valid addresses.

unsigned	isReadOnly_: 1
	Whether the space should report as RO.

Private Types
typedef SortedListSet< DataElement, DataComparator >	ElementsType
	Container type for storing the data elements.

Private Member Functions
ssize_t	find_data_element (address_t address, address_t len, const DataElement *ptr, unsigned repeat)
	Look up the first matching data element given an address in the virtual memory space.

Private Attributes
address_t	cacheOffset_ = NO_CACHE
	Offset in the memory space at which cachedData_ starts.

string	cachedData_
	Stored information for read-modify-write calls.

ElementsType	elements_
	Stores all the registered variables.

SortedListSet< RepeatElement, RepeatComparator >	repeats_
	Stores all the registered variables.

BarrierNotifiable	bn_
	Helper object in the function calls.

Static Private Attributes
static constexpr unsigned	NO_CACHE = static_cast<address_t>(-1)

Additional Inherited Members
Public Types inherited from openlcb::MemorySpace
typedef uint32_t	address_t

typedef uint16_t	errorcode_t

Static Public Attributes inherited from openlcb::MemorySpace
static const errorcode_t	ERROR_AGAIN = 0x3FFF
	This error code signals that the operation was only partially completed, the again notify was used and will be notified when the operation can be re-tried).

Detailed Description

Implementation of a memory space where the values are not stored in a contiguous storage area but are read and written via callbacks.

Definition at line 49 of file VirtualMemorySpace.hxx.

Member Typedef Documentation

◆ ElementsType

typedef SortedListSet<DataElement, DataComparator> openlcb::VirtualMemorySpace::ElementsType

private

Container type for storing the data elements.

Definition at line 515 of file VirtualMemorySpace.hxx.

◆ ReadFunction

using openlcb::VirtualMemorySpace::ReadFunction = std::function<void( unsigned repeat, string *contents, BarrierNotifiable *done)>

protected

Function that will be called for reads.

Parameters

repeat	0 to number of repeats if this is in a repeated group. Always 0 if not repeated group.
contents	the payload to be returned from this variable shall be written here. Will be zero-padded to size_ bytes if shorter.
done	must be notified when the read values are ready. The call will be re-tried if this does not happen inline.

Definition at line 221 of file VirtualMemorySpace.hxx.

◆ TypedReadFunction

template<typename T >

using openlcb::VirtualMemorySpace::TypedReadFunction = typename std::function<T ( unsigned repeat, BarrierNotifiable *done)>

protected

Typed ReadFunction for primitive types.

Returns: the read value if the read was successful. If the read did not complete, return 0.

Definition at line 232 of file VirtualMemorySpace.hxx.

◆ TypedWriteFunction

template<typename T >

using openlcb::VirtualMemorySpace::TypedWriteFunction = typename std::function<void( unsigned repeat, T contents, BarrierNotifiable *done)>

protected

Typed WriteFunction for primitive types.

Definition at line 226 of file VirtualMemorySpace.hxx.

◆ WriteFunction

using openlcb::VirtualMemorySpace::WriteFunction = std::function<void( unsigned repeat, string contents, BarrierNotifiable *done)>

protected

Function that will be called for writes.

Parameters

repeat	0 to number of repeats if this is in a repeated group. Always 0 if not repeated group.
contents	data payload that needs to be written. The data bytes of this container start at the address_.
done	must be notified when the write is complete (possibly inline).

Definition at line 212 of file VirtualMemorySpace.hxx.

Constructor & Destructor Documentation

◆ VirtualMemorySpace()

openlcb::VirtualMemorySpace::VirtualMemorySpace ( )

inline

Definition at line 52 of file VirtualMemorySpace.hxx.

Member Function Documentation

◆ expand_bounds_from_group()

template<class G >

void openlcb::VirtualMemorySpace::expand_bounds_from_group ( const G & group )

inlineprotected

Expand the address bounds from a single CDI group declaration.

Parameters

group is an instance of a group, for example a segment.

Definition at line 245 of file VirtualMemorySpace.hxx.

◆ find_data_element()

ssize_t openlcb::VirtualMemorySpace::find_data_element	(	address_t	address,
		address_t	len,
		const DataElement **	ptr,
		unsigned *	repeat
	)

inlineprivate

Look up the first matching data element given an address in the virtual memory space.

Parameters

address	byte offset to look up.
len	how many bytes long range to search from address.
ptr	will be filled with a pointer to the data element when found, or filled with nullptr if no data element overlaps with the given range.
repeat	output argument, filled with zero or the repetition number.

Returns: 0 if an exact match is found. -N if a data element is found, but N first bytes of this element are not covered. A number N in [1..len-1] if a data element is found, but this many bytes need to be skipped from address to arrive at the given data element's offset. len if there was no data element found (in which case also set ptr to null).

Definition at line 417 of file VirtualMemorySpace.hxx.

◆ max_address()

address_t openlcb::VirtualMemorySpace::max_address ( )

inlineoverridevirtual

Returns: the largest valid address for this block. A read of 1 from this address should succeed in returning the last byte.

Implements openlcb::MemorySpace.

Definition at line 69 of file VirtualMemorySpace.hxx.

◆ min_address()

address_t openlcb::VirtualMemorySpace::min_address ( )

inlineoverridevirtual

Returns: the lowest address that's valid for this block.

Reimplemented from openlcb::MemorySpace.

Definition at line 63 of file VirtualMemorySpace.hxx.

◆ read()

size_t openlcb::VirtualMemorySpace::read	(	address_t	source,
		uint8_t *	dst,
		size_t	len,
		errorcode_t *	error,
		Notifiable *	again
	)

inlineoverridevirtual

Returns: the number of bytes successfully read (before hitting end of space). If *error is set to non-null, then the operation has failed. If the operation needs to be continued, then sets error to ERROR_AGAIN, and calls the Notifiable

Parameters

again when a re-try makes sense. The caller should call read once more, with the offset adjusted with the previously returned bytes.

Implements openlcb::MemorySpace.

Definition at line 165 of file VirtualMemorySpace.hxx.

◆ read_only()

bool openlcb::VirtualMemorySpace::read_only ( )

inlineoverridevirtual

Returns: whether the memory space does not accept writes.

Reimplemented from openlcb::MemorySpace.

Definition at line 58 of file VirtualMemorySpace.hxx.

◆ register_element()

void openlcb::VirtualMemorySpace::register_element	(	address_t	address,
		address_t	size,
		ReadFunction	read_f,
		WriteFunction	write_f
	)

inlineprotected

Register an untyped element.

Parameters

address	the address in the memory space
size	how many bytes this elements occupes
read_f	will be called to read this data
write_f	will be called to write this data

Definition at line 257 of file VirtualMemorySpace.hxx.

◆ register_numeric()

template<typename T >

void openlcb::VirtualMemorySpace::register_numeric	(	const NumericConfigEntry< T > &	entry,
		TypedReadFunction< T >	read_f,
		TypedWriteFunction< T >	write_f
	)

inlineprotected

Registers a numeric typed element.

Parameters

T	is the type argument, e.g. uint8_t.
entry	is the CDI ConfigRepresentation.
read_f	will be called to read this data
write_f	will be called to write this data

Definition at line 281 of file VirtualMemorySpace.hxx.

◆ register_repeat()

template<class Group , unsigned N>

void openlcb::VirtualMemorySpace::register_repeat ( const RepeatedGroup< Group, N > & group )

inlineprotected

Registers a repeated group.

Calling this function means that the virtual memory space of the group will be looped onto the first repetition. The correct usage is to register the elements of the first repetition, then register the repetition itself using this call. Nested repetitions are not supported (either the outer or the inner repetition needs to be unrolled and registered for each repeat there).

Parameters

group is the repeated group instance. Will take the start offset, repeat count and repeat size from it.

Definition at line 313 of file VirtualMemorySpace.hxx.

◆ register_string()

template<unsigned SIZE>

void openlcb::VirtualMemorySpace::register_string	(	const StringConfigEntry< SIZE > &	entry,
		ReadFunction	read_f,
		WriteFunction	write_f
	)

inlineprotected

Registers a string typed element.

Parameters

entry	is the CDI ConfigRepresentation.
read_f	will be called to read this data
write_f	will be called to write this data

Definition at line 268 of file VirtualMemorySpace.hxx.

◆ set_bounds_from_group()

template<class G >

void openlcb::VirtualMemorySpace::set_bounds_from_group ( const G & group )

inlineprotected

Setup the address bounds from a single CDI group declaration.

Parameters

group is an instance of a group, for example a segment.

Definition at line 237 of file VirtualMemorySpace.hxx.

◆ write()

size_t openlcb::VirtualMemorySpace::write	(	address_t	destination,
		const uint8_t *	data,
		size_t	len,
		errorcode_t *	error,
		Notifiable *	again
	)

inlineoverridevirtual

Returns: the number of bytes successfully written (before hitting end of space).

Parameters

destination	address to write to
data	to write
len	how many bytes to write
error	if set to non-null, then the operation has failed. If the operation needs to be continued, then sets error to MemorySpace::ERROR_AGAIN, and calls the Notifiable
again	when a re-try makes sense. The caller should call write once more, with the offset adjusted with the previously returned bytes.

Reimplemented from openlcb::MemorySpace.

Definition at line 85 of file VirtualMemorySpace.hxx.

Member Data Documentation

◆ bn_

BarrierNotifiable openlcb::VirtualMemorySpace::bn_

private

Helper object in the function calls.

Definition at line 521 of file VirtualMemorySpace.hxx.

◆ cachedData_

string openlcb::VirtualMemorySpace::cachedData_

private

Stored information for read-modify-write calls.

Definition at line 513 of file VirtualMemorySpace.hxx.

◆ cacheOffset_

address_t openlcb::VirtualMemorySpace::cacheOffset_ = NO_CACHE

private

Offset in the memory space at which cachedData_ starts.

Definition at line 511 of file VirtualMemorySpace.hxx.

◆ elements_

ElementsType openlcb::VirtualMemorySpace::elements_

private

Stores all the registered variables.

Definition at line 517 of file VirtualMemorySpace.hxx.

◆ isReadOnly_

unsigned openlcb::VirtualMemorySpace::isReadOnly_

protected

Whether the space should report as RO.

Definition at line 330 of file VirtualMemorySpace.hxx.

◆ maxAddress_

address_t openlcb::VirtualMemorySpace::maxAddress_ = 0

protected

Bounds for valid addresses.

A read of length 1 from this address should succeed in returning the last byte.

Definition at line 328 of file VirtualMemorySpace.hxx.

◆ minAddress_

address_t openlcb::VirtualMemorySpace::minAddress_ = 0xFFFFFFFFu

protected

Bounds for valid addresses.

Definition at line 325 of file VirtualMemorySpace.hxx.

◆ NO_CACHE

constexpr unsigned openlcb::VirtualMemorySpace::NO_CACHE = static_cast<address_t>(-1)

staticconstexprprivate

Definition at line 509 of file VirtualMemorySpace.hxx.

◆ repeats_

SortedListSet<RepeatElement, RepeatComparator> openlcb::VirtualMemorySpace::repeats_

private

Stores all the registered variables.

Definition at line 519 of file VirtualMemorySpace.hxx.

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

VirtualMemorySpace.hxx

Classes

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Private Types

Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ElementsType

◆ ReadFunction

◆ TypedReadFunction

◆ TypedWriteFunction

◆ WriteFunction

Constructor & Destructor Documentation

◆ VirtualMemorySpace()

Member Function Documentation

◆ expand_bounds_from_group()

◆ find_data_element()

◆ max_address()

◆ min_address()

◆ read()

◆ read_only()

◆ register_element()

◆ register_numeric()

◆ register_repeat()

◆ register_string()

◆ set_bounds_from_group()

◆ write()

Member Data Documentation

◆ bn_

◆ cachedData_

◆ cacheOffset_

◆ elements_

◆ isReadOnly_

◆ maxAddress_

◆ minAddress_

◆ NO_CACHE

◆ repeats_