Single ECON-D event packet. More...

#include <ECONDEventPacket.h>

Public Types
enum	Corruption : std::size_t { BAD_HEADER_MARKER = 0 , BAD_LENGTH = 1 , BAD_HEADER_CRC = 2 , BAD_CRC32 = 3 , BAD_PAYLOAD = 4 , TRUNCATED = 5 , N_CORRUPTION = 6 }
	index of corruption flags More...

Public Member Functions
	ECONDEventPacket (std::size_t n_links)
	construct an event packet with the number of eRx "links"

bool	isEmpty () const
	payload length of zero, no link sub-packets

bool	isCorrupt () const
	any of the corruption flags are set

bool	from (std::span< const uint32_t > data)
	parse into the packet from the passed data span

Public Attributes
std::array< bool, N_CORRUPTION >	corruption_ {}
	corruption flags indexed by Corruption

uint32_t	header_marker_ {0}
	9b header marker

uint32_t	payload_length_ {0}
	payload length in 32b words (not including the two header words)

bool	passthrough_ {false}
	P: pass through mode.

bool	expected_ {false}
	E: HGCROC event header/trailer expected.

uint32_t	ht_ {0}
	H/T: status of HGCROC header/trailer reconstruction.

uint32_t	ebo_ {0}
	E/B/O: status of event/BX/orbit reconstruction.

bool	match_ {false}
	M: transmitted E/B/O matches the L1A FIFO.

bool	truncated_ {false}
	T: packet truncated for buffer overflow.

uint32_t	hamming_ {0}
	6b Hamming code of the header

uint32_t	bx_ {0}
	bunch crossing

uint32_t	l1a_ {0}
	6b L1A (event) number

uint32_t	orbit_ {0}
	3b orbit number

bool	subpacket_error_ {false}
	S: error in a link sub-packet.

uint32_t	reset_request_ {0}
	RR: reset request.

uint32_t	crc8_ {0}
	transmitted 8b header CRC

std::vector< ECONDLinkSubpacket >	links_
	storage of unpacked link data

Static Public Attributes
static const uint32_t	HEADER_MARKER_SPEC {0xaa << 1}
	spec default and common CMS header markers (8b marker + 0)

static const uint32_t	HEADER_MARKER_CMS {0xf3 << 1}

Private Member Functions
std::size_t	unpackLinkSubpacket (std::span< const uint32_t > data, ECONDLinkSubpacket &link) const
	Unpack a eRx ("link") sub-packet.

	enableLogging ("ECONDEventPacket")
	handle to logging source

Detailed Description

Single ECON-D event packet.

The ECON-D is the CONcentrator mezzanine for the Data path and it has many different configuration modes. The two most important to us for decoding are

"Pass Through" mode - all 37 sample words are copied from the link, the link headers from the ROC are overwritten by ECOND link headers
"Regular" mode - the ECOND event format is written which can include zero-suppression of multiple varieties including full eliminating channels that are empty

The format is described in Section 18 of the ECON-D specification (ECON-D_specification_working_doc_v1.4_5jan2023.pdf).

Note: Ported from pflib::packing::ECONDEventPacket with bounds checks added so that corrupted packets are flagged instead of read past.

Definition at line 64 of file ECONDEventPacket.h.

Member Enumeration Documentation

◆ Corruption

enum packing::ECONDEventPacket::Corruption : std::size_t

index of corruption flags

Enumerator
BAD_HEADER_MARKER	9b header marker is not the ECOND spec or common CMS config
BAD_LENGTH	stored payload length does not equal packet length
BAD_HEADER_CRC	8b header CRC mismatch
BAD_CRC32	32b sub-packet CRC mismatch
BAD_PAYLOAD	link sub-packets do not fit or do not end at the CRC word
TRUNCATED	T flag set, link sub-packets not transmitted.
N_CORRUPTION	number of corruption flags

