MCH: digit time from TF start (#5530)

* [MCH] implemented decoding of HeartBeat packets

* [MCH] changed definition of digit time

* [MCH] implemented sending of full TimeFrames in MCH data reader

The TimeFrames are sent for each CRU link separately, so this is not
a real replacement of the StfBuilder.
An "overlap" option allows to have N HeartBeat frames in common between
consecutive TimeFrames.

* [MCH] improved help messages

* [MCH] simplified digit time computation

* [MCH] fixed clang formatting

* [MCH] added unit test for time computation functions

Also added setter/getter functions for the " saturated" flag

* [MCH] fixed clang formatting

* [MCH] fixed code formatting

Author: aferrero2707

Detectors/MUON/MCH/Base/include/MCHBase/Digit.h

@@ -28,34 +28,22 @@ namespace mch
 class Digit
 {
  public:
-  struct Time {
-    union {
-      // default value
-      uint64_t time = 0x0000000000000000;
-      struct {                       ///
-        uint32_t sampaTime : 10;     /// bit 0 to 9: sampa time
-        uint32_t bunchCrossing : 20; /// bit 10 to 29: bunch crossing counter
-        uint32_t reserved : 2;       /// bit 30 to 31: reserved
-        uint32_t orbit;              /// bit 32 to 63: orbit
-      };                             ///
-    };
-    uint64_t getBXTime()
-    {
-      return (bunchCrossing + (sampaTime * 4));
-    }
-  };
-
   Digit() = default;
 
-  Digit(int detid, int pad, unsigned long adc, Time time, uint16_t nSamples = 1);
+  Digit(int detid, int pad, unsigned long adc, int32_t time, uint16_t nSamples = 1);
   ~Digit() = default;
 
   bool operator==(const Digit&) const;
 
-  Time getTime() const { return mTime; }
+  // time in bunch crossing units, relative to the beginning of the TimeFrame
+  void setTime(int32_t t) { mTFtime = t; }
+  int32_t getTime() const { return mTFtime; }
+
+  void setNofSamples(uint16_t n);
+  uint16_t nofSamples() const { return (mNofSamples & 0x7FFF); }
 
-  uint16_t nofSamples() const { return mNofSamples; }
-  void setNofSamples(uint16_t n) { mNofSamples = n; }
+  void setSaturated(bool sat);
+  bool isSaturated() const { return ((mNofSamples & 0x8000) > 0); }
 
   int getDetID() const { return mDetID; }
 
@@ -66,11 +54,11 @@ class Digit
   void setADC(unsigned long adc) { mADC = adc; }
 
  private:
-  Time mTime;
+  int32_t mTFtime;      /// time since the beginning of the time frame, in bunch crossing units
   uint16_t mNofSamples; /// number of samples in the signal
-  int mDetID;
-  int mPadID;         /// PadIndex to which the digit corresponds to
-  unsigned long mADC; /// Amplitude of signal
+  int mDetID;           /// ID of the Detection Element to which the digit corresponds to
+  int mPadID;           /// PadIndex to which the digit corresponds to
+  unsigned long mADC;   /// Amplitude of signal
 
   ClassDefNV(Digit, 2);
 }; //class Digit

Detectors/MUON/MCH/Base/src/Digit.cxx

@@ -19,17 +19,33 @@ bool closeEnough(double x, double y, double eps = 1E-6)
   return std::fabs(x - y) <= eps * std::max(1.0, std::max(std::fabs(x), std::fabs(y)));
 }
 
-Digit::Digit(int detid, int pad, unsigned long adc, Time time, uint16_t nSamples)
-  : mDetID(detid), mPadID(pad), mADC(adc), mTime(time), mNofSamples(nSamples)
+Digit::Digit(int detid, int pad, unsigned long adc, int32_t time, uint16_t nSamples)
+  : mTFtime(time), mNofSamples(nSamples), mDetID(detid), mPadID(pad), mADC(adc)
 {
+  setSaturated(false);
+}
+
+void Digit::setNofSamples(uint16_t n)
+{
+  uint16_t sat = mNofSamples & 0x8000;
+  mNofSamples = (n & 0x7FFF) + sat;
+}
+
+void Digit::setSaturated(bool sat)
+{
+  if (sat) {
+    mNofSamples |= 0x8000;
+  } else {
+    mNofSamples &= 0x7FFF;
+  }
 }
 
 bool Digit::operator==(const Digit& other) const
 {
   return mDetID == other.mDetID &&
          mPadID == other.mPadID &&
          mADC == other.mADC &&
-         mTime.time == other.mTime.time &&
+         mTFtime == other.mTFtime &&
          mNofSamples == other.mNofSamples;
 }
 

