✨ [MRRTF-99] Add support for MCH UserLogic Raw Data Format V1

Author: aphecetche

Detectors/MUON/MCH/Raw/Common/include/MCHRawCommon/DataFormats.h

@@ -34,6 +34,54 @@ using uint10_t = uint16_t;
 using uint20_t = uint32_t;
 using uint50_t = uint64_t;
 
+// Format of 64 bits-words of the UserLogicFormat
+template <int VERSION>
+struct ULHeaderWord;
+
+// initial UL format (2020)
+template <>
+struct ULHeaderWord<0> {
+  union {
+    uint64_t word;
+    struct {
+      uint64_t data : 50;
+      uint64_t error : 2;
+      uint64_t incomplete : 1;
+      uint64_t dsID : 6;
+      uint64_t linkID : 5;
+    };
+  };
+};
+
+// version 1 of UL format (2021)
+// = as initial version with 1 bit less for linkID and 1 bit more for error
+template <>
+struct ULHeaderWord<1> {
+  union {
+    uint64_t word;
+    struct {
+      uint64_t data : 50;
+      uint64_t error : 3;
+      uint64_t incomplete : 1;
+      uint64_t dsID : 6;
+      uint64_t linkID : 4;
+    };
+  };
+};
+
+// structure of the FEEID field (16 bits) in the MCH Raw Data RDH
+struct FEEID {
+  union {
+    uint16_t word;
+    struct {
+      uint16_t id : 8;
+      uint16_t chargeSum : 1;
+      uint16_t reserved : 3;
+      uint16_t ulFormatVersion : 4;
+    };
+  };
+};
+
 }; // namespace o2::mch::raw
 
 #endif

Detectors/MUON/MCH/Raw/Decoder/README.md

@@ -16,15 +16,16 @@ called a (CRU) page. How the loop on the raw pages is done is *not* the decoder
 
 ## createPageDecoder
 
-On the reading/consumer/decoding end, the choice of the internal decoder to use is made
-using the data itself. You must give (at least) a part of a raw data buffer that contains
- a (valid) RawDataHeader. That RDH is used to deduce which implementation is picked.
+On the reading/consumer/decoding end, the choice of the internal decoder to use
+is made using the data itself. You must give (at least) a part of a raw data
+buffer that contains a (valid) RawDataHeader. That RDH is used to deduce which
+implementation is picked.
 
     gsl::span<const std::byte> rawbuffer = ... ;
     auto pageDecoder = o2::mch::raw::createPageDecoder(rawbuffer,channelHandler);
 
 The `pageDecoder` that is returned is a function that you have to call on each
-data page that you want to decode : 
+data page that you want to decode :
 
     while(some_data_is_available) {
     // get some memory buffer from somewhere ...
@@ -34,20 +35,22 @@ data page that you want to decode :
     pageDecode(buffer);
     }
 
-Internally the implementation is using templatized implementation, `PageDecoderImpl<FORMAT,CHARGESUM>`.
-Currently the following template parameters combinations have been tested : 
+Internally the implementation is using templatized implementation, `PageDecoderImpl<FORMAT,CHARGESUM,VERSION>`.
+Currently the following template parameters combinations have been tested :
 
-|      FORMAT     |   CHARGESUM   |
-| :-------------: | :-----------: |
-|    BareFormat   | ChargeSumMode |
-|    BareFormat   |   SampleMode  |
-| UserLogicFormat | ChargeSumMode |
-| UserLogicFormat |   SampleMode  |
+|      FORMAT     |   CHARGESUM   | VERSION |
+| :-------------: | :-----------: | :-----: |
+|    BareFormat   | ChargeSumMode |    0    |
+|    BareFormat   |   SampleMode  |    0    |
+| UserLogicFormat | ChargeSumMode |    0    |
+| UserLogicFormat |   SampleMode  |    0    |
+| UserLogicFormat | ChargeSumMode |    1    |
+| UserLogicFormat |   SampleMode  |    1    |
 