Definition at line 67 of file ECONDEventPacket.h.

                  : std::size_t {
    BAD_HEADER_MARKER = 0,
    BAD_LENGTH = 1,
    BAD_HEADER_CRC = 2,
    BAD_CRC32 = 3,
    BAD_PAYLOAD = 4,
    TRUNCATED = 5,
    N_CORRUPTION = 6
  };

Constructor & Destructor Documentation

◆ ECONDEventPacket()

packing::ECONDEventPacket::ECONDEventPacket ( std::size_t n_links )

explicit

construct an event packet with the number of eRx "links"

Definition at line 214 of file ECONDEventPacket.cxx.

214: links_(n_links) {}

packing::ECONDEventPacket::links_

std::vector< ECONDLinkSubpacket > links_

storage of unpacked link data

Definition ECONDEventPacket.h:124

Member Function Documentation

◆ from()

bool packing::ECONDEventPacket::from ( std::span< const uint32_t > data )

parse into the packet from the passed data span

The span should start at the first ECON-D header word and contain the full packet (as given by the DAQ capture header length). This function never reads outside of the span. On corruption, the corresponding flag is set and parsing stops early.

Returns: true if the packet is not corrupt

Definition at line 221 of file ECONDEventPacket.cxx.

                                                        {
  corruption_.fill(false);
  std::fill(links_.begin(), links_.end(), ECONDLinkSubpacket{});
  payload_length_ = 0;
 
  if (data.size() < 2) {
    ldmx_log(debug) << "packet of " << data.size()
                    << " words is too short for the two header words";
    corruption_[BAD_LENGTH] = true;
    if (data.empty()) return false;
  }
 
  ldmx_log(trace) << "econd header one: " << Hex(data[0]);
  header_marker_ = ((data[0] >> 23) & MASK<9>);
  corruption_[BAD_HEADER_MARKER] = (header_marker_ != HEADER_MARKER_SPEC) and
                                   (header_marker_ != HEADER_MARKER_CMS);
  if (corruption_[BAD_HEADER_MARKER]) {
    // most likely not an ECON-D header at all
    ldmx_log(debug) << "Bad header marker from ECOND 0x" << std::hex
                    << (header_marker_ >> 1) << " + 0b"
                    << (header_marker_ & 0b1) << std::dec << " in word "
                    << Hex(data[0]);
    return false;
  }
  if (corruption_[BAD_LENGTH]) return false;
 
  payload_length_ = ((data[0] >> 14) & MASK<9>);
  passthrough_ = ((data[0] >> 13) & MASK<1>) == 1;
  expected_ = ((data[0] >> 12) & MASK<1>) == 1;
  ht_ = ((data[0] >> 10) & MASK<2>);
  ebo_ = ((data[0] >> 8) & MASK<2>);
  match_ = ((data[0] >> 7) & MASK<1>) == 1;
  truncated_ = ((data[0] >> 6) & MASK<1>) == 1;
  hamming_ = (data[0] & MASK<6>);
 
  ldmx_log(trace) << "econd header two: " << Hex(data[1]);
  bx_ = ((data[1] >> 20) & MASK<12>);
  l1a_ = ((data[1] >> 14) & MASK<6>);
  orbit_ = ((data[1] >> 11) & MASK<3>);
  subpacket_error_ = ((data[1] >> 10) & MASK<1>) == 1;
  reset_request_ = ((data[1] >> 8) & MASK<2>);
  crc8_ = (data[1] & MASK<8>);
  ldmx_log(trace) << "    length=" << payload_length_ << " P=" << passthrough_
                  << " BX=" << bx_ << " L1A=" << l1a_ << " Orb=" << orbit_;
 
  corruption_[BAD_LENGTH] = (data.size() != (payload_length_ + 2));
  if (corruption_[BAD_LENGTH]) {
    ldmx_log(debug) << "stored payload length " << payload_length_
                    << " does not match the packet length (" << data.size()
                    << " - 2)";
    if (data.size() < (payload_length_ + 2)) return false;
  }
 
  // 8b CRC over both header words without the Hamming and the CRC
  uint64_t header_crc_base = (data[0] >> 6);
  header_crc_base <<= 30;
  header_crc_base |= (data[1] >> 8);
  uint8_t header_crc_val = utility::econdCrc8(header_crc_base);
  corruption_[BAD_HEADER_CRC] = (header_crc_val != crc8_);
  if (corruption_[BAD_HEADER_CRC]) {
    ldmx_log(debug) << "Event header 8b CRC does not match transmitted value: "
                    << std::bitset<8>(header_crc_val)
                    << " != " << std::bitset<8>(crc8_);
  }
 
  if (isEmpty()) {
    ldmx_log(trace) << "empty packet, no link sub-packets";
    return not isCorrupt();
  }
 
  // the last payload word is the CRC over all link sub-packets
  auto payload{data.subspan(2, payload_length_)};
  auto subpackets{payload.first(payload_length_ - 1)};
  uint32_t crc_val = utility::crc32(subpackets);
  uint32_t target = payload.back();
  corruption_[BAD_CRC32] = (crc_val != target);
  if (corruption_[BAD_CRC32]) {
    ldmx_log(debug)
        << "CRC over all link sub-packets does not match transmitted value "
        << Hex(crc_val) << " != " << Hex(target);
  }
 
  if (corruption_[BAD_HEADER_CRC]) return false;
 
  if (truncated_) {
    ldmx_log(debug) << "Buffer control detected insufficient space so it did "
                       "not transfer link packets.";
    corruption_[TRUNCATED] = true;
    return false;
  }
 
  std::size_t offset{0};
  for (auto& link : links_) {
    auto length = unpackLinkSubpacket(subpackets.subspan(offset), link);
    if (length == 0) {
      corruption_[BAD_PAYLOAD] = true;
      return false;
    }
    offset += length;
  }
 
  if (offset != subpackets.size()) {
    ldmx_log(debug) << "link sub-packets end at " << offset
                    << " but the CRC word is at " << subpackets.size();
    corruption_[BAD_PAYLOAD] = true;
  }
 
  return not isCorrupt();
}

