μHAL (v2.7.9)
Part of the IPbus software repository
Classes | Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
uhal::Node Class Reference

A heirarchical node for navigating heirarchical firmwares. More...

#include <uhal/Node.hpp>

Inheritance diagram for uhal::Node:
[legend]
Collaboration diagram for uhal::Node:
[legend]

Classes

class  const_iterator
 

Public Member Functions

virtual ~Node ()
 Destructor. More...
 
const_iterator begin () const
 
const_iterator end () const
 
bool operator== (const Node &aNode) const
 A function to determine whether two Nodes are identical. More...
 
const NodegetNode (const std::string &aId) const
 Retrieve the Node given by a full-stop delimeted name path relative, to the current node. More...
 
template<typename T >
const T & getNode (const std::string &aId) const
 Retrieve the Node given by a full-stop delimeted name path relative, to the current node and cast it to a particular node type. More...
 
std::vector< std::string > getNodes () const
 Return all node IDs known to this HwInterface. More...
 
std::vector< std::string > getNodes (const std::string &aRegex) const
 Return all node IDs known to this connection manager which match a (boost) regular expression. More...
 
const std::string & getId () const
 Return the unique ID of the current node. More...
 
std::string getPath () const
 Return the full path to the current node. More...
 
const uint32_t & getAddress () const
 Return the register address with which this node is associated. More...
 
const uint32_t & getMask () const
 Return the mask to be applied if this node is a sub-field, rather than an entire register. More...
 
const defs::BlockReadWriteModegetMode () const
 Return whether the node represents a single register, a block of registers or a block-read/write port. More...
 
const uint32_t & getSize () const
 Return the maximum size available to a block read/write. More...
 
const defs::NodePermissiongetPermission () const
 Return the read/write access permissions of this node. More...
 
const std::string & getTags () const
 Return the optional tags string which the user can specify for the current node. More...
 
const std::string & getDescription () const
 Return the optional description string which the user can specify for the current node. More...
 
const std::string & getModule () const
 Return the name of the module in which the current node resides. More...
 
const boost::unordered_map< std::string, std::string > & getParameters () const
 Return parameters of the current node. More...
 
const boost::unordered_map< std::string, std::string > & getFirmwareInfo () const
 Return parameters for inferring the VHDL address decoding. More...
 
void stream (std::ostream &aStr, std::size_t aIndent=0) const
 A streaming helper function to create pretty, indented tree diagrams. More...
 
ValHeader write (const uint32_t &aValue) const
 Write a single, unmasked word to a register. More...
 
ValHeader writeBlock (const std::vector< uint32_t > &aValues) const
 Write a block of data to a block of registers or a block-write port. More...
 
ValHeader writeBlockOffset (const std::vector< uint32_t > &aValues, const uint32_t &aOffset) const
 Write a block of data to a block of registers or a block-write port. More...
 
ValWord< uint32_t > read () const
 Read a single, unmasked, unsigned word. More...
 
ValVector< uint32_t > readBlock (const uint32_t &aSize) const
 Read a block of unsigned data from a block of registers or a block-read port. More...
 
ValVector< uint32_t > readBlockOffset (const uint32_t &aSize, const uint32_t &aOffset) const
 Read a block of unsigned data from a block of registers or a block-read port. More...
 
ClientInterfacegetClient () const
 Get the underlying IPbus client. More...
 
std::vector< const Node * > getLineage (const Node &aAncestor) const
 Returns ancestry path of nodes from (but not including) aAncestor to this node. More...
 
bool isChildOf (const Node &aParent) const
 Returns whether this node is child of the function's argument. More...
 

Protected Member Functions

 Node ()
 Empty node. More...
 
 Node (const Node &aNode)
 Copy constructor. More...
 
virtual Nodeoperator= (const Node &aNode)
 Assignment operator. More...
 
virtual Nodeclone () const
 Function to produce a new copy of the current Node. More...
 

Private Member Functions

std::string getRelativePath (const Node &aAncestor) const
 
void getAncestors (std::deque< const Node * > &aPath) const
 Get the full path to the current node. More...
 

Private Attributes

HwInterfacemHw
 The parent hardware interface of which this node is a child (or rather decendent) More...
 
