// // File : MiEvent.hh // // Purpose: Declaration of Mirror event classes // // // $Id: MiEvent.hh 12082 2011-02-21 17:11:29Z mathes $ // /** @file MiEvent.hh * Declaration of class TMirrorEvent * @author H.-J. Mathes, FzK */ #ifndef _MiEvent_hh_ #define _MiEvent_hh_ #ifndef NO_VERSION # include #endif // NO_VERSION // // Note: GNU C/C++ comes along with data types 'long long int', ... // which are currently not supported by CINT // Therefor we undef __GNUC__ which selects this type in the // system header files #ifdef __CINT__ # undef __GNUC__ #endif // __CINT__ #include #include #include #include /** @mainpage FD Mirror Event Data Format Library @section intro Introduction This document contains the description of the FD mirror event data format library which is used to describe all components of an FD mirror event at the level of the Mirror PC. To create this documentation again you need at least doxygen 1.4.0. @see http://www.stack.nl/~dimitri/doxygen/index.html The library is divided into several parts: @li The modules containing TMirror* like named data structures. @li The modules containing TShm* like data structures. The design of the TMirror* classes is very much guided by the needs of the online DAQ system, i.e. they include all the possibility to be mapped onto plain memory. Therefor, their use within interactive ROOT sessions isn't quite straightforward. @section usage Usage The package is used by including the appropiate header files. When dealing with TMirror* or TMirrorRun* data structures, @ref MiEvent "MiEvent.hh" or @ref MiRun "MiRun.hh" needs to be included. When working with the shared memory based data structures one has to include the @ref ShmEvent "ShmEvent.hh" or @ref ShmRun "ShmRun.hh" header files. @subsection dirs Directory Structure The described library resides in one subdirectory of MiEvent, namely the MiEvent/src directory. The directory MiEvent/test contains a few test programs necessary to check certain aspects of the library. @subsection install Installation In order to compile the library properly, the shared memory library (package Shm) and a buffer manager library (pacakge Nova) must be present and installed. As this package is either distributed with the FD-DAS or the FDEventLib package, the build variables listed below, should be set properly: @li FDINCDIR : FD-DAS main include directory @li FDLIBDIR : FD-DAS main library directory @li FDBINDIR : FD-DAS binary installation directory @li SHMINCDIR : the directory where to find the header files for the shared memory package @li SHMLIBDIR : directory with the shared memory library @li UTILINCDIR : the directory with the include files of the FdUtil package @li UTILLIBDIR : the directory containing the libraries of the FdUtil package After creation and installation of header files and libraries we end then up with: @li libMiEvent.a : the package containing all TMirror* structures together with its shared library counterpartlibMiEvent.so @li libMiShmEvent.a : the package containing all TShm* structures together with its shared library counterpart libMiShmEvent.so. In case this package is distributed as a part of the FDEventLib package, the SHM parts are neither required nor built. @section changes Changes The list of changes is now maintained in the file CHANGES: @verbinclude CHANGES A detailed list of list of changes from release v1r5 to v2r0 is especially setup in the file RELEASE-NOTES-v2r0: @verbinclude RELEASE-NOTES-v2r0 @todo The list of todo items is now kept in the file TODO. @verbinclude TODO */ // --- forward declarations class TMirrorEventHeader; class TMirrorPixelData; class TMirrorPixelList; class TMirrorFADCData; class TFADCData; class TMirrorBitArray; class TMirrorEventFile; class TMirrorTriggerData; class TShmEvent; #ifndef __CINT__ # include # include # include # include # include # include # include #endif // __CINT__ /** Class to describe the FD Mirror event. * * @anchor MiEvent * This class describes the event data format how it lives on a * MirrorPC and how it comes out of the Mirror DAQ program. * * The implementation of this class is done in a way that an easy mapping of * all data structures to shared memory is possible. We have here the special * requirements that a TMirrorEvent and all of its subcomponents * must also be able to reside in shared memory (SHM) and to be remapped to * other process' address spaces without any problems coming from the * virtual tables of the class. * * Therefor we have several constructors for different situations, * which take this into account. * * The present subcomponents of a TMirrorEvent are: * @li the event header TMirrorEventHeader * @li the pixel data TMirrorPixelData, containing the image read from the SLT * @li a list of all pixels (TMirrorPixelList) contained in that event * @li a block of the FADC data traces (TMirrorFADCData) * * The mapping to shared memory is presently done by C-structs which are * handled through private pointers inside the classes. * * @todo Make the event specific C-structs private to the classes. * * At the moment the relation between the C++ classes and the C-structs are: * @li MiEvent is related with TMirrorEvent * @li MiEventHeader is related with TMirrorEventHeader * @li MiPixelData is related with TMirrorPixelData * @li MiPixelList is related with TMirrorPixelList * @li MiFADCData is related with TMirrorFADCData * @li FADCData is related with TFADCData */ class TMirrorEvent : public VMirrorEvent { public: /** This enumeration defines the way how the data are saved by the * Streamer() method of the class TMirrorEvent. */ enum { /** Save all data components. This is at present the default. * * 'All' includes: * @li the TMirrorEventHeader * @li the TMirrorPixelData * @li the TMirrorPixelList * @li the TMirrorFADCData * @li the TMirrorTriggerData */ kSaveAll = 0x80000000, /** Save the information of the class TMirrorEventHeader. */ kSaveEventHeader = 0x00000001, /** Save the information of the class TMirrorPixelData (SLT pixel data). */ kSavePixelData = 0x00000002, /** Save the information of the class TMirrorPixelList. */ kSavePixelList = 0x00000004, /** Save the information of the class TMirrorFADCData according to the * pixel list. */ kSaveFadcData = 0x00000008, /** Save the information of the class TMirrorTriggerData. */ kSaveTriggerData = 0x00000010, /** Save all types of calibrated data. */ kSaveCalibratedData = 0x00040000, /** Save all types of analysed data. */ kSaveAnalysedData = 0x00080000 }; public: /** Constructor for class TMirrorEvent. * * As there are different constructors, fConstructorType stores the * information how the TMirrorEvent object was created * in order to destroy it later correctly * * This is the default constructor which uses internally the MiEvent...() * functions which create appropiate C-structs. * * As the 'sub-objects' of TMirrorEvent are normally never created by the * user, MiEventCreate() creates all the sub-structs and the constructors * for the sub-objects are called. * * As the copying of a TMirrorEvent is not a trivial task, at present the * copy constructors are private to prevent the user from copying. The * same is also valid for the other classes describing the event data. */ TMirrorEvent(); #ifndef __CINT__ // Cint is not allowed to see this !!! /** Constructor for TMirrorEvent from TShmEvent * * Create sub-objects from the C-struct pointers found in the TShmEvent * struct. This constructor should be used very carefully since it is * designed to create a TMirrorEvent object from a area of shared memory. * Therefor it is assumed, that this memory has a special structure and * is sufficiently large enough. If any of these preconditions are not * given, the results will be unpredictable. */ TMirrorEvent(TShmEvent*); #endif // __CINT__ /** Copy constructor of the class TMirrorEvent. */ TMirrorEvent(const TMirrorEvent&); /** Destructor of a TMirrorEvent object for all types of constructors. * * It uses the internal variable fConstructorType to select how the * object has to be destroyed. */ virtual ~TMirrorEvent(); /** operator=() for class TMirrorEvent. * * This operator has to be defined in order to perform a deep copy of * a TMirrorEvent object. */ TMirrorEvent& operator=(const TMirrorEvent&); /** Clear the contents of a TMirrorEvent. * * Sub-objects are only cleared if they are present (internal detail). */ virtual void Clear(Option_t *o=""); /** Print the contents of a TMirrorEvent to the specified stream. * * This is done by subsequent calling the Show() methods of the * sub-event classes. */ void Show(std::ostream& ostr=std::cout) const; /** Set the option how the data of the TMirrorEvent is saved into a ROOT * file or how it is sent via a TCP/IP socket. * * The default is, that all event constitutents are saved/sent. */ void SetSaveOption(/* unsigned */ int option) { fSaveOption = option; } #ifndef __CINT__ // Cint is not allowed to see this !!! /** Update internal references according to current TShmEvent. */ void Update(TShmEvent*); #endif // __CINT__ // access functions for sub structures public: /** Return a pointer to the TMirrorEventHeader object which describes * the event header of the current event. */ virtual TMirrorEventHeader* GetEventHeader(); /** Return a pointer to the TMirrorFADCData object. This object holds the * data of all FADCs plus their corresponding monitoring data. */ virtual TMirrorFADCData* GetFADCData(); /** Return a pointer to the TMirrorPixelData object which describes the bit * pattern from the SLT pixel memory. */ virtual TMirrorPixelData* GetPixelData(); /** Return a pointer to the TMirrorPixelList object. * * This object represents a list of variable length which contains the * pixel numbers of all triggered pixels. */ virtual TMirrorPixelList* GetPixelList(); /** Return the save option for the current event/file. */ /* unsigned */ int GetSaveOption() const { return fSaveOption; } /** Return a pointer to the TMirrorTriggerData object. * * This object represents data created by the TLT processor. */ virtual TMirrorTriggerData* GetTriggerData(); // --- required by interface VMiEvent /** Return a pointer to the TFADCData object for the speicified pixel, * might be NULL if the pixel doesn't exist. */ virtual TFADCData* GetFADCData(FdUtil::Fd::PixelNumber pixel); /** Return a pointer to the TFADCData object for the speicified pixel, the * readout of the trace could be limited. Might be NULL if the pixel * doesn't exist. */ virtual TFADCData* GetFADCData(FdUtil::Fd::PixelNumber pixel, TFADCData::FADCTraceInfo info); /** Return a pointer to the PixelMonitorData of the specified pixel, NULL * if the pixel doesn't exist. */ virtual TFADCData::PixelMonitorData GetMonitorData(FdUtil::Fd::PixelNumber); /** */ virtual TMirrorEventHeader::EMiTriggerSource GetTriggerSource(); public: /** Get the print level (= level of verbosity) for all instances of this * class. */ static unsigned int GetPrintLevel() { return fgPrintLevel; } /** Set the logging level for all instances of all TMirror* classes. * * Only messages with a severity greater or equal to this level are * printed to the default logging steram. */ static void SetLoggingLevel(FdUtil::ErrorLogger::ESeverityLevel level) { fgLoggingLevel = level; } /** Set the print level (= level of verbosity) for all instances of this * class. */ static void SetPrintLevel(unsigned int level=1) { fgPrintLevel = level; } private: MiEvent::Constructor_t fConstructorType; //! how object was created TMirrorEventHeader *fEventHeader; //! ptr. to TMirrorEventHeader TMirrorPixelData *fPixelData; //! ptr. to TMirrorPixelData TMirrorPixelList *fPixelList; //! ptr. to TMirrorPixelList TMirrorFADCData *fFADCData; //! ptr. to TMirrorFADCData TMirrorTriggerData *fTriggerData; //! ptr. to TMirrorTriggerData // unsigned int fSaveOption; // save which parts of object int fSaveOption; // save which parts of object static FdUtil::ErrorLogger::ESeverityLevel fgLoggingLevel; static unsigned int fgPrintLevel; //! print/verbosity level for TMirror* classes ClassDef(TMirrorEvent,MiEVENTVERSIONv4) }; #endif // _MiEvent_hh_