References BAD_CRC32, BAD_HEADER_CRC, BAD_HEADER_MARKER, BAD_LENGTH, BAD_PAYLOAD, bx_, corruption_, crc8_, ebo_, expected_, hamming_, header_marker_, HEADER_MARKER_SPEC, ht_, isCorrupt(), isEmpty(), l1a_, links_, match_, orbit_, passthrough_, payload_length_, reset_request_, subpacket_error_, TRUNCATED, truncated_, and unpackLinkSubpacket().

◆ isCorrupt()

bool packing::ECONDEventPacket::isCorrupt ( ) const

any of the corruption flags are set

Definition at line 216 of file ECONDEventPacket.cxx.

                                       {
  return std::any_of(corruption_.begin(), corruption_.end(),
                     [](bool c) { return c; });
}

References corruption_.

Referenced by from().

◆ isEmpty()

bool packing::ECONDEventPacket::isEmpty ( ) const

inline

payload length of zero, no link sub-packets

Definition at line 130 of file ECONDEventPacket.h.

130{ return payload_length_ == 0; }

References payload_length_.

Referenced by from().

◆ unpackLinkSubpacket()

std::size_t packing::ECONDEventPacket::unpackLinkSubpacket	(	std::span< const uint32_t >	data,
		ECONDLinkSubpacket &	link ) const

private

Unpack a eRx ("link") sub-packet.

Parameters

[in]	data	words from the start of the sub-packet to the CRC word (not included)
[out]	link	sub-packet to update with unpacked data

Returns: length of data in 32b words that was unpacked, 0 if the sub-packet does not fit into data