std::string mUid
 The Unique ID of this node. More...
 
uint32_t mPartialAddr
 The register address with which this node is associated. More...
 
uint32_t mAddr
 The register address with which this node is associated. More...
 
uint32_t mMask
 The mask to be applied if this node is a sub-field, rather than an entire register. More...
 
defs::NodePermission mPermission
 The read/write access permissions of this node. More...
 
defs::BlockReadWriteMode mMode
 Whether the node represents a single register, a block of registers or a block-read/write port. More...
 
uint32_t mSize
 The maximum size available to a block read/write. More...
 
std::string mTags
 Optional string which the user can specify. More...
 
std::string mDescription
 Optional string which the user can specify. More...
 
std::string mModule
 The name of the module in which the current node resides. More...
 
std::string mClassName
 Class name used to construct the derived node type. More...
 
boost::unordered_map< std::string, std::string > mParameters
 Additional parameters of the node. More...
 
boost::unordered_map< std::string, std::string > mFirmwareInfo
 parameters to infer the VHDL address decoding More...
 
NodemParent
 The parent of the current node. More...
 
std::vector< Node * > mChildren
 The direct children of the node. More...
 
boost::unordered_map< std::string, Node * > mChildrenMap
 Helper to assist look-up of a particular child node, given a name. More...
 

Friends

class HwInterface
 
class NodeTreeBuilder
 
class DerivedNodeFactory
 
class const_iterator
 

Detailed Description

A heirarchical node for navigating heirarchical firmwares.

Definition at line 85 of file Node.hpp.

Constructor & Destructor Documentation

◆ Node() [1/2]

uhal::Node::Node ( )
protected

Empty node.

Definition at line 51 of file Node.cpp.

Referenced by clone().

◆ Node() [2/2]

uhal::Node::Node ( const Node aNode)
protected

Copy constructor.

Parameters
aNodea node to copy.

Definition at line 73 of file Node.cpp.

References mChildren, and mChildrenMap.

◆ ~Node()

uhal::Node::~Node ( )
virtual

Destructor.

Definition at line 156 of file Node.cpp.

References mChildren, and mChildrenMap.

Member Function Documentation

◆ begin()

Node::const_iterator uhal::Node::begin ( ) const

◆ clone()

Node * uhal::Node::clone ( ) const
protectedvirtual

Function to produce a new copy of the current Node.

Returns
a new copy of the current Node

Definition at line 150 of file Node.cpp.

References Node().

◆ end()

Node::const_iterator uhal::Node::end ( ) const

Definition at line 180 of file Node.cpp.

References const_iterator.

Referenced by uhal::tests::checkIteration(), uhal::detail::getAddressDescription(), and getNodes().

◆ getAddress()

const uint32_t & uhal::Node::getAddress ( ) const

Return the register address with which this node is associated.

Returns
the register address with which this node is associated

Definition at line 260 of file Node.cpp.

References mAddr.

Referenced by uhal::tests::checkProperties(), uhal::detail::compareNodeAddr(), uhal::detail::getAddressOverlaps(), uhal::tests::nodeAddrCompare(), operator==(), uhal::detail::printNodeOverlapDescription(), and uhal::tests::UHAL_TESTS_DEFINE_CLIENT_TEST_CASES().

◆ getAncestors()

void uhal::Node::getAncestors ( std::deque< const Node * > &  aPath) const
private

Get the full path to the current node.

Definition at line 249 of file Node.cpp.

References getAncestors(), and mParent.

Referenced by getAncestors(), getPath(), and getRelativePath().

◆ getClient()

ClientInterface & uhal::Node::getClient ( ) const

Get the underlying IPbus client.

Returns
the IPbus client that will be used to issue a dispatch

Definition at line 675 of file Node.cpp.

References uhal::HwInterface::getClient(), and mHw.

◆ getDescription()

const std::string & uhal::Node::getDescription ( ) const

Return the optional description string which the user can specify for the current node.

Returns
the optional description string which the user can specify for the current node

Definition at line 296 of file Node.cpp.

References mDescription.

Referenced by uhal::tests::checkProperties().

◆ getFirmwareInfo()

