View into a backend block of memory in an ArchData. More...

#include <DataView.hpp>

Inheritance diagram for sparta::DataView:

Collaboration diagram for sparta::DataView:

Public Types
typedef ArchDataSegment::offset_type	offset_type
	Represents offset into ArchData.

typedef ArchDataSegment::ident_type	ident_type
	DataView identifiers (distinguishes views in the same ArchData)

typedef uint32_t	index_type
	Type used for specifying index into this DataView during a read or write.

Public Types inherited from sparta::ArchDataSegment
typedef uint64_t	offset_type

typedef uint32_t	ident_type

Public Member Functions
	DataView (ArchData data, ident_type id, offset_type size, ident_type subset_of=INVALID_ID, offset_type subset_offset=0, const uint8_t initial_buf_le=nullptr)
	Construct a DataView.

ArchData *	getArchData () const

offset_type	getSize () const

offset_type	getOffset () const

ArchData::Line *	getLine () const
	Get already-placed line.

ident_type	getID () const

template<typename T , ByteOrder BO = LE>
T	read (index_type idx=0) const
	Reads a value from this DataView at the specific index.

template<typename T , ByteOrder BO = LE>
T	readUnsafe (index_type idx=0) const
	Same behavior as read but without checking access bounds.

template<typename T , ByteOrder BO = LE>
T	readPadded (index_type idx=0) const
	Reads a value from this DataView using a type T which might be larger than the dataview.

template<typename T , ByteOrder BO = LE>
T	readPaddedUnsafe (index_type idx=0) const
	Same behavior as readPadded but without checking access bounds.

template<typename T , ByteOrder BO = LE>
void	write (T val, index_type idx=0)
	Writes a value to this DataView at the specific index.

template<typename T , ByteOrder BO = LE>
void	writeUnsafe (T val, index_type idx=0)
	Same behavior as write but without checking access bounds.

template<typename T , ByteOrder BO = LE>
void	writeTruncated (T val, uint32_t idx=0)
	Writes value from this DataView using a type T which might be larger than the size of the DataView.

template<typename T , ByteOrder BO = LE>
void	writeTruncatedUnsafe (T val, uint32_t idx=0)
	Same behavior as writeTruncated bout without checking access bounds.

DataView &	operator= (const DataView &rhp)
	Reads data from another dataview and writes that value to this DataView.

std::string	getByteString () const
	Dump data in this DataView as hex bytes in address order with a space between each pair.

template<ByteOrder BO = LE>
std::string	getValueAsString () const
	Reads the value of this DataView and renders as a string in the specified Byte-Order as a prefixed hex number with zero-padding. (e.g. 0x00c0ffee).

Public Member Functions inherited from sparta::ArchDataSegment
	ArchDataSegment (const ArchDataSegment &)=delete

	ArchDataSegment (const ArchDataSegment &&)=delete

ArchDataSegment &	operator= (const ArchDataSegment &)=delete

	ArchDataSegment (ArchData *data, offset_type size, ident_type id, ident_type subset_of=INVALID_ID, offset_type subset_offset=0)
	Constructor.

virtual	~ArchDataSegment ()
	Virtual destructor.

void	place (offset_type offset)
	Sets the offset of this DataView within its ArchData then invokes the place_ method for subclasses to handle.

void	writeInitial ()
	Invokes writeInitial_, giving subclasses a chance to write a value to memory during initialization or reset of an ArchData.

bool	isPlaced () const
	Has this segment been placed yet.

offset_type	getOffset () const
	Gets the offset of this segment once placed.

offset_type	getLayoutSize () const
	Gets the layout size of this segment (number of bytes)

ident_type	getLayoutID () const
	Gets the layout Identifier of this segment.

ident_type	getSubsetOf () const
	Gets the segment of which this segment is a subset.

offset_type	getSubsetOffset () const
	Gets the offset into the segment of which this segment is a subset.

ArchData *	getArchData ()
	Gets the ArchData associated with this segment.

const ArchData *	getArchData () const
	Gets the ArchData associated with this segment.

Static Public Attributes
static const std::string	DATAVIEW_UNPLACED_STR
	String to show instead of a value when representing an unplaced dataview.

