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 "uhal/log/exception.hpp"
#include "uhal/definitions.hpp"
#include "uhal/ValMem.hpp"
#include "uhal/ClientInterface.hpp"

#include "boost/unordered_map.hpp"

#include <vector>
#include <string>
#include <iterator>


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::deque< 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;


      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 boost::unordered_map< std::string, std::string >& getParameters() const;

      const boost::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;


    private:
      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;

      boost::unordered_map< std::string, std::string > mParameters;

      boost::unordered_map< std::string, std::string > mFirmwareInfo;

      Node* mParent;

      std::deque< Node* > mChildren;

      boost::unordered_map< std::string , Node* > mChildrenMap;
  };

  std::ostream& operator<< ( std::ostream& aStr ,  const uhal::Node& aNode );
}


#include "uhal/TemplateDefinitions/Node.hxx"

#endif