const boost::unordered_map< std::string, std::string > & uhal::Node::getFirmwareInfo ( ) const

Return parameters for inferring the VHDL address decoding.

Returns
parameters for inferring the VHDL address decoding

Definition at line 314 of file Node.cpp.

References mFirmwareInfo.

Referenced by uhal::tests::checkProperties().

◆ getId()

const std::string & uhal::Node::getId ( ) const

Return the unique ID of the current node.

Returns
the unique ID of the current node

Definition at line 195 of file Node.cpp.

References mUid.

Referenced by uhal::tests::checkProperties(), getNode(), and operator==().

◆ getLineage()

std::vector< const Node * > uhal::Node::getLineage ( const Node aAncestor) const

Returns ancestry path of nodes from (but not including) aAncestor to this node.

Definition at line 681 of file Node.cpp.

References getPath(), and mParent.

Referenced by uhal::tests::checkLineage(), uhal::tests::checkNodeTree(), and uhal::detail::getAddressDescription().

◆ getMask()

const uint32_t & uhal::Node::getMask ( ) const

Return the mask to be applied if this node is a sub-field, rather than an entire register.

Returns
the mask to be applied if this node is a sub-field, rather than an entire register

Definition at line 266 of file Node.cpp.

References mMask.

Referenced by uhal::tests::checkProperties(), uhal::detail::getAddressOverlaps(), operator==(), and uhal::detail::printNodeOverlapDescription().

◆ getMode()

const defs::BlockReadWriteMode & uhal::Node::getMode ( ) const

Return whether the node represents a single register, a block of registers or a block-read/write port.

Returns
whether the node represents a single register, a block of registers or a block-read/write port

Definition at line 272 of file Node.cpp.

References mMode.

Referenced by uhal::tests::checkProperties(), uhal::detail::getAddressOverlaps(), and uhal::detail::printNodeOverlapDescription().

◆ getModule()

const std::string & uhal::Node::getModule ( ) const

Return the name of the module in which the current node resides.

Returns
the name of the module in which the current node resides

Definition at line 302 of file Node.cpp.

References mModule.

Referenced by uhal::tests::checkProperties().

◆ getNode() [1/2]

const Node & uhal::Node::getNode ( const std::string &  aId) const

Retrieve the Node given by a full-stop delimeted name path relative, to the current node.

Parameters
aIda full-stop delimeted name path to a node, relative to the current node
Returns
the Node given by the identifier

Definition at line 415 of file Node.cpp.

References getPath(), getRelativePath(), uhal::log(), mChildrenMap, and uhal::Quote().

Referenced by uhal::tests::checkDescendants(), uhal::tests::checkIteration(), uhal::tests::checkLineage(), uhal::tests::checkNodeTree(), and getNode().

◆ getNode() [2/2]

template<typename T >
const T & uhal::Node::getNode ( const std::string &  aId) const

Retrieve the Node given by a full-stop delimeted name path relative, to the current node and cast it to a particular node type.

Parameters
aIda full-stop delimeted name path to a node, relative to the current node
Returns
the Node given by the identifier

Definition at line 46 of file Node.hxx.

References getId(), getNode(), uhal::log(), uhal::Quote(), and uhal::Type().

◆ getNodes() [1/2]

std::vector< std::string > uhal::Node::getNodes ( ) const

Return all node IDs known to this HwInterface.

Returns
all node IDs known to this HwInterface

Definition at line 452 of file Node.cpp.

References begin(), and end().

Referenced by uhal::tests::checkDescendants().

◆ getNodes() [2/2]

std::vector< std::string > uhal::Node::getNodes ( const std::string &  aRegex) const

Return all node IDs known to this connection manager which match a (boost) regular expression.

Parameters
aRegexa string expression which is converted to a (boost) regular expression against which the node IDs are tested
Returns
all node IDs known to this connection manager

Definition at line 466 of file Node.cpp.

References begin(), end(), uhal::Info, uhal::log(), and sort().

◆ getParameters()

const boost::unordered_map< std::string, std::string > & uhal::Node::getParameters ( ) const

Return parameters of the current node.

Returns
parameters of the current node

Definition at line 308 of file Node.cpp.

References mParameters.