static const ident_type	INVALID_ID
	Invalid Identifier constant for a DataView.

Static Public Attributes inherited from sparta::ArchDataSegment
static const ident_type	INVALID_ID = ~(ident_type)0
	Indicates an invalid ID for an ArchDataSegment or any refinement.

Protected Member Functions
Inherited from ArchDataSegment
virtual void	place_ (offset_type offset) override
	Places this DataView within its ArchData.

virtual void	writeInitial_ () override
	Writes the initial value of this DataView into memory. This is guaranteed to be called after placement.

Detailed Description

View into a backend block of memory in an ArchData.

Note: Can be a subset of another DataView. ArchDataSegment provides the layout inteface Noncopyable because of ArchDataSegment. Could be made copyable if ArchDataSegment were also copable.

Definition at line 27 of file DataView.hpp.

Member Typedef Documentation

◆ ident_type

typedef ArchDataSegment::ident_type sparta::DataView::ident_type

DataView identifiers (distinguishes views in the same ArchData)

Definition at line 32 of file DataView.hpp.

◆ index_type

typedef uint32_t sparta::DataView::index_type

Type used for specifying index into this DataView during a read or write.

Definition at line 33 of file DataView.hpp.

◆ offset_type

typedef ArchDataSegment::offset_type sparta::DataView::offset_type

Represents offset into ArchData.

Definition at line 31 of file DataView.hpp.

Constructor & Destructor Documentation

◆ DataView()

sparta::DataView::DataView	(	ArchData *	data,
		ident_type	id,
		offset_type	size,
		ident_type	subset_of = `INVALID_ID`,
		offset_type	subset_offset = `0`,
		const uint8_t *	initial_buf_le = `nullptr`
	)

inline

Construct a DataView.

Parameters

