RawDAQData.h

Go to the documentation of this file.

#ifndef RAWDAQDATA_BASE_H
#define RAWDAQDATA_BASE_H
#include "DAQDataFormats/FunctionBind.h"  // Macros for function pointer bindings

#include <iostream>             /* Iostream for printing   */
#include <stdint.h>             // uint32_t, etc
#include <stdlib.h>             // exit
#include <vector>

/// Versioning is implemented
#define DAQDATAFORMATS_VERSIONING_IS_IMPLEMENTED

/// Define a macros to make accessing the raw buffer easier
/// All DAQDataFormats use this macro, so we'll just have one definition here
#ifndef RAWBUFF32
#define RAWBUFF32 ((uint32_t*)_Buffer)
#define RAWBUFF16 ((uint16_t*)_Buffer)
#endif

/// calling functionIsNotAllowed
#define GENERATE_FUNCTION_IS_NOT_ALLOWED functionIsNotAllowed(__FUNCTION__)


//--------------------
/// Debugging macros
//#define DEBUGGING

#ifdef DEBUGGING
#warning "Debugging is turned on. Please uncomment out DEBUGGING constant!"
#define EXECUTE_ON_DEBUG(x) x
#define PRINT_ON_DEBUG(x) do { std::cout<<x<<"\n"; } while (0)
#else
// Swallow semicolon
#define EXECUTE_ON_DEBUG(x) static_assert(true, "Null statement")
#define PRINT_ON_DEBUG(x) static_assert(true, "Null statement")
#endif

/// This is for hard debugging
#ifndef COUT
#define COUT(xx) std::cout<<__PRETTY_FUNCTION__<<xx; std::cout<<"\n";
#endif

//--------------------


namespace novadaq{
namespace datalogger{
    class DataBlockReader;
}}


/*! 
  The RawDAQData class is a virtual class definition that
  all the NOVA DAQ data format classes inherit from.
  
  All RawDAQData class decendants must impliment:
  
  A writeData method that writes the objects data in a 
  packed format to a memory location.

  A readData method that reads the objects data in a 
  packed format from a memory location.

  and

  A sizeofdata method that returns the native size of the
  packed data object in 32bit words

*/
namespace daqdataformats {

    typedef int32_t version_t;// can be negative. For example, -1 = undefined

    typedef enum {
        rds_error = -1,
        rds_incomplete,
        rds_complete,
    } readDataStatus;

    namespace rawdaqdataformat {
        static const version_t DAQDATAFORMAT_UNKNOWN_VERSION = -1;
    }// end of namespace rawnano

class RawDAQData {
 protected:
    RawDAQData (); //!< Default Constructor.
    RawDAQData (version_t);
    RawDAQData (version_t, sizeofdata_t);
    RawDAQData (version_t, bool use_setBufferSourceUnknownVersion);
    RawDAQData (version_t, bool use_setBufferSourceUnknownVersion, sizeofdata_t);
    RawDAQData (init_t);
    RawDAQData (version_t, init_t);
    RawDAQData (version_t, init_t, sizeofdata_t);
    RawDAQData (version_t, init_t, sizeofdata_t, setBufferSource_t);
    RawDAQData (version_t, init_t, sizeofdata_t, setBufferSource_t, print_t, readData_t);
    /// Deep copy
    RawDAQData (const RawDAQData&);
    
 public:
    virtual ~RawDAQData();

 public:

    /// Deep copy from the DAQDataFormat
    virtual void copy (const RawDAQData&);

    /// Shallow copy from the external buffer
    virtual void copy (const void* buffer); //! Shallow copy constructor

    // Data I/O Methods
    // Read method that read the raw formated data block from the target memory
    void*                  readData(const void* buffer);
    /// Read from the buffer if the size of data is known
    void*                  readData(const void* buffer, const uint32_t size_of_data) {return readDataGeneral(buffer, size_of_data);}
    /// From the File descriptor
    virtual readDataStatus readData(const int   fd);

    /// General write method that writes the raw formated data block to the target memory
    /// We are not going to overload it, so no need to declare virtual
    void*    writeData(const void* buffer) const; //!< Write Data to target memory location. Return is the address of the end of the write. NULL on error.
    ssize_t  writeData(const int   fd    ) const; //!< Write Data to target file descriptor. Return is the number of bytes written. -1 on error.