Referenced by uhal::tests::checkProperties(), and uhal::tests::DummyParentNode::printParameters().

◆ getPath()

std::string uhal::Node::getPath ( ) const

Return the full path to the current node.

Returns
the full path to the current node

Definition at line 201 of file Node.cpp.

References getAncestors().

Referenced by uhal::tests::checkLineage(), uhal::tests::checkProperties(), uhal::detail::getAddressDescription(), getLineage(), getNode(), uhal::detail::printNodeOverlapDescription(), read(), and write().

◆ getPermission()

const defs::NodePermission & uhal::Node::getPermission ( ) const

Return the read/write access permissions of this node.

Returns
the read/write access permissions of this node

Definition at line 284 of file Node.cpp.

References mPermission.

Referenced by uhal::tests::checkProperties(), and operator==().

◆ getRelativePath()

std::string uhal::Node::getRelativePath ( const Node aAncestor) const
private

Definition at line 225 of file Node.cpp.

References getAncestors().

Referenced by getNode().

◆ getSize()

const uint32_t & uhal::Node::getSize ( ) const

Return the maximum size available to a block read/write.

Returns
the maximum size available to a block read/write

Definition at line 278 of file Node.cpp.

References mSize.

Referenced by uhal::tests::checkExceptionsThrownByReadWrite(), uhal::tests::checkProperties(), uhal::detail::getAddressOverlaps(), and uhal::detail::printNodeOverlapDescription().

◆ getTags()

const std::string & uhal::Node::getTags ( ) const

Return the optional tags string which the user can specify for the current node.

Returns
the optional tags string which the user can specify for the current node

Definition at line 290 of file Node.cpp.

References mTags.

Referenced by uhal::tests::checkProperties().

◆ isChildOf()

bool uhal::Node::isChildOf ( const Node aParent) const

Returns whether this node is child of the function's argument.

Definition at line 698 of file Node.cpp.

References mParent.

Referenced by uhal::detail::getAddressOverlaps().

◆ operator=()

Node & uhal::Node::operator= ( const Node aNode)
protectedvirtual

Assignment operator.

Parameters
aNodea Node to copy
Returns
reference to this object for chained assignment

Definition at line 106 of file Node.cpp.

References mAddr, mChildren, mChildrenMap, mClassName, mDescription, mHw, mMask, mMode, mModule, mParameters, mPartialAddr, mPermission, mSize, mTags, and mUid.

◆ operator==()

bool uhal::Node::operator== ( const Node aNode) const

A function to determine whether two Nodes are identical.

Parameters
aNodea Node to compare
Returns
whether two Nodes are identical

Definition at line 186 of file Node.cpp.

References getAddress(), getId(), getMask(), and getPermission().

◆ read()

ValWord< uint32_t > uhal::Node::read ( ) const

Read a single, unmasked, unsigned word.

Returns
a Validated Memory which wraps the location to which the reply data is to be written

Definition at line 585 of file Node.cpp.

References uhal::HwInterface::getClient(), getPath(), uhal::log(), mAddr, mHw, mMask, mPermission, uhal::defs::NOMASK, uhal::Quote(), uhal::defs::READ, and uhal::ClientInterface::read().

Referenced by uhal::tests::checkExceptionsThrownByReadWrite(), uhal::tests::job_multiple(), and uhal::tests::UHAL_TESTS_DEFINE_CLIENT_TEST_CASES().

◆ readBlock()

ValVector< uint32_t > uhal::Node::readBlock ( const uint32_t &  aSize) const

Read a block of unsigned data from a block of registers or a block-read port.

Parameters
aSizethe number of words to read
Returns
a Validated Memory which wraps the location to which the reply data is to be written

Definition at line 606 of file Node.cpp.

References uhal::log(), uhal::Quote(), uhal::defs::READ, and uhal::defs::SINGLE.

Referenced by uhal::tests::checkExceptionsThrownByReadWrite(), uhal::tests::for(), uhal::tests::job_multiple(), and uhal::tests::UHAL_TESTS_DEFINE_CLIENT_TEST_CASES().

◆ readBlockOffset()

ValVector< uint32_t > uhal::Node::readBlockOffset ( const uint32_t &  aSize,
const uint32_t &  aOffset 
) const

