μHAL (v2.7.9)
Part of the IPbus software repository
Node.hpp
Go to the documentation of this file.
1 /*
2 ---------------------------------------------------------------------------
3 
4  This file is part of uHAL.
5 
6  uHAL is a hardware access library and programming framework
7  originally developed for upgrades of the Level-1 trigger of the CMS
8  experiment at CERN.
9 
10  uHAL is free software: you can redistribute it and/or modify
11  it under the terms of the GNU General Public License as published by
12  the Free Software Foundation, either version 3 of the License, or
13  (at your option) any later version.
14 
15  uHAL is distributed in the hope that it will be useful,
16  but WITHOUT ANY WARRANTY; without even the implied warranty of
17  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  GNU General Public License for more details.
19 
20  You should have received a copy of the GNU General Public License
21  along with uHAL. If not, see <http://www.gnu.org/licenses/>.
22 
23 
24  Andrew Rose, Imperial College, London
25  email: awr01 <AT> imperial.ac.uk
26 
27  Marc Magrans de Abril, CERN
28  email: marc.magrans.de.abril <AT> cern.ch
29 
30 ---------------------------------------------------------------------------
31 */
32 
40 #ifndef _uhal_Node_hpp_
41 #define _uhal_Node_hpp_
42 
43 
44 #include <iterator>
45 #include <stdexcept>
46 #include <string>
47 #include <vector>
48 
49 #include "boost/unordered_map.hpp"
50 
51 #include "uhal/ClientInterface.hpp"
52 #include "uhal/definitions.hpp"
53 #include "uhal/log/exception.hpp"
54 #include "uhal/ValMem.hpp"
55 
56 
57 namespace uhal
58 {
59  class HwInterface;
60  class NodeTreeBuilder;
61  class DerivedNodeFactory;
62 
63  namespace exception
64  {
66  UHAL_DEFINE_EXCEPTION_CLASS ( WriteAccessDenied , "Exception class to handle the case where a write was performed on a register which does not allow write access." )
68  UHAL_DEFINE_EXCEPTION_CLASS ( ReadAccessDenied , "Exception class to handle the case where a read was performed on a register which does not allow read access." )
70  UHAL_DEFINE_EXCEPTION_CLASS ( NoBranchFoundWithGivenUID , "Exception class to handle the case where a child ID was requested which does not exist." )
72  UHAL_DEFINE_EXCEPTION_CLASS ( BulkTransferOnSingleRegister , "Exception class to handle the case where a bulk read or write was performed on a single register." )
74  UHAL_DEFINE_EXCEPTION_CLASS ( BulkTransferRequestedTooLarge , "Exception class to handle the case where requested bulk read or write was too large." )
76  UHAL_DEFINE_EXCEPTION_CLASS ( BulkTransferOffsetRequestedForFifo , "Exception class to handle the case where an offset was requested into a FIFO." )
78  UHAL_DEFINE_EXCEPTION_CLASS ( BulkTransferOffsetRequestedForSingleRegister , "Exception class to handle the case where an offset was requested into a Single Register." )
80  UHAL_DEFINE_EXCEPTION_CLASS ( BadNodeCast , "Exception class to handle the case of an attempt to cast a node to the wrong type." )
81  }
82 
83 
85  class Node
86  {
87  private:
88  friend class HwInterface;
89  friend class NodeTreeBuilder;
90  friend class DerivedNodeFactory;
91 
92  public:
93  class const_iterator : public std::iterator< std::forward_iterator_tag , Node , ptrdiff_t, const Node* , const Node& >
94  {
95  friend class Node;
96  typedef std::deque< std::vector< Node* >::const_iterator > stack;
97 
98  public:
100  virtual ~const_iterator();
101 
102  const_iterator ( const Node* aBegin );
103  const_iterator ( const const_iterator& aOrig );
104 
105  const Node& value() const;
106  const Node& operator*() const;
107  const Node* operator->() const;
108 
109  bool next();
110  const_iterator& operator++();
111  const_iterator operator++ ( int );
112 
113  bool operator== ( const const_iterator& aIt ) const;
114  bool operator!= ( const const_iterator& aIt ) const;
115 
116  private:
117  const Node* mBegin;
119  };
120 
121  private:
122  friend class const_iterator;
123 
124  protected:
126  Node ( );
127 
132  Node ( const Node& aNode );
133 
139  virtual Node& operator= ( const Node& aNode );
140 
145  virtual Node* clone() const;
146 
147  public:
149  virtual ~Node();
150 
151  const_iterator begin() const;
152 
153  const_iterator end() const;
154 
160  bool operator == ( const Node& aNode ) const;
161 
167  const Node& getNode ( const std::string& aId ) const;
168 
174  template< typename T>
175  const T& getNode ( const std::string& aId ) const;
176 
181  std::vector<std::string> getNodes() const;
182 
188  std::vector<std::string> getNodes ( const std::string& aRegex ) const;
189 
194  const std::string& getId() const;
195 
200  std::string getPath() const;
201 
206  const uint32_t& getAddress() const;
207 
212  const uint32_t& getMask() const;
213 
218  const defs::BlockReadWriteMode& getMode() const;
219 
224  const uint32_t& getSize() const;
225 
230  const defs::NodePermission& getPermission() const;
231 
236  const std::string& getTags() const;
237 
242  const std::string& getDescription() const;
243 
248  const std::string& getModule() const;
249 
254  const boost::unordered_map< std::string, std::string >& getParameters() const;
255 
260  const boost::unordered_map< std::string, std::string >& getFirmwareInfo() const;
261 
267  void stream ( std::ostream& aStr , std::size_t aIndent = 0 ) const;
268 
274  ValHeader write ( const uint32_t& aValue ) const;
275 
281  ValHeader writeBlock ( const std::vector< uint32_t >& aValues ) const;
282 
289  ValHeader writeBlockOffset ( const std::vector< uint32_t >& aValues , const uint32_t& aOffset ) const;
290 
295  ValWord< uint32_t > read ( ) const;
296 
302  ValVector< uint32_t > readBlock ( const uint32_t& aSize ) const;
303 
310  ValVector< uint32_t > readBlockOffset ( const uint32_t& aSize , const uint32_t& aOffset ) const;
311 
316  ClientInterface& getClient() const;
317 
319  std::vector<const Node*> getLineage(const Node& aAncestor) const;
320 
322  bool isChildOf(const Node& aParent) const;
323 
324  private:
325 
326  std::string getRelativePath(const Node& aAncestor) const;
327 
329  void getAncestors ( std::deque< const Node* >& aPath ) const;
330 
331  private:
332 
335 
337  std::string mUid;
338 
340  uint32_t mPartialAddr;
342  uint32_t mAddr;
343 
345  uint32_t mMask;
351  uint32_t mSize;
352 
354  std::string mTags;
355 
357  std::string mDescription;
358 
360  std::string mModule;
361 
363  std::string mClassName;
364 
366  boost::unordered_map< std::string, std::string > mParameters;
367 
369  boost::unordered_map< std::string, std::string > mFirmwareInfo;
370 
373 
375  std::vector< Node* > mChildren;
376 
378  boost::unordered_map< std::string , Node* > mChildrenMap;
379  };
380 
381  std::ostream& operator<< ( std::ostream& aStr , const uhal::Node& aNode );
382 }
383 
384 
386 
387 #endif
uhal::HwInterface
A class which bundles a node tree and an IPbus client interface together providing everything you nee...
Definition: HwInterface.hpp:61
uhal::ValVector< uint32_t >
uhal::Node::mTags
std::string mTags
Optional string which the user can specify.
Definition: Node.hpp:354
uhal::operator<<
std::ostream & operator<<(std::ostream &aStr, const uhal::HttpResponseType &aHttpResponse)
Definition: HttpResponseGrammar.cpp:41
UHAL_DEFINE_EXCEPTION_CLASS
#define UHAL_DEFINE_EXCEPTION_CLASS(ClassName, ClassDescription)
Definition: exception.hpp:59
uhal::Node::const_iterator::stack
std::deque< std::vector< Node * >::const_iterator > stack
Definition: Node.hpp:96
uhal::Node::mModule
std::string mModule
The name of the module in which the current node resides.
Definition: Node.hpp:360
definitions.hpp
uhal::defs::NodePermission
NodePermission
define Read and Write permissions of a uhal Node
Definition: definitions.hpp:50
uhal::Node::mAddr
uint32_t mAddr
The register address with which this node is associated.
Definition: Node.hpp:342
uhal::Node::mFirmwareInfo
boost::unordered_map< std::string, std::string > mFirmwareInfo
parameters to infer the VHDL address decoding
Definition: Node.hpp:369
uhal::tests::writeBlock
c writeBlock(addr, xx)
uhal::Node::mHw
HwInterface * mHw
The parent hardware interface of which this node is a child (or rather decendent)
Definition: Node.hpp:334
uhal::ClientInterface
An abstract base class for defining the interface to the various IPbus clients as well as providing t...
Definition: ClientInterface.hpp:100
uhal::Node::mUid
std::string mUid
The Unique ID of this node.
Definition: Node.hpp:337
uhal::Node::mDescription
std::string mDescription
Optional string which the user can specify.
Definition: Node.hpp:357
uhal::Node::mParent
Node * mParent
The parent of the current node.
Definition: Node.hpp:372
Node.hxx
uhal::DerivedNodeFactory
A singleton class to register derived nodes, and create instances of them later NOTE!...
Definition: DerivedNodeFactory.hpp:69
uhal::Node::mPartialAddr
uint32_t mPartialAddr
The register address with which this node is associated.
Definition: Node.hpp:340
uhal::ValHeader
A class which wraps a single word of data and marks whether or not it is valid.
Definition: ValMem.hpp:148
uhal::Node::mChildren
std::vector< Node * > mChildren
The direct children of the node.
Definition: Node.hpp:375
uhal::NodeTreeBuilder
A class to build a node tree from an Address table file NOTE! This is a factory method and must be Mu...
Definition: NodeTreeBuilder.hpp:88
uhal
Definition: HttpResponseGrammar.hpp:49
uhal::Node::mMode
defs::BlockReadWriteMode mMode
Whether the node represents a single register, a block of registers or a block-read/write port.
Definition: Node.hpp:349
uhal::Node
A heirarchical node for navigating heirarchical firmwares.
Definition: Node.hpp:86
uhal::defs::BlockReadWriteMode
BlockReadWriteMode
define whether transactions target a single register, a block of registers, a block-read/write port o...
Definition: definitions.hpp:53
uhal::Node::mClassName
std::string mClassName
Class name used to construct the derived node type.
Definition: Node.hpp:363
uhal::tests::getNode
hw getNode("REG").write(x)
uhal::Node::mSize
uint32_t mSize
The maximum size available to a block read/write.
Definition: Node.hpp:351
uhal::Node::mPermission
defs::NodePermission mPermission
The read/write access permissions of this node.
Definition: Node.hpp:347
uhal::Node::mChildrenMap
boost::unordered_map< std::string, Node * > mChildrenMap
Helper to assist look-up of a particular child node, given a name.
Definition: Node.hpp:378
uhal::Node::mMask
uint32_t mMask
The mask to be applied if this node is a sub-field, rather than an entire register.
Definition: Node.hpp:345
uhal::ValWord< uint32_t >
ValMem.hpp
uhal::Node::const_iterator::mItStack
stack mItStack
Definition: Node.hpp:118
uhal::Node::const_iterator
Definition: Node.hpp:94
uhal::Node::mParameters
boost::unordered_map< std::string, std::string > mParameters
Additional parameters of the node.
Definition: Node.hpp:366
uhal::tests::write
c write(addr, xx[0])
exception.hpp
ClientInterface.hpp
uhal::Node::const_iterator::mBegin
const Node * mBegin
Definition: Node.hpp:117