ClientInterface.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_ClientInterface_hpp_
#define _uhal_ClientInterface_hpp_
 
 
#include <deque>
#include <stdint.h>
#include <string>
#include <utility>
#include <vector>
 
#include <boost/date_time/posix_time/posix_time_types.hpp>
#include <boost/shared_ptr.hpp>
#include <boost/weak_ptr.hpp>
#include <boost/thread/mutex.hpp>
 
#include "uhal/grammars/URI.hpp"
#include "uhal/log/exception.hpp"
#include "uhal/definitions.hpp"
#include "uhal/ValMem.hpp"
 
 
namespace uhal
{
  // Forward declaration
  class Buffers;
  class ClientInterface;
  class HwInterface;
  class IPbusCore;
  class Node;
 
  namespace detail
  {
    std::string getAddressDescription(const ClientInterface&, const uint32_t, const size_t&);
  }
 
  namespace exception
  {
    UHAL_DEFINE_EXCEPTION_CLASS ( PingFailed , "Exception class to handle the case where pinging of a client failed." )
 
    
    UHAL_DEFINE_EXCEPTION_CLASS ( BitsSetWhichAreForbiddenByBitMask , "Exception class to handle the case where a masked write was attempted with a data source which has non-zero bits outside the bit-mask's bounds." )
 
    UHAL_DEFINE_EXCEPTION_CLASS ( ValidationError , "Exception class to handle the case where we were unable to validate the packet." )
 
    UHAL_DEFINE_EXCEPTION_CLASS ( NullBufferException , "Exception class to handle a NULL buffer being passed to the transport class." )
 
    UHAL_DEFINE_EXCEPTION_CLASS ( PacketLevelError, "Base exception class covering situations in which a packet-level error occurs.")
 
    UHAL_DEFINE_EXCEPTION_CLASS ( TransactionLevelError, "Base exception class covering situations in which a transaction-level error occurs (i.e. error occurs in individual read/write).")
 
    UHAL_DEFINE_EXCEPTION_CLASS ( ClientTimeout, "Base exception class covering timeouts when waiting for reply from device")
 
    UHAL_DEFINE_EXCEPTION_CLASS ( TransportLayerError, "Base exception class covering non-timeout transport-layer-specific errors.")
  }
 
  class ClientInterface
  {
    protected:
      ClientInterface ( const std::string& aId, const URI& aUri , const boost::posix_time::time_duration& aTimeoutPeriod );
 
    private:
      ClientInterface ();
 
      ClientInterface ( const ClientInterface& aClientInterface );
 
      virtual ClientInterface& operator= ( const ClientInterface& aClientInterface );
 
    public:
      virtual ~ClientInterface();
 
      const std::string& id() const;
 
      // /**
      // Ping the target for this client
      // */
      // void ping();
 
      const std::string& uri() const;
 
      void dispatch ();
 
      void setTimeoutPeriod ( const uint32_t& aTimeoutPeriod  = 0 );
 
      uint64_t getTimeoutPeriod();
 
    protected:
      const boost::posix_time::time_duration& getBoostTimeoutPeriod();
 
    public:
 
      ValHeader write ( const uint32_t& aAddr, const uint32_t& aValue );
 
      ValHeader write ( const uint32_t& aAddr, const uint32_t& aValue, const uint32_t& aMask );
 
      ValHeader writeBlock ( const uint32_t& aAddr, const std::vector< uint32_t >& aValues, const defs::BlockReadWriteMode& aMode=defs::INCREMENTAL );
 
      ValWord< uint32_t > read ( const uint32_t& aAddr );
 
      ValWord< uint32_t > read ( const uint32_t& aAddr, const uint32_t& aMask );
 
      ValVector< uint32_t > readBlock ( const uint32_t& aAddr, const uint32_t& aSize, const defs::BlockReadWriteMode& aMode=defs::INCREMENTAL );
 
      ValWord< uint32_t > rmw_bits ( const uint32_t& aAddr , const uint32_t& aANDterm , const uint32_t& aORterm );
 
      ValWord< uint32_t > rmw_sum ( const uint32_t& aAddr , const int32_t& aAddend );
 