Read a block of unsigned data from a block of registers or a block-read port.

Parameters
aSizethe number of words to read
aOffsetan offset into the block at which to start the block-read
Returns
a Validated Memory which wraps the location to which the reply data is to be written

Definition at line 637 of file Node.cpp.

References uhal::log(), uhal::defs::NON_INCREMENTAL, uhal::Quote(), uhal::defs::READ, and uhal::defs::SINGLE.

Referenced by uhal::tests::checkExceptionsThrownByReadWrite(), and uhal::tests::UHAL_TESTS_DEFINE_CLIENT_TEST_CASES().

◆ stream()

void uhal::Node::stream ( std::ostream &  aStr,
std::size_t  aIndent = 0 
) const

A streaming helper function to create pretty, indented tree diagrams.

Parameters
aStra stream to write to
aIndentsize of the indentation

Definition at line 320 of file Node.cpp.

References uhal::dec, uhal::hex, uhal::defs::HIERARCHICAL, uhal::defs::INCREMENTAL, mAddr, mChildren, mClassName, mDescription, mMask, mMode, mModule, mParameters, mPermission, mSize, mTags, mUid, uhal::defs::NON_INCREMENTAL, uhal::defs::READ, uhal::defs::SINGLE, and uhal::defs::WRITE.

Referenced by uhal::operator<<().

◆ write()

ValHeader uhal::Node::write ( const uint32_t &  aValue) const

Write a single, unmasked word to a register.

Parameters
aValuethe value to write to the register
Returns
a Validated Header which will contain the returned IPbus header

Definition at line 490 of file Node.cpp.

References uhal::HwInterface::getClient(), getPath(), uhal::log(), mAddr, mHw, mMask, mPermission, uhal::defs::NOMASK, uhal::Quote(), uhal::defs::READ, uhal::defs::WRITE, and uhal::ClientInterface::write().

Referenced by uhal::tests::checkExceptionsThrownByReadWrite(), uhal::tests::job_multiple(), and uhal::tests::UHAL_TESTS_DEFINE_CLIENT_TEST_CASES().

◆ writeBlock()

ValHeader uhal::Node::writeBlock ( const std::vector< uint32_t > &  aValues) const

Write a block of data to a block of registers or a block-write port.

Parameters
aValuesthe values to write to the registers or a block-write port
Returns
a Validated Header which will contain the returned IPbus header

Definition at line 516 of file Node.cpp.

References uhal::log(), uhal::Quote(), uhal::defs::SINGLE, and uhal::defs::WRITE.

Referenced by uhal::tests::checkExceptionsThrownByReadWrite(), uhal::tests::for(), uhal::tests::job_multiple(), and uhal::tests::UHAL_TESTS_DEFINE_CLIENT_TEST_CASES().

◆ writeBlockOffset()

ValHeader uhal::Node::writeBlockOffset ( const std::vector< uint32_t > &  aValues,
const uint32_t &  aOffset 
) const

Write a block of data to a block of registers or a block-write port.

Parameters
aValuesthe values to write to the registers or a block-write port
aOffsetan offset into the block at which to start the block-write
Returns
a Validated Header which will contain the returned IPbus header

Definition at line 547 of file Node.cpp.

References uhal::log(), uhal::defs::NON_INCREMENTAL, uhal::Quote(), uhal::defs::SINGLE, and uhal::defs::WRITE.

Referenced by uhal::tests::checkExceptionsThrownByReadWrite(), and uhal::tests::UHAL_TESTS_DEFINE_CLIENT_TEST_CASES().

Friends And Related Function Documentation

◆ const_iterator

friend class const_iterator
friend

Definition at line 122 of file Node.hpp.

Referenced by begin(), and end().

◆ DerivedNodeFactory

friend class DerivedNodeFactory
friend

Definition at line 90 of file Node.hpp.

◆ HwInterface

friend class HwInterface
friend

Definition at line 88 of file Node.hpp.

◆ NodeTreeBuilder

friend class NodeTreeBuilder
friend

Definition at line 89 of file Node.hpp.

Member Data Documentation

◆ mAddr

uint32_t uhal::Node::mAddr
private

