Node.hpp

Go to the documentation of this file.

/*
---------------------------------------------------------------------------
 
    This file is part of uHAL.
 
    uHAL is a hardware access library and programming framework
    originally developed for upgrades of the Level-1 trigger of the CMS
    experiment at CERN.
 
    uHAL is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
 
    uHAL is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
 
    You should have received a copy of the GNU General Public License
    along with uHAL.  If not, see <http://www.gnu.org/licenses/>.
 
 
      Andrew Rose, Imperial College, London
      email: awr01 <AT> imperial.ac.uk
 
      Marc Magrans de Abril, CERN
      email: marc.magrans.de.abril <AT> cern.ch
 
---------------------------------------------------------------------------
*/
 
#ifndef _uhal_Node_hpp_
#define _uhal_Node_hpp_
 
 
#include <iterator>
#include <stdexcept>
#include <string>
#include <unordered_map>
#include <vector>
 
#include "uhal/ClientInterface.hpp"
#include "uhal/definitions.hpp"
#include "uhal/log/exception.hpp"
#include "uhal/ValMem.hpp"
 
 
namespace uhal
{
  class HwInterface;
  class NodeTreeBuilder;
  class DerivedNodeFactory;
 
  namespace exception
  {
    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." )
    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." )
    UHAL_DEFINE_EXCEPTION_CLASS ( NoBranchFoundWithGivenUID , "Exception class to handle the case where a child ID was requested which does not exist." )
    UHAL_DEFINE_EXCEPTION_CLASS ( BulkTransferOnSingleRegister , "Exception class to handle the case where a bulk read or write was performed on a single register." )
    UHAL_DEFINE_EXCEPTION_CLASS ( BulkTransferRequestedTooLarge , "Exception class to handle the case where requested bulk read or write was too large." )
    UHAL_DEFINE_EXCEPTION_CLASS ( BulkTransferOffsetRequestedForFifo , "Exception class to handle the case where an offset was requested into a FIFO." )
    UHAL_DEFINE_EXCEPTION_CLASS ( BulkTransferOffsetRequestedForSingleRegister , "Exception class to handle the case where an offset was requested into a Single Register." )
    UHAL_DEFINE_EXCEPTION_CLASS ( BadNodeCast , "Exception class to handle the case of an attempt to cast a node to the wrong type." )
  }
 
 
  class Node
  {
    private:
      friend class HwInterface;
      friend class NodeTreeBuilder;
      friend class DerivedNodeFactory;
 
    public:
      class const_iterator : public std::iterator< std::forward_iterator_tag , Node , ptrdiff_t, const Node* , const Node& >
      {
          friend class Node;
          typedef std::deque< std::vector< Node* >::const_iterator > stack;
 
        public:
          const_iterator();
          virtual ~const_iterator();
 
          const_iterator ( const Node* aBegin );
          const_iterator ( const const_iterator& aOrig );
 
          const Node& value() const;
          const Node& operator*() const;
          const Node* operator->() const;
 
          bool next();
          const_iterator& operator++();
          const_iterator operator++ ( int );
 
          bool operator== ( const const_iterator& aIt ) const;
          bool operator!= ( const const_iterator& aIt ) const;
 
        private:
          const Node* mBegin;
          stack mItStack;
      };
 
    private:
      friend class const_iterator;
 
    protected:
      Node ( );
 
      Node ( const Node& aNode );
 
      virtual Node& operator= ( const Node& aNode );
 
      virtual Node* clone() const;
 
    public:
      virtual ~Node();
 
      const_iterator begin() const;
 
      const_iterator end() const;
 
      bool operator == ( const Node& aNode ) const;
 
      bool hasNode ( const std::string& aId ) const;
 
      const Node& getNode ( const std::string& aId ) const;
 
      template< typename T>
      const T& getNode ( const std::string& aId ) const;
 
      std::vector<std::string> getNodes() const;
 
      std::vector<std::string> getNodes ( const std::string& aRegex ) const;
 
      const std::string& getId() const;
 
      std::string getPath() const;
 
      const uint32_t& getAddress() const;
 
      const uint32_t& getMask() const;
 
      const defs::BlockReadWriteMode& getMode() const;
 
      const uint32_t& getSize() const;
 
      const defs::NodePermission& getPermission() const;
 
      const std::string& getTags() const;
 
      const std::string& getDescription() const;
 
      const std::string& getModule() const;
 
      const std::unordered_map< std::string, std::string >& getParameters() const;
 
      const std::unordered_map< std::string, std::string >& getFirmwareInfo() const;
 
      void stream ( std::ostream& aStr , std::size_t aIndent = 0 ) const;
 
      ValHeader write ( const uint32_t& aValue ) const;
 
      ValHeader writeBlock ( const std::vector< uint32_t >& aValues ) const;
 
      ValHeader writeBlockOffset ( const std::vector< uint32_t >& aValues , const uint32_t& aOffset ) const;
 
      ValWord< uint32_t > read ( ) const;
 
      ValVector< uint32_t > readBlock ( const uint32_t& aSize ) const;
 
      ValVector< uint32_t > readBlockOffset ( const uint32_t& aSize , const uint32_t& aOffset ) const;
 
      ClientInterface& getClient() const;
 
      std::vector<const Node*> getLineage(const Node& aAncestor) const;
 
      bool isChildOf(const Node& aParent) const;
 
    private:
 
      std::string getRelativePath(const Node& aAncestor) const;
 
      void getAncestors ( std::deque< const Node* >& aPath ) const;
 
    private:
 
      HwInterface* mHw;
 
      std::string mUid;
 
      uint32_t mPartialAddr;
      uint32_t mAddr;
 
      uint32_t mMask;
      defs::NodePermission mPermission;
      defs::BlockReadWriteMode mMode;
      uint32_t mSize;
 
      std::string mTags;
 
      std::string mDescription;
 
      std::string mModule;
 
      std::string mClassName;
 
      std::unordered_map< std::string, std::string > mParameters;
 
      std::unordered_map< std::string, std::string > mFirmwareInfo;
 
      Node* mParent;
 
      std::vector< Node* > mChildren;
 
      std::unordered_map< std::string , Node* > mChildrenMap;
  };
 
  std::ostream& operator<< ( std::ostream& aStr ,  const uhal::Node& aNode );
}
 
 
#include "uhal/TemplateDefinitions/Node.hxx"
 
#endif