Base class to represents an architected register of any size that is a power of 2 and greater than 0 with a ceiling specified. More...

#include <Register.hpp>

Inheritance diagram for sparta::RegisterBase:

[legend]

Collaboration diagram for sparta::RegisterBase:

[legend]

Classes
struct	Definition
	Describes an architected Register. More...

class	Field
	Register Field with masked access to owning register. More...

struct	PostWriteAccess
	Structure containing data for a Register post-write notification. More...

struct	ReadAccess
	Structure containing data for a Register pre- or post-read notification. More...

Public Types
typedef DataView::ident_type	ident_type
	Identifier to distinguish from other registers in the same RegisterSet.

typedef DataView::index_type	index_type
	Index of read/write access within register.

typedef DataView::offset_type	size_type
	Size of register and bit or byte offset within register data.

typedef uint32_t	group_num_type
	Numeric group identifier for register lookup.

typedef TreeNode::group_idx_type	group_idx_type
	TreeNode group index.

typedef uint32_t	bank_idx_type
	Numeric bank identifier for bank lookup.

typedef std::vector< const char * >	AliasVector
	Vector of Register Aliases.

typedef std::vector< Field * >	FieldVector
	Vector of Register Fields.

typedef std::function< sparta::utils::ValidValue< uint64_t >(RegisterBase *)>	register_read_callback_type
	Register read callback.

typedef std::function< bool(RegisterBase *, uint64_t)>	register_write_callback_type
	Register write callback.

typedef NotificationSource< ReadAccess >	ReadNotiSrc
	Notification type for Register read accesses.

typedef NotificationSource< PostWriteAccess >	PostWriteNotiSrc
	Notification type for Register write accesses.

Public Types inherited from sparta::TreeNode
typedef uint64_t	node_uid_type
	Type of unique-identifier assigned to every node.

typedef std::vector< TreeNode * >	ChildrenVector
	Vector of TreeNode children.

typedef std::vector< std::string >	AliasVector
	Vector of aliases (other names for this node)

typedef std::multimap< std::string, TreeNode * >	ChildNameMapping
	Mapping of names, aliases, and groups to individual child nodes within one node. This must be in a deterministic order, so an ordered container (e.g. std::map) is required. A sorted contained is probably desirable, but not required.

typedef uint32_t	group_idx_type
	Index within a group.

typedef std::weak_ptr< TreeNode >	WeakPtr
	Weak pointer to a TreeNode. Acquire with getWeakPtr.

typedef std::weak_ptr< const TreeNode >	ConstWeakPtr
	Weak pointer to a const TreeNode. Acquire with getWeakPtr.

typedef std::shared_ptr< TreeNode >	SharedPtr
	Shared pointer to TreeNode. Acquire with WeakPtr::lock().

typedef std::map< const std::string , std::vector< TreeNode > >	TagsMap
	Map of strings (interned in StringManager) tags to TreeNodes.

Public Types inherited from sparta::PhasedObject
enum	TreePhase { TREE_BUILDING = 0 , TREE_CONFIGURING = 1 , TREE_FINALIZING = 2 , TREE_FINALIZED = 3 , TREE_TEARDOWN = 4 }
	Current phase of tree construction (applies to node and entire tree). More...

Public Member Functions
Field *	getField (const std::string &name)
	Retrieves a child that is a Register::Field with the given dotted path.

const Field *	getField (const std::string &name) const
	Retrieves a child that is a Register::Field with the given dotted path.

PostWriteNotiSrc &	getPostWriteNotificationSource ()
	Returns the post-write notification-source node for this register which can be used to observe writes to this register. This notification is posted immediately after the register has been written and populates a sparta::Register::PostWriteAccess object with the results.

ReadNotiSrc &	getReadNotificationSource ()
	Returns the read notification-source node for this register which can be used to observe reads to this register. This notification is posted immediately after the register has been read and populates a sparta::Register::ReadAccess object with the results.

void	addReadCB (register_read_callback_type callback)
	Registers a callback for obtaining a 32- or 64-bit register value.

bool	hasReadCB () const
	Returns true if register has a read callback; false otherwise.

void	addWriteCB (register_write_callback_type callback)
	Registers a callback for writing a 32- or 64-bit register value.

bool	hasWriteCB () const
	Returns true if register has a write callback; false otherwise.

Construction & Initialization
	RegisterBase (TreeNode *parent, const Definition &def)
	Register constructor.

virtual	~RegisterBase ()
	Destructor.

void	reset (bool unmasked=true)
	Reset this register to its default value.

Field *	addField (const Field::Definition &fd)
	Create a new field in this Register based on the given Field::Definition.

Const Attributes
ident_type	getID () const
	Gets the ID of this register as specified in its definition.

group_num_type	getGroupNum () const
	Gets the group number of this register as specified in its definition.

std::string	getGroupName () const
	Gets the name of the group to which this register belongs from its definition.

group_idx_type	getGroupIdx () const
	Gets the group index of this register as specified in its definition.

size_type	getNumBytes () const
	Gets the size of this register's value in bytes.

size_type	getNumBits () const
	Gets the size of this register's value in bits.

size_type	getNumFields () const
	Gets the number of fields within this register.

bool	isInBank (bank_idx_type bank) const
	Determines if this register is accessible through a specific bank index (assuming that this bank index exists in the owning register set)

bool	isBanked () const
	Is this register banked.

FieldVector &	getFields ()
	Gets the full set of register fields.

const FieldVector &	getFields () const
	Const qualified version of getFields.

ident_type	getSubsetOf () const
	Returns the identity of the compound Register in the same Register set which this register is a subset (refers a subset of bytes in that parent).

size_type	getSubsetOffset () const
	Returns the byte offset into the compound Register of which this register is a subset.

Definition::HintsT	getHintFlags () const
	Returns the hint flags for this type.

Definition::RegDomainT	getRegDomain () const
	Returns the regdomain for this type.

const Definition &	getDefinition () const
	Gets the definition supplied during the construciton of this Register.

Access Methods
template<typename T >
T	read (index_type idx=0)
	Read a value from this register.

sparta::utils::ValidValue< uint64_t >	readWithCheck ()
	Read a value from this register, possibly via a user-supplied callback.

template<typename T >
void	write (T val, index_type idx=0)
	Write a value into this register.

template<typename T >
bool	writeWithCheck (T val)
	Write a value to this register, possibly via a user-supplied callback.

template<typename T >
void	writeUnmasked (T val, index_type idx=0)
	Write a value into this register without it being affected by the write-mask.

template<typename T >
T	peek (index_type idx=0) const

template<typename T >
void	poke (T val, index_type idx=0)
	Poke a value into this regster.

template<typename T >
void	pokeUnmasked (T val, index_type idx=0)
	Poke a value into this regster without it being affected by the write-mask.

template<typename T >
T	dmiRead (index_type idx=0) const
	Read value directly from the Register's backing store.

template<typename T >
void	dmiWrite (T val, index_type idx=0)
	Write a value directly to this Register's backing store.

template<typename T >
T	getWriteMask (index_type idx=0) const
	Get a write mask at the given index of the given size.

Printing Methods
std::string	getValueAsByteString () const
	Creates a string representing this register's value as a sequence of bytes, separated by a spaces, sorted by address ascending.

std::string	getWriteMaskAsByteString () const
	Creats a string representing this register's write-mask as sequence of bytes, separated by spaces, sorted by address ascending.

std::string	getWriteMaskAsBitString () const
	Creats a string representing this register's write-mask as sequence of bits, separated by a space between each byte, sorted by bit-address ascending.

Observation
void	read (void *buf, size_t size, size_t offset)

void	peek (void *buf, size_t size, size_t offset) const

void	write (const void *buf, size_t size, size_t offset)