The register address with which this node is associated.

Definition at line 342 of file Node.hpp.

Referenced by uhal::NodeTreeBuilder::calculateHierarchicalAddresses(), getAddress(), operator=(), read(), stream(), and write().

◆ mChildren

std::vector< Node* > uhal::Node::mChildren
private

◆ mChildrenMap

boost::unordered_map< std::string , Node* > uhal::Node::mChildrenMap
private

Helper to assist look-up of a particular child node, given a name.

Definition at line 378 of file Node.hpp.

Referenced by uhal::NodeTreeBuilder::addChildren(), getNode(), Node(), operator=(), and ~Node().

◆ mClassName

std::string uhal::Node::mClassName
private

◆ mDescription

std::string uhal::Node::mDescription
private

Optional string which the user can specify.

Definition at line 357 of file Node.hpp.

Referenced by getDescription(), operator=(), uhal::NodeTreeBuilder::setDescription(), and stream().

◆ mFirmwareInfo

boost::unordered_map< std::string, std::string > uhal::Node::mFirmwareInfo
private

parameters to infer the VHDL address decoding

Definition at line 369 of file Node.hpp.

Referenced by getFirmwareInfo(), and uhal::NodeTreeBuilder::setFirmwareInfo().

◆ mHw

HwInterface* uhal::Node::mHw
private

The parent hardware interface of which this node is a child (or rather decendent)

Definition at line 334 of file Node.hpp.

Referenced by uhal::HwInterface::claimNode(), getClient(), operator=(), read(), and write().

◆ mMask

uint32_t uhal::Node::mMask
private

The mask to be applied if this node is a sub-field, rather than an entire register.

Definition at line 345 of file Node.hpp.

Referenced by getMask(), operator=(), read(), uhal::NodeTreeBuilder::setMask(), stream(), and write().

◆ mMode

defs::BlockReadWriteMode uhal::Node::mMode
private

Whether the node represents a single register, a block of registers or a block-read/write port.

Definition at line 349 of file Node.hpp.

Referenced by uhal::NodeTreeBuilder::addChildren(), uhal::NodeTreeBuilder::calculateHierarchicalAddresses(), getMode(), operator=(), uhal::NodeTreeBuilder::setModeAndSize(), and stream().

◆ mModule

std::string uhal::Node::mModule
private

The name of the module in which the current node resides.

Definition at line 360 of file Node.hpp.

Referenced by getModule(), operator=(), uhal::NodeTreeBuilder::setModule(), and stream().

◆ mParameters

boost::unordered_map< std::string, std::string > uhal::Node::mParameters
private

Additional parameters of the node.

Definition at line 366 of file Node.hpp.

Referenced by getParameters(), operator=(), uhal::NodeTreeBuilder::setPars(), and stream().

◆ mParent

Node* uhal::Node::mParent
private

The parent of the current node.

Definition at line 372 of file Node.hpp.

Referenced by getAncestors(), getLineage(), and isChildOf().

◆ mPartialAddr

uint32_t uhal::Node::mPartialAddr
private

The register address with which this node is associated.

Definition at line 340 of file Node.hpp.

Referenced by uhal::NodeTreeBuilder::calculateHierarchicalAddresses(), operator=(), and uhal::NodeTreeBuilder::setAddr().

◆ mPermission

defs::NodePermission uhal::Node::mPermission
private

The read/write access permissions of this node.

Definition at line 347 of file Node.hpp.

Referenced by getPermission(), operator=(), read(), uhal::NodeTreeBuilder::setPermissions(), stream(), and write().

◆ mSize

uint32_t uhal::Node::mSize
private

The maximum size available to a block read/write.

Definition at line 351 of file Node.hpp.

Referenced by uhal::NodeTreeBuilder::calculateHierarchicalAddresses(), getSize(), operator=(), uhal::NodeTreeBuilder::setModeAndSize(), and stream().

◆ mTags

std::string uhal::Node::mTags
private

Optional string which the user can specify.

Definition at line 354 of file Node.hpp.

Referenced by getTags(), operator=(), uhal::NodeTreeBuilder::setTags(), and stream().

◆ mUid

std::string uhal::Node::mUid
private

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