    //---------------------------------------------------------
    /// Calculate CRC of _Buffer (after skipping last skip_last_words words) using CRC32c algorythm with 0x8F6E37A0 polynomial.
    /// Usually use skip_last_words=1 as the _Buffer has an CRC in the end
    /// If on calculates with skip_last_words=0 (with CRC at the end), it should calculate to Zero (Property of Check Sum)
    uint32_t calculateCheckSum(const uint32_t skip_last_words) const;

    /// Get method for the pointer to the internal buffers
    /// We are not going to overload it, so no need to declare virtual
    void*  getBuffer() const { return _Buffer; }; /* This is evil.  You shouldn't expose the buffer point. However, we allow it. */

    /// We are not going to overload these funtions, so no need to declare them virtual
    bool         setBufferSource (const void*); //!< Set The Buffer pointer to a given location.
    bool         resetBufferSource();     //! reset _Buffer to point to InternalBuffer
    virtual bool clear();                 //!< Clear Internal Buffer
    bool         reset();                 //!< Reset

    /// Is buffer internal
    /// We are not going to overload it, so no need to declare virtual
    bool         isInternalBuffer() const { return (_Buffer == (void*)(&_InternalBuffer[0])); }

    /// Functions that need to be defined in each class
    /// Initialize DAQDataFormats class
    void     init() {};
    /// Method for printing the content of the Buffer
    void     print(std::ostream& os=std::cout) const;
    /// print into the string
    void     print(std::string&  output_string) const;
    /// Sizeof method for the current data block.  Returns the size of the data block in 32bit words.
    uint32_t sizeofdata() const;

    /// Add the CRC into the end of fBuffer. CRC of all but the last words of the _Buffer
    virtual bool addCheckSum();

 //------------- Internal methods for DAQDataFormats. Can't be used by users
 protected:

    /// General ReadData method when the sizeofdata is known
    void*  readDataGeneral(const void* buffer);

    /// Method which returns the version of the DataFormat given the pointer to the buffer
    /// It has to be implemented for all DataFormats.
    virtual version_t figureOutTheVersion(const void* buffer) const = 0;

    /// If the buffer should be internal, check it's pointers and reassign them
    bool         checkBufferInternalness();

    /// Function where we set all function pointers. At this point we don't know it
    /// It is to be derived in the final user readable class
    virtual bool setFunctionPointers() = 0;

    
    /// Set BufferSource of the input DataFormat and return pointer to the position right after the end of its buffer
    void*    setBufferSourceGeneral(RawDAQData&, const void*);
    bool     setBufferSourceUnknownVersion(const void*);

    /// Reserve space for the internal buffer to some predetermined size
    bool     reserveInternalBuffer(const uint32_t size_of_data);

    /// Add Zeros to internal buffer
    bool     addToInternalBuffer(const uint32_t size_of_data_to_add);


    /// Resize the internal buffer
    bool     resizeInternalBuffer(const uint32_t size_of_data);
  
    /// Conversions from bool to int and backwards
    /// We are not going to overload it, so no need to declare virtual
    uint32_t boolToUint32_t (const bool     number ) const {  return ((number) ? 1 : 0); }
    bool     uint32_tToBool (const uint32_t number ) const {  return ((number) ? true : false); }

    /// Print methods
    /// Generic print
    void     printGeneral(std::ostream&     os=std::cout) const;
    /// Displays the data _Buffer
    /// Customazible for debugging purpose
    void     printBuffer (std::ostream&     os                       = std::cout
                         ,const bool        print_offset             = true      /* Print offset from the address of the _Buffer */
                         ,const bool        print_ascii              = true      /* Print ASCII of the content of the Buffer */
                         ,const bool        print_buffer_address     = false     /* Print Buffer Address */
                         ,const bool        print_internal_buffer    = false     /* Print Internal Buffer Info */
                         ,const bool        print_size_of_data       = false     /* Print Size Of Data */
                         ,const std::string separation_between_lines = "\n"      /* Separation symbol between lines */
                         ,const uint32_t    cols                     = 4         /* Number of columns in a line */
                         ) const;
    /// Print word from Buffer
    void     printWord      (const uint32_t iword, const bool is_bynary_printing, std::ostream& os=std::cout) const; ///! Print the i-th word of _Buffer, is_bynary_printing: true = bynary, false = HEX
    void     printWordBinary(const uint32_t word, std::ostream& os=std::cout) const;
    void     printWordHex   (const uint32_t word, std::ostream& os=std::cout) const;
    void     printBinary    (const void* buffer0, const uint32_t size, std::ostream& os=std::cout) const;
    void     printHex       (const void* buffer0, const uint32_t size, std::ostream& os=std::cout) const;
    void     printUnknownVersion(std::ostream& out_stream=std::cout) const { out_stream<<"DAQDataFormat is of unknown version"<<std::endl;}