Detectors/MUON/MCH/Clustering/src/ClusterFinderOriginal.cxx

@@ -174,7 +174,7 @@ void ClusterFinderOriginal::resetPreCluster(gsl::span<const Digit>& digits)
     double dx = mSegmentation->padSizeX(padID) / 2.;
     double dy = mSegmentation->padSizeY(padID) / 2.;
     double charge = static_cast<double>(digit.getADC()) / static_cast<double>(std::numeric_limits<unsigned long>::max()) * 1024;
-    bool isSaturated = digit.getTime().time > 0;
+    bool isSaturated = digit.isSaturated();
     int plane = mSegmentation->isBendingPad(padID) ? 0 : 1;
 
     if (charge <= 0.) {

Detectors/MUON/MCH/Raw/Decoder/CMakeLists.txt

@@ -35,4 +35,10 @@ if(BUILD_TESTING)
                 LABELS "muon;mch;raw"
                 PUBLIC_LINK_LIBRARIES O2::MCHRawDecoder Boost::boost)
 
+        o2_add_test(digits-time-computation
+                SOURCES src/testDigitsTimeComputation.cxx
+                COMPONENT_NAME mchraw
+                LABELS "muon;mch;raw"
+                PUBLIC_LINK_LIBRARIES O2::MCHRawDecoder Boost::boost)
+
 endif()

Detectors/MUON/MCH/Raw/Decoder/include/MCHRawDecoder/DataDecoder.h

@@ -17,6 +17,7 @@
 
 #include <gsl/span>
 #include <unordered_set>
+#include <unordered_map>
 
 #include "Headers/RDHAny.h"
 #include "MCHBase/Digit.h"
@@ -40,17 +41,62 @@ struct OrbitInfoHash {
   }
 };
 
+void dumpOrbits(const std::unordered_set<OrbitInfo, OrbitInfoHash>& mOrbits);
+
 //_________________________________________________________________
 //
 // Data decoder
 //_________________________________________________________________
 class DataDecoder
 {
  public:
+  struct SampaInfo {
+    union {
+      uint32_t id = 0;
+      struct {
+        uint32_t chip : 1;
+        uint32_t ds : 6;
+        uint32_t solar : 16;
+        uint32_t unused : 9;
+      };
+    };
+
+    union {
+      // default value
+      uint64_t time = 0x0000000000000000;
+      struct {                       ///
+        uint32_t sampaTime : 10;     /// bit 0 to 9: sampa time
+        uint32_t bunchCrossing : 20; /// bit 10 to 29: bunch crossing counter
+        uint32_t reserved : 2;       /// bit 30 to 31: reserved
+        uint32_t orbit;              /// bit 32 to 63: orbit
+      };                             ///
+    };
+    uint32_t getBXTime()
+    {
+      return (bunchCrossing + (sampaTime * 4));
+    }
+  };
+
+  struct SampaTimeFrameStart {
+    SampaTimeFrameStart(uint32_t orbit, uint32_t bunchCrossing) : mOrbit(orbit), mBunchCrossing(bunchCrossing) {}
+
+    uint32_t mOrbit{0};
+    int32_t mBunchCrossing{0};
+  };
+
+  using SampaTimeFrameStarts = std::unordered_map<uint32_t, std::optional<SampaTimeFrameStart>>;
+
   DataDecoder(SampaChannelHandler channelHandler, RdhHandler rdhHandler, std::string mapCRUfile, std::string mapFECfile, bool ds2manu, bool verbose);
 
   void reset();
-  void decodeBuffer(gsl::span<const std::byte> page);
+  void decodeBuffer(gsl::span<const std::byte> buf);
+
+  static int32_t digitsTimeDiff(uint32_t orbit1, uint32_t bc1, uint32_t orbit2, uint32_t bc2);
+  static void computeDigitsTime_(std::vector<o2::mch::Digit>& digits, std::vector<SampaInfo>& sampaInfo, SampaTimeFrameStarts& sampaTimeFrameStarts, bool debug);
+  void computeDigitsTime()
+  {
+    computeDigitsTime_(mOutputDigits, mSampaInfos, mSampaTimeFrameStarts, mDebug);
+  }
 
   const std::vector<o2::mch::Digit>& getOutputDigits() const { return mOutputDigits; }
   const std::unordered_set<OrbitInfo, OrbitInfoHash>& getOrbits() const { return mOrbits; }
@@ -59,22 +105,28 @@ class DataDecoder
   void initElec2DetMapper(std::string filename);
   void initFee2SolarMapper(std::string filename);
   void init();
+  void decodePage(gsl::span<const std::byte> page);
+  void dumpDigits(bool bending);
 
-  Elec2DetMapper mElec2Det{nullptr};
-  FeeLink2SolarMapper mFee2Solar{nullptr};
-  o2::mch::raw::PageDecoder mDecoder;
-  size_t mNrdhs{0};
-  std::vector<o2::mch::Digit> mOutputDigits;
-  std::unordered_set<OrbitInfo, OrbitInfoHash> mOrbits; ///< list of orbits in the processed buffer
+  Elec2DetMapper mElec2Det{nullptr};       ///< front-end electronics mapping
+  FeeLink2SolarMapper mFee2Solar{nullptr}; ///< CRU electronics mapping
+  std::string mMapFECfile;                 ///< optional text file with custom front-end electronics mapping
+  std::string mMapCRUfile;                 ///< optional text file with custom CRU mapping
 
-  SampaChannelHandler mChannelHandler;
-  std::function<void(o2::header::RDHAny*)> mRdhHandler;
+  o2::mch::raw::PageDecoder mDecoder; ///< CRU page decoder
+
+  std::vector<o2::mch::Digit> mOutputDigits; ///< vector of decoded digits
+  std::vector<SampaInfo> mSampaInfos;        ///< vector of auxiliary SampaInfo objects
+
+  std::unordered_set<OrbitInfo, OrbitInfoHash> mOrbits; ///< list of orbits in the processed buffer
+  SampaTimeFrameStarts mSampaTimeFrameStarts;           ///< time stamps of the TimeFrames in the processed buffer
 
-  std::string mMapCRUfile;
-  std::string mMapFECfile;
+  SampaChannelHandler mChannelHandler;                  ///< optional user function to be called for each decoded SAMPA hit
+  std::function<void(o2::header::RDHAny*)> mRdhHandler; ///< optional user function to be called for each RDH
 
   bool mDebug{false};
   bool mDs2manu{false};
+  uint32_t mOrbit{0};
 };
 
 } // namespace raw

