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/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 IPbusCore;

  namespace exception
  {
    // //! Exception class to handle the case where an Atomic Transaction was requested but could not be performed. Uses the base uhal::exception implementation of what()
    // class AtomicTransactionSize : public 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();

      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;

      friend class IPbusCore;

    protected:

      URI mUri;

      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