    /// Generic readData methods
    void*    readDataGeneral(const void* buffer, const uint32_t size_of_data_to_read);
    void*    readDataGeneral(const void* buffer, const uint32_t size_of_data_to_read, const uint32_t buffer_start_position);

    /// One can call this function from another function, which usage is not allowed (for a particular version).
    bool     functionIsNotAllowed(const std::string function="", const std::string message="") const;

    /// General routines for the default constructor of main class for fixed size data formats, 
    /// like RawNanoSliceHeader, Timing marker etc. (they can be different from version to version though)
    /// But the difference is that we want to clear out the internal buffer for them,
    /// whereas for floating data formats don't need to have that, since the data may be overwritten anyways
    void     defaultConstructorFixedSize();
    void     defaultConstructorFixedSize(init_t);

    /// General routines for the default constructor of main class for floating size data formats,
    /// like RawNanoSlice, RawEvent etc.
    /// We don't need to initialize internal buffer
    void     defaultConstructorFloatingSize();
    void     defaultConstructorFloatingSize(init_t);


    /// Read data from the unknown version
    void*    readDataUnknownVersion(const void* buffer);

    /// is current _version unknown?
    bool     isVersionUnknown()                        const { return isVersionUnknown(_version);}
    /// is input version unknown?
    bool     isVersionUnknown(const version_t version) const { return (version == rawdaqdataformat::DAQDATAFORMAT_UNKNOWN_VERSION);}

    /// Get uint64_t from low and hi word
    uint64_t getUint64_t(uint32_t low_word  , uint32_t hi_word) const;
    bool     getLoAndHi (uint64_t input_data, uint32_t& output_low_word, uint32_t& output_hi_word) const;
    
    /*
    uint64_t getUint64_t(const DELEGATE(RawDAQData, function_get_low_word, uint32_t),
                         const DELEGATE(RawDAQData, function_get_hi_word , uint32_t)
                        )const;
    */

    bool     setUint64_t(uint64_t value,
                         DELEGATE(RawDAQData, function_set_low_word, bool, uint32_t),
                         DELEGATE(RawDAQData, function_set_hi_word , bool, uint32_t)
                        );

    /// Generating exception message as the version of DAQDataFormat is greater than the maximum allowed
    std::string  generateExceptionForWrongVersion(version_t maximum_version) const;

    /// Need to perform these operations in Deep Copy constructor
    void lastOperationsInDeepCopy(const RawDAQData& copy_in);

    //------------- Private methods for RawDAQData. Can't be used by derived classes
 private:

    /// Default constructor methods with custom reset_buffer_source method
    /// so that one can use resetBufferSource or clear
    void     defaultConstructorGeneral(resetBufferSource_t);
    void     defaultConstructorGeneral(init_t, resetBufferSource_t);

 protected:

  /// All data formats need to have _Buffer and a Data structure. _Buffer will be common.
  void*                  _Buffer;//!< The internal Buffer for each data format
                                 //!< Generalized pointer to the buffer holding the packed data
                                 //!< This pointer is used in performing generalized read/write calls
                                 //!< and should be set during initialization

  /// The internal buffer to hold data.
  /// Not always needed. A data format may have an external buffer.
  std::vector <uint32_t> _InternalBuffer;

  /// Auxillary variable that holds whether the buffer should be external or internal
  bool                   _shouldBufferBeInternal;

  /// DataFormat Version. 
  version_t              _version;

  /// Some common function pointers used in each DAQDataFormats class
  Init_t            (_function_init);
  Sizeofdata_t      (_function_sizeofdata);
  Print_t           (_function_print);
  ReadData_t        (_function_readData);
  SetBufferSource_t (_function_setBufferSource);
  
  /// These variables are only for Debugging purposes
  EXECUTE_ON_DEBUG(std::string _dataFormatClassName);
  EXECUTE_ON_DEBUG(std::string _dataFormatConstructor);


  friend class novadaq::datalogger::DataBlockReader;

};// end of RawDAQData class

/// operator << so that one can put print it into an output stream directly
std::ostream& operator << (std::ostream& os, const daqdataformats::RawDAQData& dataformat);

/// Method to calculate a shifts from a given mask.
/// The method is private for DAQDataFormats. Used by calculateShiftsFromMasks().
/// This method should not be used by any DAQDataFormat
uint32_t calculateShiftFromAGivenMask (const uint32_t mask);

}// end of daqdataformats namespace
#endif /* RAWDAQDATA_BASE_H */