Detectors/MUON/MCH/Raw/Decoder/include/MCHRawDecoder/DecodedDataHandlers.h

@@ -28,14 +28,21 @@ using SampaChannelHandler = std::function<void(DsElecId dsId,
                                                uint8_t channel,
                                                SampaCluster)>;
 
-/// A SampaChannSampaHeartBeatHandler is a function that takes a chip index and
+/// A SampaHeartBeatHandler is a function that takes a chip index and
 /// a bunch crossing counter value found in a HeartBeat packet
+using SampaHeartBeatHandler = std::function<void(DsElecId dsId,
+                                                 uint8_t chip,
+                                                 uint20_t bunchCrossing)>;
+
+/// A SampaErrorHandler is a function that takes a chip index and
+/// a numerical code describing the error encountered during the decoding
 using SampaErrorHandler = std::function<void(DsElecId dsId,
                                              int8_t chip,
                                              uint32_t error)>;
 
 struct DecodedDataHandlers {
   SampaChannelHandler sampaChannelHandler;
+  SampaHeartBeatHandler sampaHeartBeatHandler;
   SampaErrorHandler sampaErrorHandler;
 };
 

Detectors/MUON/MCH/Raw/Decoder/src/BareElinkDecoder.h

@@ -97,6 +97,7 @@ class BareElinkDecoder
   void oneLess10BitWord();
   void process();
   void sendCluster();
+  void sendHBPacket();
   void softReset();
 
   template <typename T>
@@ -260,8 +261,12 @@ void BareElinkDecoder<CHARGESUM>::handleHeader()
       softReset();
       break;
     case SampaPacketType::HeartBeat:
-      fmt::printf("BareElinkDecoder %d: HEARTBEAT found. Should be doing sth about it ?\n", mDsId);
-      softReset();
+      if (mSampaHeader.isHeartbeat()) {
+        sendHBPacket();
+        changeState(State::LookingForHeader, HEADERSIZE);
+      } else {
+        softReset();
+      }
       break;
     default:
       throw std::logic_error("that should not be possible");
@@ -440,6 +445,15 @@ void BareElinkDecoder<SampleMode>::sendCluster()
   mSamples.clear();
 }
 
+template <typename CHARGESUM>
+void BareElinkDecoder<CHARGESUM>::sendHBPacket()
+{
+  SampaHeartBeatHandler handler = mDecodedDataHandlers.sampaHeartBeatHandler;
+  if (handler) {
+    handler(mDsId, mSampaHeader.chipAddress() % 2, mSampaHeader.bunchCrossingCounter());
+  }
+}
+
 template <>
 void BareElinkDecoder<ChargeSumMode>::changeToReadingData()
 {