Definition at line 37 of file ECONDEventPacket.cxx.

                                                                  {
  if (data.empty()) {
    ldmx_log(debug) << "no words left for link sub-packet";
    return 0;
  }
  ldmx_log(trace) << "link header " << Hex(data[0]);
  link.stat_ = ((data[0] >> 29) & MASK<3>);
  if (link.badStat()) {
    std::bitset<3> bits = link.stat_;
    std::string names;
    for (std::size_t i{0}; i < 3; i++) {
      if (!bits.test(i)) names += std::string(" ") + LINK_STAT_BIT_NAMES[i];
    }
    ldmx_log(debug) << "bad link Stat bits 0b" << bits << " -> [" << names
                    << " ] mismatched";
  }
  link.hamming_ = ((data[0] >> 26) & MASK<3>);
  link.is_empty_ = ((data[0] >> 25) & MASK<1>) == 1;
  link.adc_cm0_ = ((data[0] >> 15) & MASK<10>);
  link.adc_cm1_ = ((data[0] >> 5) & MASK<10>);
  ldmx_log(trace) << "    is_empty=" << link.is_empty_
                  << " CM0=" << link.adc_cm0_ << " CM1=" << link.adc_cm1_;
 
  if (link.is_empty_) {
    // F=1: single-word header, no channel map or channel data
    // E=1 means unmasked Stat error bits caused the suppression
    link.error_caused_empty_ = ((data[0] >> 4) & MASK<1>) == 1;
    ldmx_log(trace) << "is empty, E=" << link.error_caused_empty_;
    return 1;
  }
 
  if (data.size() < 2) {
    ldmx_log(debug) << "link sub-packet missing channel map";
    return 0;
  }
  ldmx_log(trace) << "chan map lower 32 " << Hex(data[1]);
  link.channel_map_ =
      ((data[0] & MASK<5>) << 32) | static_cast<uint64_t>(data[1]);
  ldmx_log(trace) << "is not empty, channel_map="
                  << std::bitset<37>(link.channel_map_);
 
  // two header words (including channel map)
  std::size_t length{2};
 
  int bits_left_in_current_word{32};
  for (std::size_t i_chan{0}; i_chan < 37; i_chan++) {
    // calib is the 19th channel in the sub-packet
    uint32_t* ch = &(link.calib_);
    if (i_chan < 18) {
      ch = &(link.channels_[i_chan]);
    } else if (i_chan > 18) {
      ch = &(link.channels_[i_chan - 1]);
    }
 
    if (passthrough_) {
      // channels are transparently copied from the link
      if (length >= data.size()) {
        ldmx_log(debug) << "pass through sub-packet ran out of words at ch "
                        << i_chan;
        return 0;
      }
      *ch = data[length];
      length++;
      continue;
    }
 
    // skip channels that are not passed
    if (((link.channel_map_ >> i_chan) & 1) == 0) {
      *ch = 0;
      continue;
    }
 
    if (length >= data.size()) {
      ldmx_log(debug) << "sub-packet ran out of words at ch " << i_chan;
      return 0;
    }
 
    // the code cannot span words, the format is byte aligned
    auto code{(data[length] >> (bits_left_in_current_word - 4)) & MASK<4>};
    // direct transcription of the table in Fig 20 of the ECOND Spec
    int nbits{32}, extra{0};
    bool has_adctm1{true}, has_toa{true};
    bool tc{false}, tp{false};
    if (code == 0b0000) {
      // TOA ZS
      has_toa = false;
      nbits = 24;
    } else if (code == 0b0001) {
      // ADC(-1) and TOA ZS
      has_adctm1 = false;
      has_toa = false;
      extra = 2;
      nbits = 16;
    } else if (code == 0b0010) {
      // No ZS or ...
      tp = true;
      has_toa = false;
      nbits = 24;
    } else if (code == 0b0011) {
      // ADC(-1) ZS
      has_adctm1 = false;
      nbits = 24;
    } else if ((code >> 2) == 0b01) {
      // full pass ZS in ADC mode
    } else if ((code >> 2) == 0b11) {
      // pass ZS because in TOT mode
      tc = true;
      tp = true;
    } else {
      // 0b10: known invalid
      ldmx_log(debug) << "ECOND eRx known invalid code "
                      << std::bitset<2>(code >> 2);
      tc = true;
    }
 
    // get the channel data from the current and perhaps the next word
    uint64_t chan_data{0};
    if (bits_left_in_current_word < nbits) {
      int runon_length = nbits - bits_left_in_current_word;
      if (length + 1 >= data.size()) {
        ldmx_log(debug) << "sub-packet ran out of words at ch " << i_chan;
        return 0;
      }
      chan_data = ((data[length] & ((1ul << bits_left_in_current_word) - 1ul))
                   << runon_length);
      length++;
      bits_left_in_current_word = 32;
      chan_data +=
          ((data[length] >> (bits_left_in_current_word - runon_length)) &
           ((1ul << runon_length) - 1ul));
      bits_left_in_current_word -= runon_length;
    } else {
      chan_data = ((data[length] >> (bits_left_in_current_word - nbits)) &
                   ((1ul << nbits) - 1ul));
      bits_left_in_current_word -= nbits;
    }
 
    // measurements that do not exist are negative
    int adc_tm1{-1}, toa{-1};
    chan_data >>= extra;
    if (has_toa) {
      toa = (chan_data & MASK<10>);
      chan_data >>= 10;
    }
    int main_sample = (chan_data & MASK<10>);
    chan_data >>= 10;
    if (has_adctm1) {
      adc_tm1 = (chan_data & MASK<10>);
    }
    ldmx_log(trace) << "    ch " << i_chan << " code=" << std::bitset<4>(code)
                    << " ADC(t-1)=" << adc_tm1 << " ADC/TOT=" << main_sample
                    << " TOA=" << toa;
 
    *ch = packSample(tc, tp, adc_tm1, main_sample, toa);
 
    if (bits_left_in_current_word == 0) {
      length++;
      bits_left_in_current_word = 32;
    }
  }
 
  // sub-packets are 32b-word-aligned
  if (bits_left_in_current_word < 32) {
    length++;
  }
 
  if (length > data.size()) {
    ldmx_log(debug) << "sub-packet length " << length << " exceeds "
                    << data.size() << " remaining words";
    return 0;
  }
 
  ldmx_log(trace) << "eRx final length " << length;
  return length;
}