void	writeUnmasked (const void *buf, size_t size, size_t offset)

void	poke (const void *buf, size_t size, size_t offset)

void	pokeUnmasked (const void *buf, size_t size, size_t offset)

Public Member Functions inherited from sparta::TreeNode
const Clock *	getClock () override
	Walks up parents (starting with self) until a parent with an associated local clock is found, then returns that clock.

const Clock *	getClock () const

const Clock *	getLocalClock ()
	Gets the clock associated directly with this Node. This is useful for configuration and simulator debug, but not at run-time.

const Clock *	getLocalClock () const

virtual void	setClock (const Clock *clk)
	Assigns a clock to this node. This clock will then be accessed by any descendant which has no assigned clock or an ancestor with an assigned clock between that descendant and this node. getClock returns the Clock associated with the nearest ancestor.

Scheduler *	getScheduler (const bool must_exist=false)
	Get the scheduler associated with this tree node's root.

const Scheduler *	getScheduler (const bool must_exist=false) const

WeakPtr	getWeakPtr ()
	Gets a weak pointer to this TreeNode. This weak pointer is guaranteed to expire when this TreeNode is destructed unless locked.

ConstWeakPtr	getWeakPtr () const
	Const variant of getWeakPtr.

virtual void	addLink (TreeNode *node, const std::string &label)
	Link this tree node with another tree node.

virtual void	activateLink (const std::string &label)
	Activate one of the links added with addLink.

	TreeNode ()=delete
	Not default-constructable.

	TreeNode (const TreeNode &)=delete
	Not copy-constructable.

	TreeNode (TreeNode &&rhp)
	Move constructor.

TreeNode &	operator= (const TreeNode &)=delete
	Not assign-constructable.

	TreeNode (TreeNode *parent, const std::string &name, const std::string &group, group_idx_type group_idx, const std::string &desc, bool is_indexable)
	TreeNode full constructor. Initializes node and adds it as a child of an existing tree node (if parent is not null).

	TreeNode (TreeNode *parent, const std::string &name, const std::string &group, group_idx_type group_idx, const std::string &desc)
	TreeNode constructor with no is_indexable parameter [defaults to true].

	TreeNode (const std::string &name, const std::string &group, group_idx_type group_idx, const std::string &desc)
	TreeNode constructor with no parent Node.

	TreeNode (TreeNode *parent, const std::string &name, const std::string &desc)
	TreeNode constructor with no group information.

	TreeNode (TreeNode *parent, const std::string &group, group_idx_type group_idx, const std::string &desc)
	TreeNode constructor for anonymous node with group information.

	TreeNode (const std::string &name, const std::string &desc)
	TreeNode constructor with no parent node or group information.

virtual	~TreeNode ()
	Virtual destructor.

void	addAlias (const std::string &alias)
	Add a single alias for this node.

void	addAliases (const AliasVector &v)
	Adds each element of a vector of aliases to this node..

void	addTag (const std::string &tag)
	Adds single tag to this node.

void	addTags (const std::vector< std::string > &v)
	Adds each elements of a vector of tags to this node.

virtual std::string	stringize (bool pretty=false) const
	Create a string representation of this node.

void	stringizeTags (std::stringstream &ss) const
	Render tags to a string in the form: " tags:[tag0, tag1]" If there are any tags. The leading space makes this a useful sub-utility of stringize because if there are no tags, returns empty string with no leading space.

node_uid_type	getNodeUID () const
	Gets the unique ID of this node.

const std::string &	getName () const override
	Gets the name of this node.

const std::string *	getNamePtr () const
	Gets the name of this node's string pointer which isinterned in StringManager)

bool	isAnonymous () const
	Is this node anonymous.

bool	isExpired () const
	Is this expired (i.e. has it been the rhp of a move constructor)

bool	isIndexableByGroup () const
	Returns whether this object is accessible through its parent's interfaces for getting children by group and index.

const std::string &	getGroup () const
	Gets the group name of this node.

const std::string *	getGroupNamePtr () const
	Gets the group name string pointer (interned in StringManager singleton) of this node.

group_idx_type	getGroupIdx () const
	Gets the group index of this node.

const std::vector< const std::string * > &	getTags () const
	Gets the set of tags associated with this TreeNode.

bool	hasTag (const std::string &tag) const
	Does this node have a specific tag (by name)

bool	hasTag (const std::string *interned_tag_name) const
	Does this node have a specific tag (by string pointer interned with StringManager). This is faster than the alternate hasTag method because it relies only on pointer comparisons.

const std::string &	getDesc () const
	Gets the description of this node.

bool	isBuiltin () const
	Is this node in the builtins group.

void	markHidden (bool hidden=true)
	Marks this TreeNode hidden for the purposes of printint out nodes. This does not make the node inaccessible, but causes it (and its subtree) to be hidden from typical recursive tree printouts.

bool	isHidden () const
	Is this TreeNode supposed to be hidden during tree printouts This value does not have to be respected by anything using TreeNode and is mainly a UI/printout convenience.

void	validateName (const std::string &nm)
	Validates the given name string for this TreeNode. Does not consider context (e.g. name collisions)

void	validateGroup (const std::string &name, const std::string &group, group_idx_type idx)
	Validates the given group name string and group index for this TreeNode. Does not consider context (e.g. name collisions)

void	validateDesc (const std::string &desc)
	Validates the given description string for this TreeNode.

void	addExtensionParameters (const std::string &extension_name, std::unique_ptr< ParameterSet > extension_params)
	Add a named parameter set to extend this tree node's metadata.

void	addExtensionFactory (const std::string &extension_name, std::function< ExtensionsBase *()> factory)
	Add an extension factory to this tree node by its type (name). This method does not actually create any objects at this time. It will validate and create the extension only if asked for later on during simulation.

ExtensionsBase *	getExtension (const std::string &extension_name)
	Get an extension object by type string. Returns nullptr if not found (unrecognized).

ExtensionsBase *	getExtension ()
	Get an extension without needing to specify any particular type string. If no extensions exist, returns nullptr. If only one extension exists, returns that extension. If more than one extension exists, throws an exception.