data	Data which this view will access. Must not be nullptr
id	ID of this DataView (as an ArchDataSegment
size	size of <data> accessed by this view. Must be a power of 2 greater than 0. This is validated by ArchDataSegment
subset_of	ID of another DataView of which this is a subset (occupies only a subset of the other dataview's space).
subset_offset	Offset in bytes within the dataview indicated by subset_of
initial_buf_le	Buffer from which initial value will be copied byte-by-byte from a little-endian byte array source. Therefore, bytes could be swapped if Sparta is run (if supported) on a BE architecture. The result should be that hand-coded intitial_buf byte-arrays needn't be updated during such changes. This pointer must be nullptr or contain a number of bytes >= size. The pointer must be valid at least until DataView::place is called during initialization

Note: Subsets relationships might not be validated at construction. Invalid subset relationships might only be tested at ArchData layout-time. This means that a DataView which is larger than another DataView of which it is declared a subset will not cause an error until layout-time (see layout).

Definition at line 64 of file DataView.hpp.

Here is the call graph for this function:

Member Function Documentation

◆ getArchData()

ArchData * sparta::DataView::getArchData ( ) const

inline

Returns: The ArchData object this view is associated with

Definition at line 98 of file DataView.hpp.

◆ getByteString()

std::string sparta::DataView::getByteString ( ) const

inline

Dump data in this DataView as hex bytes in address order with a space between each pair.

Precondition: This view must have been placed (isPlaced())

Example for a 16bit DataView:

std::cout << dv.getByteString();

de ad be ef

Definition at line 347 of file DataView.hpp.

Here is the call graph for this function:

◆ getID()

ident_type sparta::DataView::getID ( ) const

inline

Returns: The layout ID

Definition at line 110 of file DataView.hpp.

Here is the call graph for this function:

◆ getLine()

ArchData::Line * sparta::DataView::getLine ( ) const

inline

Get already-placed line.

Returns: The line that is viewed into the ArchData

Definition at line 107 of file DataView.hpp.

◆ getOffset()

offset_type sparta::DataView::getOffset ( ) const

inline

Returns: The offset of the memory within the ArchData

Definition at line 104 of file DataView.hpp.

◆ getSize()

offset_type sparta::DataView::getSize ( ) const

inline

Returns: The size of this view

Definition at line 101 of file DataView.hpp.

Here is the call graph for this function:

◆ getValueAsString()

template<ByteOrder BO = LE>

std::string sparta::DataView::getValueAsString ( ) const

inline

Reads the value of this DataView and renders as a string in the specified Byte-Order as a prefixed hex number with zero-padding. (e.g. 0x00c0ffee).

Precondition: This view must have been placed (isPlaced())

Returns: String of contained data read in the specified endianness

Template Parameters

BO	ByteOrder in which to read the value of this DataView

Definition at line 367 of file DataView.hpp.

Here is the call graph for this function:

◆ operator=()

DataView & sparta::DataView::operator= ( const DataView & rhp )

inline

Reads data from another dataview and writes that value to this DataView.

Precondition: rhp and this must have same size; Dataviews must be placed. See DataView::isPlaced

Exceptions

SpartaException if dataviews have different size

Note: This method performs no re-ordering since endianness is a property of data-access and not data storage.

Definition at line 319 of file DataView.hpp.

Here is the call graph for this function:

◆ place_()

virtual void sparta::DataView::place_ ( offset_type offset )

inlineoverrideprotectedvirtual

Places this DataView within its ArchData.

Postcondition: Writes initial value if specified at construction

Parameters

offset Offset into <data>

Todo:: Store pointer directly to value to save an add in offset

Reimplemented from sparta::ArchDataSegment.

Definition at line 400 of file DataView.hpp.

Here is the call graph for this function:

◆ read()

template<typename T , ByteOrder BO = LE>

T sparta::DataView::read ( index_type idx = 0 ) const

inline

Reads a value from this DataView at the specific index.

Template Parameters

T	type of value to read. Should be [u]intNN_t. See sparta::ArchData::Line::read specializations for supported types.
BO	sparta::ByteOrder describing read byte-order.

Parameters

idx Index offset within this DataView from low memory address in the DataView. Index refers to multiples of sizeof(T). This is used for reading the content of the DataView as smaller values. For example, a 128b DataView can be read as two uint64_t values by calling read<uint64_t, LE>(0), read<uint64_t, LE>(1). The caller would then be responsible for performing 128b operations using these two values.

Returns: The read value interpreted as the appropriate byte-order from memory referenced by this DataView.

Note: May generate assertion if read size is invalid. These assertions should be disabled in optimized mode for performance.; sizeof(T)*index + sizeof(T) must be less than getSize().

Precondition: This view must have been placed (isPlaced())

Example:

assert(dv.getSize() == 64);
uint32_t val1 = dv.read<uint32_t, LE>();
uint32_t val2 = dv.read<uint32_t, LE>(1);

Definition at line 142 of file DataView.hpp.

Here is the call graph for this function:

◆ readPadded()

template<typename T , ByteOrder BO = LE>

T sparta::DataView::readPadded ( index_type idx = 0 ) const

inline

Reads a value from this DataView using a type T which might be larger than the dataview.

See also: sparta::DataView::read

Parameters

idx	Index at which to read to this view in terms of multiples of sizeof(T)

See also: read

Precondition: This view must have been placed (isPlaced())

A good example usage is T=uint64_t, getSize()=4, and idx_=0

Definition at line 172 of file DataView.hpp.

Here is the call graph for this function:

◆ readPaddedUnsafe()

template<typename T , ByteOrder BO = LE>

T sparta::DataView::readPaddedUnsafe ( index_type idx = 0 ) const

inline

Same behavior as readPadded but without checking access bounds.

Note: This exists to avoid redundancy if higher-level functions are already checkint the access bounds

Definition at line 186 of file DataView.hpp.

Here is the call graph for this function:

◆ readUnsafe()

template<typename T , ByteOrder BO = LE>

T sparta::DataView::readUnsafe ( index_type idx = 0 ) const

inline

Same behavior as read but without checking access bounds.

Note: This exists to avoid redundancy if higher-level functions are already checkint the access bounds

Definition at line 155 of file DataView.hpp.

Here is the call graph for this function:

◆ write()

template<typename T , ByteOrder BO = LE>

void sparta::DataView::write	(	T	val,
		index_type	idx = `0`
	)

inline

Writes a value to this DataView at the specific index.

Parameters

val	The value to write of type T

Template Parameters

T	type of value to write. Should be [u]intNN_t. See sparta::ArchData::Line::read specializations for supported types.
BO	sparta::ByteOrder describing read byte-order.

Parameters

idx Index offset within this DataView from low memory address in the DataView. Index refers to multiples of sizeof(T). This is used for writing to the content of the DataView as smaller values. For example, a 128b DataView can be written as two uint64_t values by calling write<uint64_t, LE>(val1, 0), write<uint64_t, LE>(val2, 1). The caller would then be responsible for performing representing the 128b value before writing to the register.

Returns: The write value stored into memory using the appropriate byte-order from memory.

Note: May generate assertion if read size is invalid. These assertions should be disabled in optimized mode for performance.; sizeof(T)*index + sizeof(T) must be less than getSize().

Precondition: This view must have been placed (isPlaced())

Example:

assert(dv.getSize() == 64);
dv.write<uint32_t, LE>(val1);
dv.write<uint32_t, LE>(val2, 1);

Definition at line 237 of file DataView.hpp.

Here is the call graph for this function:

◆ writeInitial_()

virtual void sparta::DataView::writeInitial_ ( )

inlineoverrideprotectedvirtual

Writes the initial value of this DataView into memory. This is guaranteed to be called after placement.

Reimplemented from sparta::ArchDataSegment.

Definition at line 410 of file DataView.hpp.

Here is the call graph for this function:

◆ writeTruncated()

template<typename T , ByteOrder BO = LE>

void sparta::DataView::writeTruncated	(	T	val,
		uint32_t	idx = `0`
	)

inline

Writes value from this DataView using a type T which might be larger than the size of the DataView.

See also: sparta::DataView::read

Parameters

val	Value to write. This may contain more set significant bytes than than the number of bytes available in this view following the chosen idx
idx	Index at which to write to this view in terms of multiples of sizeof(T)

Precondition: This view must have been placed (isPlaced())

Truncates most signficant bits from val if larger than the number of bytes which can be written at idx.

A good example usage is T=uint64_t, getSize()=4, and idx_=0

Definition at line 275 of file DataView.hpp.

Here is the call graph for this function:

◆ writeTruncatedUnsafe()

template<typename T , ByteOrder BO = LE>

void sparta::DataView::writeTruncatedUnsafe	(	T	val,
		uint32_t	idx = `0`
	)

inline

Same behavior as writeTruncated bout without checking access bounds.

Note: This exists to avoid redundancy if higher-level functions are already checking the access bounds; Still checks access size for sanity (i.e. positive integer power of 2 and <= 8)

Definition at line 292 of file DataView.hpp.

Here is the call graph for this function:

◆ writeUnsafe()

template<typename T , ByteOrder BO = LE>

void sparta::DataView::writeUnsafe	(	T	val,
		index_type	idx = `0`
	)

inline

Same behavior as write but without checking access bounds.

Note: This exists to avoid redundancy if higher-level functions are already checking the access bounds

Definition at line 252 of file DataView.hpp.

Here is the call graph for this function:

Member Data Documentation

◆ DATAVIEW_UNPLACED_STR

const std::string sparta::DataView::DATAVIEW_UNPLACED_STR

static

String to show instead of a value when representing an unplaced dataview.

Definition at line 39 of file DataView.hpp.

◆ INVALID_ID

const ident_type sparta::ArchDataSegment::INVALID_ID

static

Invalid Identifier constant for a DataView.

Definition at line 27 of file ArchDataSegment.hpp.

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

/github/workspace/sparta/sparta/functional/DataView.hpp

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ ident_type

◆ index_type

◆ offset_type

Constructor & Destructor Documentation

◆ DataView()

Member Function Documentation

◆ getArchData()

◆ getByteString()

◆ getID()

◆ getLine()

◆ getOffset()

◆ getSize()

◆ getValueAsString()

◆ operator=()

◆ place_()

◆ read()

◆ readPadded()

◆ readPaddedUnsafe()

◆ readUnsafe()

◆ write()

◆ writeInitial_()

◆ writeTruncated()

◆ writeTruncatedUnsafe()

◆ writeUnsafe()

Member Data Documentation

◆ DATAVIEW_UNPLACED_STR

◆ INVALID_ID