References packing::ECONDLinkSubpacket::adc_cm0_, packing::ECONDLinkSubpacket::adc_cm1_, packing::ECONDLinkSubpacket::badStat(), packing::ECONDLinkSubpacket::calib_, packing::ECONDLinkSubpacket::channel_map_, packing::ECONDLinkSubpacket::channels_, packing::ECONDLinkSubpacket::error_caused_empty_, packing::ECONDLinkSubpacket::hamming_, packing::ECONDLinkSubpacket::is_empty_, passthrough_, and packing::ECONDLinkSubpacket::stat_.

Referenced by from().

Member Data Documentation

◆ bx_

uint32_t packing::ECONDEventPacket::bx_ {0}

bunch crossing

Definition at line 106 of file ECONDEventPacket.h.

106{0};

Referenced by from().

◆ corruption_

std::array<bool, N_CORRUPTION> packing::ECONDEventPacket::corruption_ {}

corruption flags indexed by Corruption

Definition at line 85 of file ECONDEventPacket.h.

85{};

Referenced by from(), and isCorrupt().

◆ crc8_

uint32_t packing::ECONDEventPacket::crc8_ {0}

transmitted 8b header CRC

Definition at line 116 of file ECONDEventPacket.h.

116{0};

Referenced by from().

◆ ebo_

uint32_t packing::ECONDEventPacket::ebo_ {0}

E/B/O: status of event/BX/orbit reconstruction.

Definition at line 98 of file ECONDEventPacket.h.

98{0};

Referenced by from().

◆ expected_

bool packing::ECONDEventPacket::expected_ {false}

E: HGCROC event header/trailer expected.

Definition at line 94 of file ECONDEventPacket.h.

94{false};

Referenced by from().

◆ hamming_

uint32_t packing::ECONDEventPacket::hamming_ {0}

6b Hamming code of the header