-The `createPageDecoder` function requires two parameters : a raw memory buffer 
-(in the form of a `gsl::span<const std::byte>` (note that the span is on constant bytes, 
-i.e. the input buffer is read-only)
-and a `SampaChannelHandler`.
+The `createPageDecoder` function requires two parameters : a raw memory buffer
+(in the form of a `gsl::span<const std::byte>` (note that the span is on
+constant bytes, i.e. the input buffer is read-only) and a
+`SampaChannelHandler`.
 
 ## SampaChannelHandler
 
@@ -57,7 +60,7 @@ identifier within that dual sampa, a `SampaCluster` and returns nothing, i.e. :
 
 > A word of caution here about the naming. A `SampaCluster` is a group of raw
 > data samples of *one* dual sampa channel, and has nothing to do with a
-> cluster of pads or something alike. 
+> cluster of pads or something alike.
 
 ```.cpp
 using SampaChannelHandler = std::function<void(DsElecId dsId,
@@ -67,7 +70,7 @@ using SampaChannelHandler = std::function<void(DsElecId dsId,
 
 That function is called by the raw data decoder for each `SampaCluster` that it
 finds in the data.
-A very simple example would be a function to dump the SampaClusters : 
+A very simple example would be a function to dump the SampaClusters :
 
 ```.cpp
 SampaChannelHandler handlePacket(DsElecId dsId, uint8_t channel, SampaCluster sc) {
@@ -78,5 +81,5 @@ SampaChannelHandler handlePacket(DsElecId dsId, uint8_t channel, SampaCluster sc
 
 ## Example of decoding raw data
 
-A (not particularly clean) example of how to decode raw data can be found in the source of the `o2-mchraw-dump` 
- executable [rawdump](../Tools/rawdump.cxx)
+A (not particularly clean) example of how to decode raw data can be found in
+the source of the `o2-mchraw-dump` executable [rawdump](../Tools/rawdump.cxx)

Detectors/MUON/MCH/Raw/Decoder/src/DataDecoder.cxx

@@ -74,8 +74,13 @@ static void patchPage(gsl::span<const std::byte> rdhBuffer, bool verbose)
   auto cruId = o2::raw::RDHUtils::getCRUID(rdhAny) & 0xFF;
   auto flags = o2::raw::RDHUtils::getCRUID(rdhAny) & 0xFF00;
   auto endpoint = o2::raw::RDHUtils::getEndPointID(rdhAny);
-  uint32_t feeId = cruId * 2 + endpoint + flags;
-  o2::raw::RDHUtils::setFEEID(rdhAny, feeId);
+  auto existingFeeId = o2::raw::RDHUtils::getFEEID(rdhAny);
+  if (existingFeeId == 0) {
+    // early versions of raw data did not set the feeId
+    // which we need to select the right decoder
+    uint32_t feeId = cruId * 2 + endpoint + flags;
+    o2::raw::RDHUtils::setFEEID(rdhAny, feeId);
+  }
 
   if (verbose) {
     std::cout << mNrdhs << "--\n";

Detectors/MUON/MCH/Raw/Decoder/src/PageDecoder.cxx

@@ -20,10 +20,8 @@ namespace o2::mch::raw
 {
 namespace impl
 {
-uint16_t CRUID_MASK = 0xFF;
-uint16_t CHARGESUM_MASK = 0x100;
 
-template <typename FORMAT, typename CHARGESUM>
+template <typename FORMAT, typename CHARGESUM, int VERSION = 0>
 struct PayloadDecoderImpl {
 
   using type = struct PayloadDecoderImplReturnType {
@@ -33,18 +31,18 @@ struct PayloadDecoderImpl {
   type operator()(const FeeLinkId& feeLinkId, DecodedDataHandlers decodedDataHandlers, FeeLink2SolarMapper fee2solar);
 };
 
-template <typename CHARGESUM>
-struct PayloadDecoderImpl<UserLogicFormat, CHARGESUM> {
-  using type = UserLogicEndpointDecoder<CHARGESUM>;
+template <typename CHARGESUM, int VERSION>
+struct PayloadDecoderImpl<UserLogicFormat, CHARGESUM, VERSION> {
+  using type = UserLogicEndpointDecoder<CHARGESUM, VERSION>;
 
   type operator()(const FeeLinkId& feeLinkId, DecodedDataHandlers decodedDataHandlers, FeeLink2SolarMapper fee2solar)
   {
-    return std::move(UserLogicEndpointDecoder<CHARGESUM>(feeLinkId.feeId(), fee2solar, decodedDataHandlers));
+    return std::move(UserLogicEndpointDecoder<CHARGESUM, VERSION>(feeLinkId.feeId(), fee2solar, decodedDataHandlers));
   }
 };
 
 template <typename CHARGESUM>
-struct PayloadDecoderImpl<BareFormat, CHARGESUM> {
+struct PayloadDecoderImpl<BareFormat, CHARGESUM, 0> {
   using type = BareGBTDecoder<CHARGESUM>;
 
   type operator()(const FeeLinkId& feeLinkId, DecodedDataHandlers decodedDataHandlers, FeeLink2SolarMapper fee2solar)
@@ -57,7 +55,7 @@ struct PayloadDecoderImpl<BareFormat, CHARGESUM> {
   }
 };
 
-template <typename FORMAT, typename CHARGESUM>
+template <typename FORMAT, typename CHARGESUM, int VERSION = 0>
 class PageDecoderImpl
 {
  public:
@@ -75,11 +73,12 @@ class PageDecoderImpl
 
     auto feeId = o2::raw::RDHUtils::getFEEID(rdhP);
     auto linkId = o2::raw::RDHUtils::getLinkID(rdhP);
-    FeeLinkId feeLinkId(feeId & CRUID_MASK, linkId);
+    FEEID f{feeId};
+    FeeLinkId feeLinkId(f.id, linkId);
 
     auto p = mPayloadDecoders.find(feeLinkId);
     if (p == mPayloadDecoders.end()) {
-      mPayloadDecoders.emplace(feeLinkId, PayloadDecoderImpl<FORMAT, CHARGESUM>()(feeLinkId, mDecodedDataHandlers, mFee2SolarMapper));
+      mPayloadDecoders.emplace(feeLinkId, PayloadDecoderImpl<FORMAT, CHARGESUM, VERSION>()(feeLinkId, mDecodedDataHandlers, mFee2SolarMapper));
       p = mPayloadDecoders.find(feeLinkId);
     }
 
@@ -95,7 +94,7 @@ class PageDecoderImpl
  private:
   DecodedDataHandlers mDecodedDataHandlers;
   FeeLink2SolarMapper mFee2SolarMapper;
-  std::map<FeeLinkId, typename PayloadDecoderImpl<FORMAT, CHARGESUM>::type> mPayloadDecoders;
+  std::map<FeeLinkId, typename PayloadDecoderImpl<FORMAT, CHARGESUM, VERSION>::type> mPayloadDecoders;
 };
 
 } // namespace impl
@@ -109,19 +108,32 @@ PageDecoder createPageDecoder(RawBuffer rdhBuffer, DecodedDataHandlers decodedDa
   }
   auto linkId = o2::raw::RDHUtils::getLinkID(rdhP);
   auto feeId = o2::raw::RDHUtils::getFEEID(rdhP);
+  FEEID f{feeId};
   if (linkId == 15) {
-    if (feeId & impl::CHARGESUM_MASK) {
-      return impl::PageDecoderImpl<UserLogicFormat, ChargeSumMode>(decodedDataHandlers, fee2solar);
+    if (f.ulFormatVersion != 0 && f.ulFormatVersion != 1) {
+      throw std::logic_error(fmt::format("ulFormatVersion {} is unknown", static_cast<int>(f.ulFormatVersion)));
+    }
+    if (f.chargeSum) {
+      if (f.ulFormatVersion == 0) {
+        return impl::PageDecoderImpl<UserLogicFormat, ChargeSumMode, 0>(decodedDataHandlers, fee2solar);
+      } else if (f.ulFormatVersion == 1) {
+        return impl::PageDecoderImpl<UserLogicFormat, ChargeSumMode, 1>(decodedDataHandlers, fee2solar);
+      }
     } else {
-      return impl::PageDecoderImpl<UserLogicFormat, SampleMode>(decodedDataHandlers, fee2solar);
+      if (f.ulFormatVersion == 0) {
+        return impl::PageDecoderImpl<UserLogicFormat, SampleMode, 0>(decodedDataHandlers, fee2solar);
+      } else if (f.ulFormatVersion == 1) {
+        return impl::PageDecoderImpl<UserLogicFormat, SampleMode, 1>(decodedDataHandlers, fee2solar);
+      }
     }
   } else {
-    if (feeId & impl::CHARGESUM_MASK) {
+    if (f.chargeSum) {
       return impl::PageDecoderImpl<BareFormat, ChargeSumMode>(decodedDataHandlers, fee2solar);
     } else {
       return impl::PageDecoderImpl<BareFormat, SampleMode>(decodedDataHandlers, fee2solar);
     }
   }
+  return nullptr;
 }
 
 PageDecoder createPageDecoder(RawBuffer rdhBuffer, DecodedDataHandlers decodedDataHandlers)

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

@@ -36,7 +36,7 @@ class UserLogicElinkDecoder
   UserLogicElinkDecoder(DsElecId dsId, DecodedDataHandlers decodedDataHandlers);
 
   /// Append 50 bits-worth of data
-  void append(uint64_t data50, uint8_t error);
+  void append(uint64_t data50, uint8_t error, bool incomplete);
 
   /// Reset our internal state
   /// i.e. assume the sync has to be found again
@@ -99,11 +99,6 @@ constexpr bool isSync(uint64_t data)
   return data == sampaSyncWord;
 };
 
-constexpr bool isIncomplete(uint8_t error)
-{
-  return (error & 0x4) > 0;
-}
-
 template <typename CHARGESUM>
 UserLogicElinkDecoder<CHARGESUM>::UserLogicElinkDecoder(DsElecId dsId,
                                                         DecodedDataHandlers decodedDataHandlers)
@@ -112,10 +107,10 @@ UserLogicElinkDecoder<CHARGESUM>::UserLogicElinkDecoder(DsElecId dsId,
 }
 
 template <typename CHARGESUM>
-void UserLogicElinkDecoder<CHARGESUM>::append(uint64_t data50, uint8_t error)
+void UserLogicElinkDecoder<CHARGESUM>::append(uint64_t data50, uint8_t error, bool incomplete)
 {
 #ifdef ULDEBUG
-  debugHeader() << (*this) << fmt::format(" --> append50 {:013x} error {} incomplete {} data10={:d} {:d} {:d} {:d} {:d}\n", data50, error, (int)isIncomplete(error), static_cast<uint10_t>(data50 & 0x3FF), static_cast<uint10_t>((data50 & 0xFFC00) >> 10), static_cast<uint10_t>((data50 & 0x3FF00000) >> 20), static_cast<uint10_t>((data50 & 0xFFC0000000) >> 30), static_cast<uint10_t>((data50 & 0x3FF0000000000) >> 40));
+  debugHeader() << (*this) << fmt::format(" --> append50 {:013x} error {} incomplete {} data10={:d} {:d} {:d} {:d} {:d}\n", data50, error, incomplete, static_cast<uint10_t>(data50 & 0x3FF), static_cast<uint10_t>((data50 & 0xFFC00) >> 10), static_cast<uint10_t>((data50 & 0x3FF00000) >> 20), static_cast<uint10_t>((data50 & 0xFFC0000000) >> 30), static_cast<uint10_t>((data50 & 0x3FF0000000000) >> 40));
 #endif
 
   if (isSync(data50)) {
@@ -134,8 +129,8 @@ void UserLogicElinkDecoder<CHARGESUM>::append(uint64_t data50, uint8_t error)
     bool packetEnd = append10(static_cast<uint10_t>(data & 0x3FF));
     data >>= 10;
 #ifdef ULDEBUG
-    if (isIncomplete(error)) {
-      debugHeader() << (*this) << fmt::format(" --> incomplete {} packetEnd @i={}\n", (int)isIncomplete(error), packetEnd, i);
+    if (incomplete) {
+      debugHeader() << (*this) << fmt::format(" --> incomplete {} packetEnd @i={}\n", incomplete, packetEnd, i);
     }
 #endif
     if (hasError()) {
@@ -145,15 +140,15 @@ void UserLogicElinkDecoder<CHARGESUM>::append(uint64_t data50, uint8_t error)
       reset();
       break;
     }
-    if (isIncomplete(error) && packetEnd) {
+    if (incomplete && packetEnd) {
 #ifdef ULDEBUG
       debugHeader() << (*this) << " stop due to isIncomplete\n";
 #endif
       break;
     }
   }
 
-  if (isIncomplete(error) && (i == 5) && (mState != State::WaitingSync)) {
+  if (incomplete && (i == 5) && (mState != State::WaitingSync)) {
 #ifdef ULDEBUG
     debugHeader() << (*this) << " data packet end not found when isIncomplete --> resetting\n";
 #endif