const std::set< std::string > &	getAllExtensionNames ()
	Extension names, if any. Tree node extensions are typically instantiated on-demand for best performance (you have to explicitly ask for an extension by its name, or it won't be created) - so note that calling this method will trigger the creation of all this node's extensions. The performance cost is proportional to the number of nodes in the virtual parameter tree.

void	addChild (TreeNode *child, bool inherit_phase=true)
	Adds a TreeNode to this node as a child.

void	addChild (TreeNode &child)
	AddChild by reference for convenience.

void	makeSubtreePrivate ()
	Make the entire subtree private.

void	setScopeRoot ()

bool	isScopeRoot () const

void	lockdownParameters ()
	Method to put the device tree in lockdown phase. All LOCKED and HIDDEN parameters are frozen after this point. Regular parameters are not affected by this phase. This method requires a Simulation pointer and will assert at compile time if anyone tries to lockdown the tree without the context of a Simulation.

virtual bool	isAttached () const
	Is this node part of a device tree with a proper RootTreeNode at the root.

virtual TreeNode *	getParent ()
	Gets immediate parent of this node if one exists.

virtual const TreeNode *	getParent () const

template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type>
const T	getParentAs (bool must_exist=true) const
	Retrieves a parent casted to type T* if this node has a parent.

template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type>
const T *	getParentAs (bool must_exist=true) const

template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type>
T	getParentAs (bool must_exist=true)

template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type>
T *	getParentAs (bool must_exist=true)

virtual TreeNode *	getRoot ()
	Gets farthest ancestor of this node.

virtual const TreeNode *	getRoot () const

TreeNode *	getScopeRoot ()

const TreeNode *	getScopeRoot () const

const TreeNode *	getExpectedRoot () const
	build-time equivalent to getRoot before an object is actually attached to a tree. This is a mainly a framework and debugging tool for determining what the root of a node being constructed will be when complete

app::Simulation *	getSimulation () const
	Gets the simulation (if any) associated with this tree.

uint32_t	getNumChildren () const
	Gets the number of children that this node has including those in the sparta builtins group.

TreeNode *	getChildAt (uint32_t idx) const
	Gets a child at a position in the children vector in the order in which they were added to this node.

const ChildrenVector	getChildren () const
	Gets a vector of all children of this node in any group in the order in which they were added to this node.

uint32_t	getChildren (std::vector< TreeNode * > &results, bool ignore_builtin_group=true, bool ignore_anonymous_nodes=true)
	Gets all children of this node in the order in which they were added to this node.

template<class T >
uint32_t	getChildrenOfType (std::vector< T * > &results) const
	return all the children matching a particular type using dynamic cast.

sparta::TreeNode *	findAncestorByName (const std::string &name)
	Find ancestor by name.

template<typename T >
sparta::TreeNode *	findAncestorByType ()
	Find ancestor by type.

sparta::TreeNode *	findAncestorByTag (const std::string &tag)
	Find the first ancestor with a particular tag.

template<typename T >
T *	findAncestorResourceByType ()
	Find an ancestor's resource with a certain type.

const AliasVector &	getAliases () const
	Gets a vector of all aliases of this node.

uint32_t	getChildrenIdentifiers (std::vector< std::string > &idents, bool ignore_builtin_group=true) const
	Gets all child identifiers, aliases, group names, and group-aliases which can be used to refer to a child of this node.

std::vector< const std::string * >	getIdentifiers () const
	Gets all the identifiers for this node (excluding groups)

uint32_t	getGroupSize (const std::string &group)
	Gets the number of nodes in a group.

group_idx_type	getGroupIndexMax (const std::string &group)
	Gets the largest index of a node in the given group.

uint32_t	getGroup (const std::string &group, std::vector< TreeNode * > &results)
	Gets all nodes in a child group.

uint32_t	findChildren (const std::string &pattern, std::vector< TreeNode * > &results, std::vector< std::vector< std::string > > &replacements)
	Finds all children starting at this node with a given pattern relative to this node by matching names an aliases. Appends each found child to <results>.

uint32_t	findChildren (const std::string &pattern, std::vector< TreeNode * > &results)
	Version of findChildren with no replacements vector.

virtual uint32_t	findImmediateChildren_ (std::regex &expr, std::vector< TreeNode * > &found, std::vector< std::vector< std::string > > &replacements, bool allow_private=false)
	Finds immediate children with some identity (name or alias) matching a regex.

uint32_t	findImmediateChildren_ (std::regex &expr, std::vector< TreeNode * > &found, bool allow_private=false)
	Variant of findImmediateChildren_ with no replacements vector.

virtual uint32_t	findImmediateChildren_ (std::regex &expr, std::vector< const TreeNode * > &found, std::vector< std::vector< std::string > > &replacements, bool allow_private=false) const
	Const-qualified variant of findImmediateChildren_.

uint32_t	findImmediateChildren_ (std::regex &expr, std::vector< const TreeNode * > &found, bool allow_private=false) const
	Variant of const-qualified findImmediateChildren_ with no replacements vector.

bool	locationMatchesPattern (const std::string &pattern, const TreeNode *pat_loc) const
	Determines if the given pattern (which may contain wildcards) can describe this node.

TreeNode *	getChild (const std::string &name, bool must_exist=true)
	Retrieves a child with this dotted path name.

const TreeNode *	getChild (const std::string &name, bool must_exist=true) const
	Overloaded const-qualified.

std::string	getDeepestMatchingPath (const std::string &path) const
	Gets the deepest whole node location starting from this node that matches some part of path starting at its beginning.

bool	hasChild (const std::string &name) const noexcept
	Determines if a child can be found with the given dotted path.

bool	hasImmediateChild (const TreeNode *n) const noexcept
	Determines if the node n is an immediate child of this node.

template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type, class ConstT = typename ptr_to_const_obj_ptr<T>::type>
const ConstT	getChildAs (const std::string &name, bool must_exist=true) const
	Retrieves a child that is castable to T with the given dotted path.

template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type>
const T *	getChildAs (const std::string &name, bool must_exist=true) const

template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type>
T	getChildAs (const std::string &name, bool must_exist=true)

template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type>
T *	getChildAs (const std::string &name, bool must_exist=true)

template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type, class ConstT = typename ptr_to_const_obj_ptr<T>::type>
ConstT	getAs () const
	Retrieves this node after casting to type T.

template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type>
const T *	getAs () const
	Retrieves this node after casting to type const T.

template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type>
T	getAs ()
	Retrieves this node after casting to type const T.

template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type>
T *	getAs ()
	Retrieves this node after casting to type const T.

uint32_t	findChildrenByTag (const std::string &tag, std::vector< TreeNode * > &results, int32_t max_depth=-1)
	Finds a set of all children having the selected tag which this node or descendants of this node within a distance of the given max_depth.

bool	isDescendantOf (const TreeNode *ancestor, int32_t max_depth=-1) const
	Determines if this node is a descendant of the specified ancestor node within some number of generations (depth).

std::string	getLocation () const override final

std::string	getDisplayLocation () const
	Returns the location of this node in the device tree which might not be usable for navigating the device tree (it cannot be used as an argument for getChild/findChildren).

std::string	getExpectedLocation () const
	build-time equivalent to getLocation before an object is actually attached to a tree. This is a mainly a framework and debugging tool for determining what the location of a node currently being constructed will be when complete.

std::string	renderSubtree (int32_t max_depth=-1, bool show_builtins=false, bool names_only=false, bool hide_hidden=false, bool(leaf_filt_fxn)(const TreeNode )=nullptr) const
	Renders the subtree starting at this node as a string containing an indentation-based depth-first representation.

uint32_t	getLevel () const
	Gets the level of this node. 0 is root.

template<typename T >
uint32_t	getRecursiveNodeCount () const
	Recursively gets the count of a nodes that are a subclass of a particular type (determined by dynamic_cast). Includes all descendants of this node in the tree, but excludes this node.

uint32_t	getPossibleNotifications (std::vector< NotificationInfo > &infos) const
	Gets information on the possible notifications generated by this node (excludes children).

void	dumpPossibleNotifications (std::ostream &o) const noexcept
	Dumps a listing of the notifications which this node can generate to the ostream o.

template<typename DataT = ANY_TYPE>
uint32_t	locateNotificationSources (std::vector< TreeNode * > &nodes, const std::string &name="")
	Gets all possible notification info from NotificationSources within this node's subtree.

template<typename DataT = ANY_TYPE>
void	dumpLocatedNotificationSources (std::ostream &o, const std::string &name="")
	Retrieves the relevant NotificationSources from locateNotificationSources and prints them to the output o.

uint32_t	getPossibleSubtreeNotifications (std::vector< NotificationInfo > &infos) const noexcept
	Gets information on the possible notifications generated by this node and all its descendants.

void	dumpPossibleSubtreeNotifications (std::ostream &o) const noexcept
	Dumps a listing of the notifications which this node and its descendants can generate to the ostream o.

bool	canGenerateNotification (const std::type_info &tinfo, const std::string *name) const
	Can this TreeNode generate a notification of the given type having the given name or pattern.

bool	canGenerateNotification (const std::type_info &tinfo, const std::string &name) const
	Can this TreeNode generate a notification of the given type having the given name (does not require interned string - will intern automatically with StringManager).

bool	canGenerateNotification (const NotificationInfo &info) const
	Can this TreeNode generate a notification of the given NotificationInfo.

bool	canSubtreeGenerateNotification (const std::type_info &tinfo, const std::string *name) const
	Can this TreeNode or its descendants (of any distance) generate a notification of the given type having the given name.

bool	canSubtreeGenerateNotification (const std::type_info &tinfo, const std::string &name) const
	Can this TreeNode or its descendants (of any distance) generate a notification of the given type having the given name (does not require interned string)

bool	canSubtreeGenerateNotifications (const std::type_info &tinfo, const std::vector< const std::string * > &names) const
	Checks to see if any a subtree can generate any of several notification names which may be patterns.

template<typename DataT , typename T , void(T::*)(const TreeNode &, const TreeNode &, const DataT &) TMethod>
void	registerForNotification (T *obj, const std::string &name, bool ensure_possible=true)
	Registers a callback method to listen for all notifications having the specified data type DataT and name (or any name if name is "") occuring on this node or any descendant (subtree).

template<typename DataT , typename T , void(T::*)(const DataT &) TMethod>
void	registerForNotification (T *obj, const std::string &name, bool ensure_possible=true)

template<typename DataT , typename T , void(T::*)(const TreeNode &, const TreeNode &, const DataT &) TMethod>
void	deregisterForNotification (T *obj, const std::string &name)
	Removes at most one registration made with registerForNotification.

template<typename DataT , typename T , void(T::*)(const DataT &) TMethod>
void	deregisterForNotification (T *obj, const std::string &name)

bool	hasObserversRegisteredForNotification (const std::type_info &tinfo, const std::string *name) const noexcept
	Determines if this TreeNode (not descendants) has any observers for this type of event and name.

void	getDelegatesRegisteredForNotification (const std::type_info &tinfo, const std::string *name, std::vector< delegate > &dels) noexcept
	Gets the vector of delegates registered for a notification on this TreeNode.

Public Member Functions inherited from sparta::ResourceContainer
	ResourceContainer ()
	Consturct with a null, unlocked resource.

	ResourceContainer (const ResourceContainer &)=delete
	Copy construction disbled.

	ResourceContainer (ResourceContainer &&)=default
	Move constructor.

virtual	~ResourceContainer ()
	Destructor.

Resource *	getResource ()
	Gets the resource contained by this node if any. May only be called after finalization begins or during teardown.

const Resource *	getResource () const
	Const variant of getResource.

bool	hasResource () const
	Determines if this node has a resource. This method exists in case the TreeNode is being explored by a tool or interactive UI. Typical TreeNode clients (such as Resources) will assume that there is a resource if they are expecting one.

template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type>
const T	getResourceAs () const
	Gets the resource contained by this node (if any) as the given type.

template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type>
const T *	getResourceAs () const
	Overload of getResourceAs for const access with a non-pointer template type.

template<class T , typename = typename std::enable_if<std::is_pointer<T>::value>::type>
T	getResourceAs ()
	Non-const overload of getResourceAs.

template<class T , typename = typename std::enable_if<!std::is_pointer<T>::value>::type>
T *	getResourceAs ()
	Non-const overload of getResourceAs.

virtual std::string	getResourceType () const
	Gets the typename of the resource that this node will eventually contain.

virtual std::string	getResourceTypeRaw () const
	Gets the typename of the resource that this node will eventually contain.

Public Member Functions inherited from sparta::PhasedObject
	PhasedObject (PhasedObject &&)=default

TreePhase	getPhase () const
	Gets the trees current phase.

virtual bool	isBuilding () const
	Is this node (and thus the entire tree above and below it) currently in the TREE_BUILDING phase.

virtual bool	isBuilt () const
	Is this node (and thus the entire tree above it) "built". Checks that getPhase has passed TREE_BUILDING.

virtual bool	isConfigured () const
	Is this node (and thus the entire tree above it) "configured". Checks that getPhase has passed TREE_CONFIGURING (i.e. FINALIZED, FINALIZING, TEARDOWN, etc).

virtual bool	isConfiguring () const
	Is this node (and thus the entire tree above it) currently in the TREE_CONFIGURING phase.

virtual bool	isFinalizing () const
	Is this node (and thus the entire tree above it) "finalized".

virtual bool	isFinalized () const
	Is this node (and thus the entire tree above it) "finalized".

virtual bool	isTearingDown () const
	Is this node (and thus the entire tree above it) in the "teardown" phase.

Public Member Functions inherited from sparta::ArchDataContainer
std::vector< ArchData * >	getAssociatedArchDatas ()
	Retrieves all ArchDatas associated with this TreeNode so that children can use it to allocate their data.

const std::vector< ArchData * >	getAssociatedArchDatas () const
	Const variant of getAssociatedArchDatas.

	ArchDataContainer ()=default
	Default constructor.

	ArchDataContainer (ArchDataContainer &)=delete
	Copy construction disabled.

	ArchDataContainer (ArchDataContainer &&)=default
	Move constructor.

virtual	~ArchDataContainer ()
	Virtual destructor.

Static Public Attributes
static constexpr bank_idx_type	BANK_IDX_DEFAULT = 0
	Default index for bank when no bank is specified. A bank having this index will always exist.

static constexpr ident_type	INVALID_ID = DataView::INVALID_ID
	Represents an invalid Register ID.

static constexpr group_num_type	GROUP_NUM_NONE = ~(group_num_type)0
	Represents no group much like sparta::TreeNode::GROUP_NAME_NONE.

static const Definition	DEFINITION_END
	Entry indicating the end of a sparta::Register::Definition array.

Static Public Attributes inherited from sparta::TreeNode
static const group_idx_type	GROUP_IDX_NONE = (group_idx_type)-1
	GroupIndex indicating that a node has no group index because it belongs to no group.

static const node_uid_type	MAX_NODE_UID
	Maximum value of node_uid_ before the framework throws an exception.

static constexpr char	GROUP_NAME_NONE [] = ""
	Group name indicating that a node belongs to no group.

static constexpr char	NODE_NAME_NONE [] = ""
	Node name for anonymous node.

static const std::string	DEBUG_DUMP_SECTION_DIVIDER
	String dividing sections in a debug dump file.

static constexpr char	NODE_NAME_VIRTUAL_GLOBAL [] = "_SPARTA_virtual_global_"
	Node name for the virtual glopbal node.

static constexpr char	LOCATION_NODE_SEPARATOR_ATTACHED = '.'
	Separator character between node identifiers in a location string when the child is attached to the parent.

static constexpr char	LOCATION_NODE_SEPARATOR_EXPECTING = ','
	Separator character between node identifiers in a location string when the child is being attached to the parent but has not been entirely attached (i.g. during construction of the child node)

static constexpr char	LOCATION_NODE_SEPARATOR_UNATTACHED = '~'
	Separator character preceding a node identifiers in a location string when that node has no parent and is not in the process of being attached to one.

static const uint32_t	RENDER_SUBTREE_INDENT = 2
	Spaces to indent for each tree level in sparta::TreeNode::renderSubtree.

static constexpr char	GROUP_NAME_BUILTIN [] = "_SPARTA_builtin_group_"
	Reserved name for built-in nodes.

static const uint64_t	CHILD_FIND_THRESHOLD = 100000
	Threshold for number of findChildren calls after finalization before a warning message is printed about framework misuse.

static const uint64_t	CHILD_GET_THRESHOLD = 100000
	Threshold for number of getChild calls after finalization before a warning message is printed about framework misuse.

static const uint32_t	TEARDOWN_ERROR_LIMIT = 5
	Number of teardown-phase-related messages that can be printed before the rest will be suppressed.

static const std::vector< std::pair< const char *, std::function< void(std::string &)> > >	TREE_NODE_PATTERN_SUBS
	List of pattern susbtitutions when creating a search pattern from a TreeNode name containing wildcards.

Protected Member Functions
virtual void	onAddingChild_ (TreeNode *child) override
	React to child registration.

virtual void	read_ (void *buf, size_t size, size_t offset=0)=0

virtual void	peek_ (void *buf, size_t size, size_t offset=0) const =0

virtual void	write_ (const void *buf, size_t size, size_t offset=0)=0

virtual void	poke_ (const void *buf, size_t size, size_t offset=0)=0

virtual void	dmiRead_ (void *buf, size_t size, size_t offset=0) const

virtual void	dmiWrite_ (const void *buf, size_t size, size_t offset=0)

Protected Member Functions inherited from sparta::TreeNode
std::pair< uint32_t, std::string >	recursGetDeepestMatchingPath_ (const std::string &path, size_t name_pos) const
	Finds the deepest node path mathing the input path. Implements getDeepestMatchingPath.

void	setExpectedParent_ (const TreeNode *parent)
	Tracks a node as an expected parent without actually adding this node as a child. This is used almost exclusively for printing error messages which include a device-tree location BEFORE actually inserting this node into the device tree since node construction can fail.

void	enterFinalizing_ ()
	Recursively enter TREE_FINALIZING phase.

void	finalizeTree_ ()
	Recursively create resources based on tree configuration. enter_finalize_ should be invoked after this method successfully completes for an entire tree. Finalizes in the order of construction.

void	validateTree_ ()
	Iterates the finalized tree and validates each node (e.g. ensures statistics can be evaluated)

void	enterFinalized_ ()
	Recursively enter TREE_FINALIZED phase.

void	enterConfig_ () noexcept
	Recursively enter TREE_CONFIGURING phase.

void	bindTreeEarly_ ()
	Recursively invoke TreeNode::onBindTreeEarly_ and Resource::onBindTreeEarly_ (in that order for each node)

void	bindTreeLate_ ()
	Recursively invoke TreeNode::onBindTreeEarly_ and Resource::onBindTreeLate_ (in that order for each node)

void	simulationTerminating_ ()
	Hook to allow simulation resources to clean-up before simulation is ended.

void	validatePostRun_ (const PostRunValidationInfo &info) const
	Hook to check the state of the simulator post-run and throw exceptions if something is incorrect.

void	dumpDebugContent_ (std::ostream &out) const noexcept
	Allows resources to write out detailed textual debugging information about the node. This is typically called by a simulator when shutting down due to an exception (or depending on simulator config). However, it could also be called at other times.

void	enterTeardown_ () noexcept
	Recursively enter TREE_TEARDOWN phase while alerting nodes through onEnteringTeardown_ and alterting Resources through Resource::onStartingTeardown_. Nodes already in TREE_TEARDOWN phase will not be alerted (neither will their associated Resources). All nodes are visited regardless of their parent's phase.

void	verifyUniqueChildIdentifier_ (const std::string &ident, bool ignore_group_collision=false)
	Verifies that the given identifier is unique for all children of this node by comparing against names, groups, and aliases. Throws SpartaException if not unique.

void	removeChildForTeardown_ (TreeNode *child)
	"Removes" the given child by invoking onDestroyingChild_ then removing this child from the children_ list

void	removeFromParentForTeardown_ (TreeNode *parent)
	Protected Wrapper for getParent()->removeChildForTeardown_ which allows subclases of TreeNode to indirectly invoke removeChildForTeardown_ with themselves as the argument.

void	detachFromParent_ ()
	Removes a node from its parent with the expectation this node will be immediately destroyed (i.e. is an xvalue)

void	detachFromChildren_ ()
	Removes a node from its children with the expectation this node will be immediately destroyed (i.e. is an xvalue)

bool	areParametersLocked_ () const
	This method informs whether the tree is past the lockdown phase for all LOCKED and HIDDEN parameters. Modifying LOCKED and HIDDEN parameters after this phase is disallowed. Tree can be locked down during TREE_BUILDING phase or TREE_CONFIGURING phase. During TREE_FINALIZING phase, all parameters are locked down as is.

template<typename DataT >
void	postPropagatingNotification_ (const TreeNode origin, const DataT &data, const std::string name_id)
	Starts a notification propagating up the tree.

template<typename DataT , typename T , void(T::*)(const TreeNode &, const TreeNode &, const DataT &) TMethod>
DelegateVector::iterator	findDelegate_ (DelegateVector &dvec, T *obj, const std::string &target_name)
	Finds a delegate associated with the given type T, object pointer, DataT, and TMethod within a DelevateVector. The intent of this function is to help see if a delegate is already registered with a calback by checking all known information associated with that callback against the input arguments.

template<typename DataT , typename T , void(T::*)(const DataT &) TMethod>
DelegateVector::iterator	findDelegate_ (DelegateVector &dvec, T *obj, const std::string &target_name)

virtual void	broadcastRegistrationForNotificationToChildren_ (const std::type_info &tinfo, const std::vector< const std::string * > &name_ids, TreeNode obs_node, const delegate del, const bool allow_private)
	Recursively notifies children that the notification described is now (or still is) being observed at the observation point TreeNode obs_node with the newly registered delegate del.

virtual void	broadcastDeregistrationForNotificationToChildren_ (const std::type_info &tinfo, const std::vector< const std::string * > &name_ids, TreeNode obs_node, const delegate del, const bool allow_private)
	Recursively notifies children that the notification described has lost one particular observer (del) which was observing at the observation point TreeNode obs_node with the delegate del.

void	broadcastRegistrationForNotificationListStringToChildren_ (const std::type_info &tinfo, const std::string &name, TreeNode obs_node, const delegate del, const bool private_only)
	Entry point to broadcastRegistrationForNotificationToChildren_ recursion. Breaks a name string.

void	broadcastDeregistrationForNotificationListStringToChildren_ (const std::type_info &tinfo, const std::string &name, TreeNode obs_node, const delegate del, const bool private_only)
	Symmetric oppostie of broadcastRegistrationForNotificationListStringToChildren_.

template<typename DataT >
void	invokeDelegatesOn_ (TreeNode to_invoke, const DataT &data, const std::string name_id)
	Protected wrapper for invokeDelegates_ which allows a TreeNode to invoke delegates on another TreeNode using itself as the origin.

Protected Member Functions inherited from sparta::ResourceContainer
std::string	getResourceTypeName_ () const
	Gets the rtti type name (demangled) of the resource type held by this container. If there is no resource held, returns empty string.

void	setResource_ (Resource *r)
	Allows subclasses to assign the resource associated with this node.

void	unsetResource_ ()
	Allows a resource to unset the resource set with setResource_.

void	lockResource_ ()
	Allows subclasses to assign the resource associated with this node.

Resource *	getResource_ () noexcept
	Returns the currently held resource of this node (if any). This method can be called at any time.

const Resource *	getResource_ () const noexcept
	Const variant of getResource_.

Protected Member Functions inherited from sparta::PhasedObject
void	setPhase_ (TreePhase phase)
	Sets the current phase.

Friends
class	Field
	Allow Fields to access register internals (e.g. dview_)

Additional Inherited Members
Static Public Member Functions inherited from sparta::TreeNode
static std::string	createSearchRegexPattern (const std::string &pat)
	Compute a regex pattern for a node child path containing any number of wildcard characters (not a dot-separated location) which can be used to test against child node names.

static bool	hasWildcardCharacters (const std::string &name)
	Determines if a given node name has any wildcard characters which will be substituted in createSearchRegexPattern.

static std::string	getNextName (const std::string &name, size_t &pos)
	Gets the next name between two '.' chars in a string starting at pos.

static bool	matchesGlobLike (const std::string &pattern, const std::string &other)
	Determine if a glob-like search pattern matches some other string.

static const std::map< const TreeNode *, WeakPtr > &	getParentlessNodes ()

static const std::map< const TreeNode *, WeakPtr > &	getAllNodes ()
	Gets the vector of all TreeNodes currently known to be constructed.

static std::string	formatAllNodes ()
	Prints the list of all TreeNodes currently known to be constructed.

static bool	isNodeConstructed (const TreeNode *)
	Is a given node constructed?

static TreeNode *	getVirtualGlobalNode ()
	Gets the virtual global node singleton. This node can have no parent and no children. It receives notifications from all nodes in the simulator as if it were the parent of every node in the simulation that has no parent.

static std::vector< const std::string * >	parseNotificationNameString (const std::string &csl)
	Parses a comma-separated list of notification names (or patterns) separated by commas and ignoring whitespace around commas.

static bool	notificationCategoryMatch (const std::string query_id, const std::string node_id)
	Checks if two notification categories match where one is an actual category.

Protected Types inherited from sparta::TreeNode
typedef std::vector< delegate >	DelegateVector
	Vector of delegates representing a list of observers to notify.

typedef std::map< type_info_container, DelegateVector >	NotificationObserverMap
	Map of delegate vectors containing all observers.

Static Protected Member Functions inherited from sparta::TreeNode
static bool	identityMatchesPattern_ (const std::string &ident, std::regex &expr, std::vector< std::string > &replacements)
	Performs pattern matching on a identity string.

static bool	identityMatchesPattern_ (const std::string &ident, std::regex &expr)
	Variant of identityMatchesPattern_ with no replacements vector.

static std::string	getPreviousName_ (const std::string &name, size_t &pos)
	Gets the previous name between two '.' chars in a string starting at pos.

Detailed Description

Base class to represents an architected register of any size that is a power of 2 and greater than 0 with a ceiling specified.

Note: Maximum register size is constrained by the ArchData instance where the register value resides. This is a property of the sparta::RegisterSet which owns this sparta::Register.

A sparta::Register may contain any number of sparta::Register::Field instances refering to bit ranges within the Register. These ranges may overlap within the register, have no alignment restrictions, and must be greater and must be at least 1 bit wide. See sparta::Register::Field for the maximum size constraint.

Constructed based on a parent sparta::TreeNode, which should be a sparta::RegisterSet, as well as a sparta::Register::Definition describing the structure of the register and a sparta::ArchData where the Register data will reside. Generally, Registers are only constructed (and then owned) by sparta::RegisterSet instances.

sparta::Register is a subclass of TreeNode, which allows a name, parent, aliases, and group information. A sparta::RegisterSet parent may also use TreeNode get/find facilities for obtaining pointers to children by name

Register itself is not meant to be overloaded. It is important to keep access methods as inline templated methods for performance. Making them virtual would negatively impact performance. This class comprises little other functionality; only some const attributes and helper functions.

Contains NotificationSource child nodes for types sparta::Register::ReadAccess and sparta::Register::PostWriteAccess. See getPostWriteNotificationSource and getReadNotificationSource.

Todo:: Add register notifications between compound registers

Definition at line 62 of file Register.hpp.

Member Typedef Documentation

◆ AliasVector

typedef std::vector<const char*> sparta::RegisterBase::AliasVector

Vector of Register Aliases.

Definition at line 103 of file Register.hpp.

◆ bank_idx_type

typedef uint32_t sparta::RegisterBase::bank_idx_type

Numeric bank identifier for bank lookup.

Note: Must be unsigned

Definition at line 98 of file Register.hpp.

◆ FieldVector

typedef std::vector<Field*> sparta::RegisterBase::FieldVector

Vector of Register Fields.

Definition at line 108 of file Register.hpp.

◆ group_idx_type

typedef TreeNode::group_idx_type sparta::RegisterBase::group_idx_type

TreeNode group index.

Definition at line 92 of file Register.hpp.

◆ group_num_type

typedef uint32_t sparta::RegisterBase::group_num_type

Numeric group identifier for register lookup.

Definition at line 87 of file Register.hpp.

◆ ident_type

typedef DataView::ident_type sparta::RegisterBase::ident_type

Identifier to distinguish from other registers in the same RegisterSet.

Definition at line 72 of file Register.hpp.

◆ index_type

typedef DataView::index_type sparta::RegisterBase::index_type

Index of read/write access within register.

Definition at line 77 of file Register.hpp.

◆ PostWriteNotiSrc

typedef NotificationSource<PostWriteAccess> sparta::RegisterBase::PostWriteNotiSrc

Notification type for Register write accesses.

Definition at line 514 of file Register.hpp.

◆ ReadNotiSrc

typedef NotificationSource<ReadAccess> sparta::RegisterBase::ReadNotiSrc

Notification type for Register read accesses.

Definition at line 474 of file Register.hpp.

◆ register_read_callback_type

typedef std::function<sparta::utils::ValidValue<uint64_t>(RegisterBase*)> sparta::RegisterBase::register_read_callback_type

Register read callback.

Definition at line 113 of file Register.hpp.

◆ register_write_callback_type

typedef std::function<bool(RegisterBase*, uint64_t)> sparta::RegisterBase::register_write_callback_type

Register write callback.

Definition at line 118 of file Register.hpp.

◆ size_type

typedef DataView::offset_type sparta::RegisterBase::size_type

Size of register and bit or byte offset within register data.

Definition at line 82 of file Register.hpp.

Constructor & Destructor Documentation

◆ RegisterBase()

sparta::RegisterBase::RegisterBase	(	TreeNode *	parent,
		const Definition &	def
	)

inline

Register constructor.

Parameters

parent	parent node
def	array of sparta::Register::Definition objects, terminated with a Definition having a NULL name field. See DEFINITION_END. Also see Register::Field::Definition fields for details
adata	ArchData in which to store this register's valu This array and its content must exist for the duration of this Register since a reference will be kept to the Definition and any Fields or aliases within that definition.

Postcondition: Computes a write mask for this register with which all writes will be filtered before being written to memory. Note that bits in the register not covered by a field are considered writable and readable. Overlapping fields with conflicing read-only flags result the register having read-only bits matching all fields flagged as read-only. That is, bits default to read-write, but once a field with a read-only flag is encountered, the bits it comprises are permanently marked as read-only regardless of any read-write fields containing those bits

Definition at line 716 of file Register.hpp.

Here is the call graph for this function:

◆ ~RegisterBase()

virtual sparta::RegisterBase::~RegisterBase ( )

inlinevirtual

Destructor.

Deletes all fields allocated by this instance

Definition at line 787 of file Register.hpp.

Member Function Documentation

◆ addField()

Field * sparta::RegisterBase::addField ( const Field::Definition & fd )

inline

Create a new field in this Register based on the given Field::Definition.

Parameters

fd	Field Definition describing the new field to create. fd must exist for the duration of this object since a reference will be kept.

Precondition: Register TreeNode cannot be built

Deliberately allows addition of fields through this interface in addition to those in the Register::Definition with which this Register was constructed.

This method is also used internally to add fields from the Register::Definition specified at construction.

Definition at line 824 of file Register.hpp.

Here is the call graph for this function:

◆ addReadCB()

void sparta::RegisterBase::addReadCB ( register_read_callback_type callback )

inline

Registers a callback for obtaining a 32- or 64-bit register value.

Definition at line 1264 of file Register.hpp.

◆ addWriteCB()

void sparta::RegisterBase::addWriteCB ( register_write_callback_type callback )

inline

Registers a callback for writing a 32- or 64-bit register value.

Definition at line 1280 of file Register.hpp.

◆ dmiRead()

template<typename T >

T sparta::RegisterBase::dmiRead ( index_type idx = 0 ) const

inline

Read value directly from the Register's backing store.

Definition at line 1070 of file Register.hpp.

◆ dmiRead_()

virtual void sparta::RegisterBase::dmiRead_	(	void *	buf,
		size_t	size,
		size_t	offset = `0`
	)		const

inlineprotectedvirtual

Definition at line 1320 of file Register.hpp.

◆ dmiWrite()

template<typename T >

void sparta::RegisterBase::dmiWrite	(	T	val,
		index_type	idx = `0`
	)

inline

Write a value directly to this Register's backing store.

Note: No masking, boundary checkor or notification is performed

Definition at line 1082 of file Register.hpp.

◆ dmiWrite_()

virtual void sparta::RegisterBase::dmiWrite_	(	const void *	buf,
		size_t	size,
		size_t	offset = `0`
	)

inlineprotectedvirtual

Definition at line 1326 of file Register.hpp.

◆ getDefinition()

const Definition & sparta::RegisterBase::getDefinition ( ) const

inline

Gets the definition supplied during the construciton of this Register.

Returns: References to the same const Definition object supplied at construction.

Definition at line 961 of file Register.hpp.

◆ getField() [1/2]

Field * sparta::RegisterBase::getField ( const std::string & name )

inline

Retrieves a child that is a Register::Field with the given dotted path.

Note: no pattern matching supported in this method; Generally, only immediate children can be fields.

Exceptions

SpartaException if child which is a Register::Field is not found

Definition at line 1163 of file Register.hpp.

◆ getField() [2/2]

const Field * sparta::RegisterBase::getField ( const std::string & name ) const

inline

Retrieves a child that is a Register::Field with the given dotted path.

Note: no pattern matching supported in this method; Generally, only immediate children can be fields.

Exceptions

SpartaException if child which is a Register::Field is not found

Definition at line 1175 of file Register.hpp.

◆ getFields() [1/2]

FieldVector & sparta::RegisterBase::getFields ( )

inline

Gets the full set of register fields.

Definition at line 916 of file Register.hpp.

◆ getFields() [2/2]

const FieldVector & sparta::RegisterBase::getFields ( ) const

inline

Const qualified version of getFields.

Definition at line 921 of file Register.hpp.

◆ getGroupIdx()

group_idx_type sparta::RegisterBase::getGroupIdx ( ) const

inline

Gets the group index of this register as specified in its definition.

Definition at line 862 of file Register.hpp.

◆ getGroupName()

std::string sparta::RegisterBase::getGroupName ( ) const

inline

Gets the name of the group to which this register belongs from its definition.

See also: getGroupNum

Definition at line 853 of file Register.hpp.

◆ getGroupNum()

group_num_type sparta::RegisterBase::getGroupNum ( ) const

inline

Gets the group number of this register as specified in its definition.

Definition at line 846 of file Register.hpp.

◆ getHintFlags()

Definition::HintsT sparta::RegisterBase::getHintFlags ( ) const

inline

Returns the hint flags for this type.

See also: HintFlag

Definition at line 947 of file Register.hpp.

◆ getID()

ident_type sparta::RegisterBase::getID ( ) const

inline

Gets the ID of this register as specified in its definition.

Definition at line 840 of file Register.hpp.

◆ getNumBits()

size_type sparta::RegisterBase::getNumBits ( ) const

inline

Gets the size of this register's value in bits.

Definition at line 872 of file Register.hpp.

◆ getNumBytes()

size_type sparta::RegisterBase::getNumBytes ( ) const

inline

Gets the size of this register's value in bytes.

Definition at line 867 of file Register.hpp.

◆ getNumFields()

size_type sparta::RegisterBase::getNumFields ( ) const

inline

Gets the number of fields within this register.

Definition at line 877 of file Register.hpp.

◆ getPostWriteNotificationSource()

PostWriteNotiSrc & sparta::RegisterBase::getPostWriteNotificationSource ( )

inline

Returns the post-write notification-source node for this register which can be used to observe writes to this register. This notification is posted immediately after the register has been written and populates a sparta::Register::PostWriteAccess object with the results.

Refer to PostWriteNotiSrc (sparta::NotificationSource) for more details. Use the sparta::NotificationSource::registerForThis and sparta::NotificationSource::deregisterForThis methods.

Definition at line 1240 of file Register.hpp.

◆ getReadNotificationSource()

ReadNotiSrc & sparta::RegisterBase::getReadNotificationSource ( )

inline

Returns the read notification-source node for this register which can be used to observe reads to this register. This notification is posted immediately after the register has been read and populates a sparta::Register::ReadAccess object with the results.

Refer to ReadNotiSrc (sparta::NotificationSource) for more details. Use the sparta::NotificationSource::registerForThis and sparta::NotificationSource::deregisterForThis methods.

Definition at line 1256 of file Register.hpp.

◆ getRegDomain()

Definition::RegDomainT sparta::RegisterBase::getRegDomain ( ) const

inline

Returns the regdomain for this type.

See also: RegdomainFlag

Definition at line 953 of file Register.hpp.

◆ getSubsetOf()

ident_type sparta::RegisterBase::getSubsetOf ( ) const

inline

Returns the identity of the compound Register in the same Register set which this register is a subset (refers a subset of bytes in that parent).

Returns: ID of register of which this is a subset if any. If none, returns INVALID_ID

Definition at line 930 of file Register.hpp.

◆ getSubsetOffset()

size_type sparta::RegisterBase::getSubsetOffset ( ) const

inline

Returns the byte offset into the compound Register of which this register is a subset.

See also: getSubsetOf

Returns: byte offset into the register of which this is a subset. If this register is not a subset of another (getSubsetOf() == INVALID_ID), returns returns INVALID_ID

Definition at line 941 of file Register.hpp.

◆ getValueAsByteString()

std::string sparta::RegisterBase::getValueAsByteString ( ) const

inline

Creates a string representing this register's value as a sequence of bytes, separated by a spaces, sorted by address ascending.

* (7) 00 03 00 ad 00 ff ff ba (0)
*

Definition at line 1116 of file Register.hpp.

Here is the call graph for this function:

◆ getWriteMask()

template<typename T >

T sparta::RegisterBase::getWriteMask ( index_type idx = 0 ) const

inline

Get a write mask at the given index of the given size.

Parameters

idx	Index of mask to access. Gets the mask associated with the n'th T in the write mask

Exceptions

SpartaException if idx and type T do not refer to a set of bytes within the size of this register

Definition at line 1095 of file Register.hpp.

Here is the call graph for this function:

◆ getWriteMaskAsBitString()

std::string sparta::RegisterBase::getWriteMaskAsBitString ( ) const

inline

Creats a string representing this register's write-mask as sequence of bits, separated by a space between each byte, sorted by bit-address ascending.

* 00001000 00000011
*

Definition at line 1147 of file Register.hpp.

Here is the call graph for this function:

◆ getWriteMaskAsByteString()

std::string sparta::RegisterBase::getWriteMaskAsByteString ( ) const

inline

Creats a string representing this register's write-mask as sequence of bytes, separated by spaces, sorted by address ascending.

* (7) 00 00 00 00 03 00 00 00 (0)
*

Definition at line 1132 of file Register.hpp.

Here is the call graph for this function:

◆ hasReadCB()

bool sparta::RegisterBase::hasReadCB ( ) const

inline

Returns true if register has a read callback; false otherwise.

Definition at line 1272 of file Register.hpp.

◆ hasWriteCB()

bool sparta::RegisterBase::hasWriteCB ( ) const

inline

Returns true if register has a write callback; false otherwise.

Definition at line 1288 of file Register.hpp.

◆ isBanked()

bool sparta::RegisterBase::isBanked ( ) const

inline

Is this register banked.

Returns: true if banked (register had 1 or more elements in its definition's bank membership vector). false if not unbanked (register had 0 elements in its definition's bank membership vector)

Definition at line 909 of file Register.hpp.

◆ isInBank()

bool sparta::RegisterBase::isInBank ( bank_idx_type bank ) const

inline

Determines if this register is accessible through a specific bank index (assuming that this bank index exists in the owning register set)

Parameters

bank	Bank index

Returns: true if this register is accessible through its containing register set in the specified bank. Alternatively, will return true if this register is unbanked (isBanked() == false) regardless of the value of bank. However, a real registerSet may only have N banks where N is less than the value of bank for the purposes of this test. In this situation, this register would not be available through that register set through bank because bank is not available in that register set. If that register set were to contain bank, then any unbanked register would be available at that bank.

Definition at line 894 of file Register.hpp.

Here is the call graph for this function:

◆ onAddingChild_()

virtual void sparta::RegisterBase::onAddingChild_ ( TreeNode * child )

inlineoverrideprotectedvirtual

React to child registration.

Parameters

child TreeNode child. Typically, this should be downcastable to a sparta::Register::Field. This is a borrowed reference - child is not copied. Child lifetime must exceed that of this Register instance.

Overrides TreeNode::onAddingChild_

Reimplemented from sparta::TreeNode.

Definition at line 1304 of file Register.hpp.

◆ peek() [1/2]

template<typename T >

T sparta::RegisterBase::peek ( index_type idx = 0 ) const

inline

Definition at line 1038 of file Register.hpp.

◆ peek() [2/2]

void sparta::RegisterBase::peek	(	void *	buf,
		size_t	size,
		size_t	offset
	)		const

inline

Definition at line 1190 of file Register.hpp.

◆ poke() [1/2]

void sparta::RegisterBase::poke	(	const void *	buf,
		size_t	size,
		size_t	offset
	)

inline

Definition at line 1211 of file Register.hpp.

◆ poke() [2/2]

template<typename T >

void sparta::RegisterBase::poke	(	T	val,
		index_type	idx = `0`
	)

inline

Poke a value into this regster.

Note: Write-mask is applied.

Definition at line 1050 of file Register.hpp.

Here is the call graph for this function:

◆ pokeUnmasked() [1/2]

void sparta::RegisterBase::pokeUnmasked	(	const void *	buf,
		size_t	size,
		size_t	offset
	)

inline

Definition at line 1220 of file Register.hpp.

◆ pokeUnmasked() [2/2]

template<typename T >

void sparta::RegisterBase::pokeUnmasked	(	T	val,
		index_type	idx = `0`
	)

inline

Poke a value into this regster without it being affected by the write-mask.

Warning: This ignores read-only fields

Definition at line 1061 of file Register.hpp.

Here is the call graph for this function:

◆ read() [1/2]

template<typename T >

T sparta::RegisterBase::read ( index_type idx = 0 )

inline

Read a value from this register.

Definition at line 976 of file Register.hpp.

Here is the call graph for this function:

◆ read() [2/2]

void sparta::RegisterBase::read	(	void *	buf,
		size_t	size,
		size_t	offset
	)

inline

Definition at line 1184 of file Register.hpp.

◆ readWithCheck()

sparta::utils::ValidValue< uint64_t > sparta::RegisterBase::readWithCheck ( )

inline

Read a value from this register, possibly via a user-supplied callback.

Definition at line 986 of file Register.hpp.

Here is the call graph for this function:

◆ reset()

void sparta::RegisterBase::reset ( bool unmasked = true )

inline

Reset this register to its default value.

Note: Uses poke internally so no notifications are posted

Definition at line 798 of file Register.hpp.

Here is the call graph for this function:

◆ write() [1/2]

void sparta::RegisterBase::write	(	const void *	buf,
		size_t	size,
		size_t	offset
	)

inline

Definition at line 1196 of file Register.hpp.

◆ write() [2/2]

template<typename T >

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

inline

Write a value into this register.

Parameters

val	The value to write
idx	The index of the register to write the val

Note: Write-mask is applied

Definition at line 1006 of file Register.hpp.

Here is the call graph for this function:

◆ writeUnmasked() [1/2]

void sparta::RegisterBase::writeUnmasked	(	const void *	buf,
		size_t	size,
		size_t	offset
	)

inline

Definition at line 1205 of file Register.hpp.

◆ writeUnmasked() [2/2]

template<typename T >

void sparta::RegisterBase::writeUnmasked	(	T	val,
		index_type	idx = `0`
	)

inline

Write a value into this register without it being affected by the write-mask.

Warning: This ignores read-only fields

Definition at line 1032 of file Register.hpp.

Here is the call graph for this function:

◆ writeWithCheck()

template<typename T >

bool sparta::RegisterBase::writeWithCheck ( T val )

inline

Write a value to this register, possibly via a user-supplied callback.

Definition at line 1015 of file Register.hpp.

Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ Field

friend class Field

friend

Allow Fields to access register internals (e.g. dview_)

Definition at line 690 of file Register.hpp.

Member Data Documentation

◆ BANK_IDX_DEFAULT

constexpr bank_idx_type sparta::RegisterBase::BANK_IDX_DEFAULT = 0

staticconstexpr

Default index for bank when no bank is specified. A bank having this index will always exist.

Definition at line 127 of file Register.hpp.

◆ DEFINITION_END

const Definition sparta::RegisterBase::DEFINITION_END

static

Entry indicating the end of a sparta::Register::Definition array.

Definition at line 687 of file Register.hpp.

◆ GROUP_NUM_NONE

constexpr group_num_type sparta::RegisterBase::GROUP_NUM_NONE = ~(group_num_type)0

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ AliasVector

◆ bank_idx_type

◆ FieldVector

◆ group_idx_type

◆ group_num_type

◆ ident_type

◆ index_type

◆ PostWriteNotiSrc

◆ ReadNotiSrc

◆ register_read_callback_type

◆ register_write_callback_type

◆ size_type

Constructor & Destructor Documentation

◆ RegisterBase()

◆ ~RegisterBase()

Member Function Documentation

◆ addField()

◆ addReadCB()

◆ addWriteCB()

◆ dmiRead()

◆ dmiRead_()

◆ dmiWrite()

◆ dmiWrite_()

◆ getDefinition()

◆ getField() [1/2]

◆ getField() [2/2]

◆ getFields() [1/2]

◆ getFields() [2/2]

◆ getGroupIdx()

◆ getGroupName()

◆ getGroupNum()

◆ getHintFlags()

◆ getID()

◆ getNumBits()

◆ getNumBytes()

◆ getNumFields()

◆ getPostWriteNotificationSource()

◆ getReadNotificationSource()

◆ getRegDomain()

◆ getSubsetOf()

◆ getSubsetOffset()

◆ getValueAsByteString()

◆ getWriteMask()

◆ getWriteMaskAsBitString()

◆ getWriteMaskAsByteString()

◆ hasReadCB()

◆ hasWriteCB()

◆ isBanked()

◆ isInBank()

◆ onAddingChild_()

◆ peek() [1/2]

◆ peek() [2/2]

◆ poke() [1/2]

◆ poke() [2/2]

◆ pokeUnmasked() [1/2]

◆ pokeUnmasked() [2/2]

◆ read() [1/2]

◆ read() [2/2]

◆ readWithCheck()

◆ reset()

◆ write() [1/2]

◆ write() [2/2]

◆ writeUnmasked() [1/2]

◆ writeUnmasked() [2/2]

◆ writeWithCheck()

Friends And Related Symbol Documentation

◆ Field

Member Data Documentation

◆ BANK_IDX_DEFAULT

◆ DEFINITION_END

◆ GROUP_NUM_NONE