Definition at line 104 of file ECONDEventPacket.h.

104{0};

Referenced by from().

◆ header_marker_

uint32_t packing::ECONDEventPacket::header_marker_ {0}

9b header marker

Definition at line 88 of file ECONDEventPacket.h.

88{0};

Referenced by from().

◆ HEADER_MARKER_CMS

const uint32_t packing::ECONDEventPacket::HEADER_MARKER_CMS {0xf3 << 1}

static

Definition at line 149 of file ECONDEventPacket.h.

149{0xf3 << 1};

◆ HEADER_MARKER_SPEC

const uint32_t packing::ECONDEventPacket::HEADER_MARKER_SPEC {0xaa << 1}

static

spec default and common CMS header markers (8b marker + 0)

Definition at line 148 of file ECONDEventPacket.h.

148{0xaa << 1};

Referenced by from().

◆ ht_

uint32_t packing::ECONDEventPacket::ht_ {0}

H/T: status of HGCROC header/trailer reconstruction.

Definition at line 96 of file ECONDEventPacket.h.

96{0};

Referenced by from().

◆ l1a_

uint32_t packing::ECONDEventPacket::l1a_ {0}

6b L1A (event) number

Definition at line 108 of file ECONDEventPacket.h.

108{0};

Referenced by from().

◆ links_

std::vector<ECONDLinkSubpacket> packing::ECONDEventPacket::links_

storage of unpacked link data

This is very space in-efficient since we store zero words for any channel or measurement that was zero suppressed.

Definition at line 124 of file ECONDEventPacket.h.

Referenced by from().

◆ match_

bool packing::ECONDEventPacket::match_ {false}

M: transmitted E/B/O matches the L1A FIFO.

Definition at line 100 of file ECONDEventPacket.h.

100{false};

Referenced by from().

◆ orbit_

uint32_t packing::ECONDEventPacket::orbit_ {0}

3b orbit number

Definition at line 110 of file ECONDEventPacket.h.

110{0};

Referenced by from().

◆ passthrough_

bool packing::ECONDEventPacket::passthrough_ {false}

P: pass through mode.

Definition at line 92 of file ECONDEventPacket.h.

92{false};

Referenced by from(), and unpackLinkSubpacket().

◆ payload_length_

uint32_t packing::ECONDEventPacket::payload_length_ {0}

payload length in 32b words (not including the two header words)

Definition at line 90 of file ECONDEventPacket.h.

90{0};

Referenced by from(), and isEmpty().

◆ reset_request_

uint32_t packing::ECONDEventPacket::reset_request_ {0}

RR: reset request.

Definition at line 114 of file ECONDEventPacket.h.

114{0};

Referenced by from().

◆ subpacket_error_

bool packing::ECONDEventPacket::subpacket_error_ {false}

S: error in a link sub-packet.

Definition at line 112 of file ECONDEventPacket.h.

112{false};

Referenced by from().

◆ truncated_

bool packing::ECONDEventPacket::truncated_ {false}

T: packet truncated for buffer overflow.

Definition at line 102 of file ECONDEventPacket.h.

102{false};

Referenced by from().

The documentation for this class was generated from the following files:

Packing/include/Packing/ECONDEventPacket.h
Packing/src/Packing/ECONDEventPacket.cxx

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Private Member Functions

Detailed Description

Member Enumeration Documentation

◆ Corruption

Constructor & Destructor Documentation

◆ ECONDEventPacket()

Member Function Documentation

◆ from()

◆ isCorrupt()

◆ isEmpty()

◆ unpackLinkSubpacket()

Member Data Documentation

◆ bx_

◆ corruption_

◆ crc8_

◆ ebo_

◆ expected_

◆ hamming_

◆ header_marker_

◆ HEADER_MARKER_CMS

◆ HEADER_MARKER_SPEC

◆ ht_

◆ l1a_

◆ links_

◆ match_

◆ orbit_

◆ passthrough_

◆ payload_length_

◆ reset_request_

◆ subpacket_error_

◆ truncated_