    protected:
      virtual void implementDispatch ( boost::shared_ptr< Buffers > aBuffers ) = 0;
 
      virtual void Flush( );
 
 
      virtual ValHeader implementBOT( ) = 0;
 
      virtual ValHeader implementWrite ( const uint32_t& aAddr, const uint32_t& aValue ) = 0;
 
      virtual ValHeader implementWriteBlock ( const uint32_t& aAddr, const std::vector< uint32_t >& aValues, const defs::BlockReadWriteMode& aMode=defs::INCREMENTAL ) = 0;
 
      virtual ValWord< uint32_t > implementRead ( const uint32_t& aAddr, const uint32_t& aMask = defs::NOMASK ) = 0;
 
      virtual ValVector< uint32_t > implementReadBlock ( const uint32_t& aAddr, const uint32_t& aSize, const defs::BlockReadWriteMode& aMode=defs::INCREMENTAL ) = 0;
 
 
      virtual ValWord< uint32_t > implementRMWbits ( const uint32_t& aAddr , const uint32_t& aANDterm , const uint32_t& aORterm ) = 0;
 
      virtual ValWord< uint32_t > implementRMWsum ( const uint32_t& aAddr , const int32_t& aAddend ) = 0;
 
      virtual void preamble ( boost::shared_ptr< Buffers > aBuffers );
 
      virtual uint32_t getPreambleSize();
 
      virtual void predispatch ( boost::shared_ptr< Buffers > aBuffers );
 
      std::pair < ValHeader , _ValHeader_* > CreateValHeader();
 
      std::pair < ValWord<uint32_t> , _ValWord_<uint32_t>* > CreateValWord ( const uint32_t& aValue , const uint32_t& aMask = defs::NOMASK );
      
      std::pair < ValVector<uint32_t> , _ValVector_<uint32_t>* > CreateValVector ( const uint32_t& aSize );
 
      virtual  exception::exception* validate ( boost::shared_ptr< Buffers > aBuffers );
 
 
    protected:
      virtual  exception::exception* validate ( uint8_t* aSendBufferStart ,
          uint8_t* aSendBufferEnd ,
          std::deque< std::pair< uint8_t* , uint32_t > >::iterator aReplyStartIt ,
          std::deque< std::pair< uint8_t* , uint32_t > >::iterator aReplyEndIt ) = 0;
 
      virtual void dispatchExceptionHandler();
 
      void returnBufferToPool ( boost::shared_ptr< Buffers >& aBuffers );
      void returnBufferToPool ( std::deque< boost::shared_ptr< Buffers > >& aBuffers );
      void returnBufferToPool ( std::vector< boost::shared_ptr< Buffers > >& aBuffers );
      void returnBufferToPool ( std::deque< std::vector< boost::shared_ptr< Buffers > > >& aBuffers );
 
    private:
      void updateCurrentBuffers();
      void deleteBuffers();
 
 
    private:
      boost::mutex mUserSideMutex;
      
      boost::mutex mBufferMutex;
 
      std::deque < boost::shared_ptr< Buffers > > mBuffers;
 
#ifdef NO_PREEMPTIVE_DISPATCH
      std::deque < boost::shared_ptr< Buffers > > mNoPreemptiveDispatchBuffers;
#endif
 
      boost::shared_ptr< Buffers > mCurrentBuffers;
 
      std::string mId;
 
      boost::posix_time::time_duration mTimeoutPeriod;
 
      boost::weak_ptr<Node> mNode;
 
      friend class IPbusCore;
      friend class HwInterface;
      friend std::string detail::getAddressDescription(const ClientInterface&, const uint32_t, const size_t&);
 
    protected:
 
      URI mUri;
 
      std::string mUriString;
 
      virtual boost::shared_ptr< Buffers > checkBufferSpace ( const uint32_t& aSendSize , const uint32_t& aReplySize , uint32_t& aAvailableSendSize , uint32_t& aAvailableReplySize );
 
      virtual uint32_t getMaxNumberOfBuffers() = 0;
      virtual uint32_t getMaxSendSize() = 0;
      virtual uint32_t getMaxReplySize() = 0;
  };
 
}
 
#endif