hcal::HcalRawDecoder Class Reference

Public Member Functions
	HcalRawDecoder (const std::string &name, framework::Process &process)
void	configure (framework::config::Parameters &) override
	Callback for the EventProcessor to configure itself from the given set of parameters.
void	beforeNewRun (ldmx::RunHeader &rh) override
	add detector name if we are reading from file
void	produce (framework::Event &event) override
	use read function to decode data, then translate EIDs into DetIDs
Public Member Functions inherited from framework::Producer
	Producer (const std::string &name, Process &process)
	Class constructor.
virtual void	process (Event &event) final
	Processing an event for a Producer is calling produce.
Public Member Functions inherited from framework::EventProcessor
	DECLARE_FACTORY (EventProcessor, EventProcessor *, const std::string &, Process &)
	declare that we have a factory for this class
	EventProcessor (const std::string &name, Process &process)
	Class constructor.
virtual	~EventProcessor ()=default
	Class destructor.
virtual void	onNewRun (const ldmx::RunHeader &run_header)
	Callback for the EventProcessor to take any necessary action when the run being processed changes.
virtual void	onFileOpen (EventFile &event_file)
	Callback for the EventProcessor to take any necessary action when a new event input ROOT file is opened.
virtual void	onFileClose (EventFile &event_file)
	Callback for the EventProcessor to take any necessary action when a event input ROOT file is closed.
virtual void	onProcessStart ()
	Callback for the EventProcessor to take any necessary action when the processing of events starts, such as creating histograms.
virtual void	onProcessEnd ()
	Callback for the EventProcessor to take any necessary action when the processing of events finishes, such as calculating job-summary quantities.
template<class T >
const T &	getCondition (const std::string &condition_name)
	Access a conditions object for the current event.
TDirectory *	getHistoDirectory ()
	Access/create a directory in the histogram file for this event processor to create histograms and analysis tuples.
void	setStorageHint (framework::StorageControl::Hint hint)
	Mark the current event as having the given storage control hint from this module_.
void	setStorageHint (framework::StorageControl::Hint hint, const std::string &purposeString)
	Mark the current event as having the given storage control hint from this module and the given purpose string.
int	getLogFrequency () const
	Get the current logging frequency from the process.
int	getRunNumber () const
	Get the run number from the process.
std::string	getName () const
	Get the processor name.
void	createHistograms (const std::vector< framework::config::Parameters > &histos)
	Internal function which is used to create histograms passed from the python configuration @parma histos vector of Parameters that configure histograms to create.

Private Member Functions
template<typename ReaderType >
std::map< ldmx::HcalElectronicsID, std::vector< ldmx::HgcrocDigiCollection::Sample > >	read (ReaderType &reader, PolarfireEventHeader &eh)
	Assume input reader behaves like a binary data input stream where we can "pop" individual 32-bit words with operator>> and we can check if the reader is done using operator bool()

Private Attributes
std::string	input_file_
	input file of encoded data
std::vector< std::string >	input_names_
	input object of encoded data
std::string	input_pass_
	input pass of creating encoded data
std::string	output_name_
	output object to put onto event bus
std::string	detector_name_
	the detector name if we are reading from a file
int	roc_version_
	version of HGC ROC we are decoding
bool	translate_eid_
	are get translating electronic IDs?
bool	read_from_file_
	is the input_name a file or an event object
packing::utility::Reader	file_reader_
	the file reader (if we are doing that)

Additional Inherited Members
Protected Member Functions inherited from framework::EventProcessor
void	abortEvent ()
	Abort the event immediately.
Protected Attributes inherited from framework::EventProcessor
HistogramPool	histograms_
	helper object for making and filling histograms
NtupleManager &	ntuple_ {NtupleManager::getInstance()}
	Manager for any ntuples.
logging::logger	the_log_
	The logger for this EventProcessor.

Detailed Description

Definition at line 53 of file HcalRawDecoder.h.

Constructor & Destructor Documentation

HcalRawDecoder()

hcal::HcalRawDecoder::HcalRawDecoder ( const std::string & name, framework::Process & process )

inline

Definition at line 55 of file HcalRawDecoder.h.

      : framework::Producer(name, process) {}

Member Function Documentation

beforeNewRun()

void hcal::HcalRawDecoder::beforeNewRun ( ldmx::RunHeader & rh )

overridevirtual

add detector name if we are reading from file

Reimplemented from framework::EventProcessor.

Definition at line 94 of file HcalRawDecoder.cxx.

                                                   {
  // if we are reading from a file, we need to provide the detector name
  if (read_from_file_) {
    rh.setDetectorName(detector_name_);
  }
}

References detector_name_, read_from_file_, and ldmx::RunHeader::setDetectorName().

configure()

void hcal::HcalRawDecoder::configure ( framework::config::Parameters & parameters )

overridevirtual

Callback for the EventProcessor to configure itself from the given set of parameters.

The parameters a processor has access to are the member variables of the python class in the sequence that has class_name equal to the EventProcessor class name.

For an example, look at MyProcessor.

Parameters

parameters

Parameters for configuration.

Reimplemented from framework::EventProcessor.

Definition at line 80 of file HcalRawDecoder.cxx.

                                                            {
  input_file_ = ps.get<std::string>("input_file");
  input_names_ = ps.get<std::vector<std::string>>("input_names", {});
  input_pass_ = ps.get<std::string>("input_pass");
  output_name_ = ps.get<std::string>("output_name");
  roc_version_ = ps.get<int>("roc_version");
  translate_eid_ = ps.get<bool>("translate_eid");
  read_from_file_ = ps.get<bool>("read_from_file");
  detector_name_ = ps.get<std::string>("detector_name");
  if (read_from_file_) {
    file_reader_.open(input_file_);
  }
}

References detector_name_, file_reader_, framework::config::Parameters::get(), input_file_, input_names_, input_pass_, packing::utility::Reader::open(), output_name_, read_from_file_, roc_version_, and translate_eid_.

produce()

void hcal::HcalRawDecoder::produce ( framework::Event & event )

overridevirtual

use read function to decode data, then translate EIDs into DetIDs

Translation

Now the HgcrocDigiCollection::Sample class handles the unpacking of individual samples; however, we still need to translate electronic IDs into detector IDs.

DO NOTHING skip hits_ where the EID aren't in the detector mapping no zero supp during test beam on the front-end, so channels that aren't connected to anything are still being readout.

no EID translation, just add the digis to the digi collection with their raw electronic ID TODO: remove this, we shouldn't be able to get past the decoding stage without translating the EID into a detector ID to avoid confusion in recon

Implements framework::Producer.

Definition at line 101 of file HcalRawDecoder.cxx.

                                                  {
  std::map<ldmx::HcalElectronicsID,
           std::vector<ldmx::HgcrocDigiCollection::Sample>>
      eid_to_samples;
  PolarfireEventHeader eh;
  if (read_from_file_) {
    if (!file_reader_ or file_reader_.eof()) return;
    eid_to_samples = this->read(file_reader_, eh);
  } else {
    for (const auto& name : input_names_) {
      hcal::utility::Reader bus_reader(
          event.getCollection<uint8_t>(name, input_pass_));
      auto single_pf_samples = this->read(bus_reader, eh);
      for (const auto& [id, samples] : single_pf_samples) {
        eid_to_samples[id] = samples;
      }
    }
  }
 
  eh.board(event, output_name_);
 
  ldmx::HgcrocDigiCollection digis;
  // assume all channels have same number of samples
  digis.setNumSamplesPerDigi(eid_to_samples.begin()->second.size());
  digis.setSampleOfInterestIndex(0);  // TODO configurable
  digis.setVersion(roc_version_);
  if (translate_eid_) {
#ifdef DEBUG
    std::cout << "Translating EIDs into DetIDs. Printing skipped EIDs..."
              << std::endl;
#endif
    auto detmap{
        getCondition<HcalDetectorMap>(HcalDetectorMap::CONDITIONS_OBJECT_NAME)};
    for (auto const& [eid, digi] : eid_to_samples) {
      // The electronics map returns an empty ID of the correct
      // type when the electronics ID is not found.
      //  need to check if the electronics ID exists
      //  TODO: do we want to end processing if this happens?
      if (detmap.exists(eid)) {
        uint32_t did_raw = detmap.get(eid).raw();
        digis.addDigi(did_raw, digi);
      } else {
#ifdef DEBUG
        std::cout << "EID(" << eid.fiber() << "," << eid.elink() << ","
                  << eid.channel() << ") ";
        for (auto& s : digi) std::cout << debug::hex(s.raw()) << " ";
        std::cout << std::endl;
#endif
      }
    }
  } else {
    for (auto const& [eid, digi] : eid_to_samples) {
      digis.addDigi(eid.raw(), digi);
    }
  }
 
#ifdef DEBUG
  std::cout << "adding " << digis.getNumDigis() << " digis each with "
            << digis.getNumSamplesPerDigi() << " samples to event bus"
            << std::endl;
#endif
  event.add(output_name_, digis);
  return;
}  // produce

References ldmx::HgcrocDigiCollection::addDigi(), hcal::PolarfireEventHeader::board(), hcal::HcalDetectorMap::CONDITIONS_OBJECT_NAME, packing::utility::Reader::eof(), file_reader_, framework::Event::getCollection(), framework::EventProcessor::getCondition(), ldmx::HgcrocDigiCollection::getNumDigis(), ldmx::HgcrocDigiCollection::getNumSamplesPerDigi(), input_names_, input_pass_, output_name_, read(), read_from_file_, roc_version_, ldmx::HgcrocDigiCollection::setNumSamplesPerDigi(), ldmx::HgcrocDigiCollection::setSampleOfInterestIndex(), ldmx::HgcrocDigiCollection::setVersion(), and translate_eid_.

read()

template<typename ReaderType >

std::map< ldmx::HcalElectronicsID, std::vector< ldmx::HgcrocDigiCollection::Sample > > hcal::HcalRawDecoder::read ( ReaderType & reader, PolarfireEventHeader & eh )

inlineprivate

Assume input reader behaves like a binary data input stream where we can "pop" individual 32-bit words with operator>> and we can check if the reader is done using operator bool()

Note: Contains quite a lot of debug details and variables that aren't actually used but should be kept around. Could possibly be cleaned up at some point but for now, best to leave alone

Static parameters depending on ROC version

words for reading and decoding

Decode event header

For the time being, the number of sample lengths is fixed to make the firmware for DMA readout simpler. This means we readout the leftover dummy words to move the pointer on the reader.

extended event header in version 2

Re-sort the data from grouped by bunch to by channel

The readout chip streams the data off of it, so it doesn't have time to re-group the signals across multiple bunches (samples) by their channel ID. We need to do that here.

Decode Bunch Header We have a few words of header material before the actual data. This header material is assumed to be encoded as in Table 3 of the DAQ specs.

<name> (bits)

VERSION (4) | FPGA_ID (8) | NLINKS (6) | 00 | LEN (12) BX ID (12) | RREQ (10) | OR (10) RID ok (1) | CRC ok (1) | LEN3 (6) | RID ok (1) | CRC ok (1) | LEN2 (6) | RID ok (1) | CRC ok (1) | LEN1 (6) | RID ok (1) | CRC ok (1) | LEN0 (6) ... other listing of links ...

Decode Each Link in Sequence Now we should be decoding each link serially where each link was encoded as in Table 4 of the DAQ specs

ROC_ID (16) | CRC ok (1) | 0 (7) | RO Map (8) RO Map (32)

If minimum length of 2 is not written for this link, assume it went down and skip

Special "Header" Word from ROC

version 3: 0101 | BXID (12) | RREQ (6) | OR (3) | HE (3) | 0101

version 2: 10101010 | BXID (12) | WADD (9) | 1010

Common Mode Channels 10 | 0000000000 | Common Mode ADC 0 (10) | Common Mode ADC 1 (10)

DAQ Channels

The HGC ROC has some odd behavior in terms of reading out the different channels.

• extra header word in row j = 0
• common mode channel in row (j) number 19 or 1 (depending on the version)

• calib channel in row j = 20 This introduces a special shift for the channel number to "align" with the range 0-35 per link.

  polarfire fpga = fpga readout roc = i_link / 2 // integer division channel = j - 1 - (j > common_mode_channel)*1 - (j > calib_channel)*1

Definition at line 77 of file HcalRawDecoder.h.

                                                     {
    static const unsigned int common_mode_channel = roc_version_ == 2 ? 19 : 1;
    static const unsigned int calib_channel = 20;
    static uint32_t head1, head2, w;
 
    // special header words not counted in event length
    do {
      reader >> head1;
    } while (head1 != 0xbeef2021 and head1 != 0xbeef2022);
 
    long int eventlen;
    long int i_event{0};
    /* whole event header word looks like
     *
     * VERSION (4) | FPGA ID (8) | NSAMPLES (4) | LEN (16)
     */
    reader >> head1;
    i_event++;
 
    eh.version_ = (head1 >> 28) & packing::utility::MASK<4>;
    eh.fpga_ = (head1 >> 20) & packing::utility::MASK<8>;
    eh.nsamples_ = (head1 >> 16) & packing::utility::MASK<4>;
    eventlen = head1 & packing::utility::MASK<16>;
    if (eh.version_ == 1u) {
      // eventlen is 32-bit words in event
      // do nothing here
    } else if (eh.version_ == 2u) {
      // eventlen is 64-bit words in event,
      // need to multiply by 2 to get actual 32-bit event length
      eventlen *= 2;
      // and subtract off the special header word above
      eventlen -= 1;
    } else {
      EXCEPTION_RAISE(
          "VersMis",
          "HcalRawDecoder only knows version 1 and 2 of DAQ format.");
    }
    // sample counters
    int n_words{0};
    std::vector<uint32_t> length_per_sample(eh.nsamples_, 0);
    for (uint32_t i_sample{0}; i_sample < eh.nsamples_; i_sample++) {
      if (i_sample % 2 == 0) {
        n_words++;
        reader >> w;
        i_event++;
      }
      uint32_t shift_in_word = 16 * (i_sample % 2);
      length_per_sample[i_sample] =
          (w >> shift_in_word) & packing::utility::MASK<12>;
    }
 
    if (eh.version_ == 2) {
      for (int i_word{n_words}; i_word < 8; i_word++) {
        reader >> head1;
        i_event++;
      }
 
      reader >> head1;
      i_event++;
      eh.spill_ = ((head1 >> 12) & 0xfff);
      eh.bunch_ = (head1 & 0xfff);
      reader >> head1;
      i_event++;
      eh.ticks_ = head1;
      reader >> head1;
      i_event++;
      eh.number_ = head1;
      reader >> head1;
      i_event++;
      eh.run_ = (head1 & 0xFFF);
      eh.dd_ = (head1 >> 23) & 0x1F;
      eh.mm_ = (head1 >> 28) & 0xF;
      eh.hh_ = (head1 >> 18) & 0x1F;
      eh.mm_ = (head1 >> 12) & 0x3F;
    }
 
    // fill map of **electronic** IDs to the digis that were read out
    std::map<ldmx::HcalElectronicsID,
             std::vector<ldmx::HgcrocDigiCollection::Sample>>
        eid_to_samples;
    std::size_t i_sample{0};
    while (i_event < eventlen) {
      reader >> head1 >> head2;
      i_event += 2;
      packing::utility::CRC fpga_crc;
      fpga_crc << head1;
 
      [[maybe_unused]] uint32_t hgcroc_version =
          (head1 >> 28) & packing::utility::MASK<4>;
      uint32_t fpga = (head1 >> 20) & packing::utility::MASK<8>;
      uint32_t nlinks = (head1 >> 14) & packing::utility::MASK<6>;
      [[maybe_unused]] uint32_t len = head1 & packing::utility::MASK<12>;
 
      fpga_crc << head2;
 
      [[maybe_unused]] uint32_t bx_id =
          (head2 >> 20) & packing::utility::MASK<12>;
      [[maybe_unused]] uint32_t rreq =
          (head2 >> 10) & packing::utility::MASK<10>;
      [[maybe_unused]] uint32_t orbit = head2 & packing::utility::MASK<10>;
 
      std::vector<uint32_t> length_per_link(nlinks, 0);
      for (uint32_t i_link{0}; i_link < nlinks; i_link++) {
        if (i_link % 4 == 0) {
          i_event++;
          reader >> w;
          fpga_crc << w;
        }
        uint32_t shift_in_word = 8 * (i_link % 4);
        [[maybe_unused]] bool rid_ok =
            ((w >> (shift_in_word + 7)) & packing::utility::MASK<1>) == 1;
        [[maybe_unused]] bool cdc_ok =
            ((w >> (shift_in_word + 6)) & packing::utility::MASK<1>) == 1;
        length_per_link[i_link] =
            (w >> shift_in_word) & packing::utility::MASK<6>;
      }
 
      eh.good_bxheader_.resize(nlinks);
      eh.good_trailer_.resize(nlinks);
      for (uint32_t i_link{0}; i_link < nlinks; i_link++) {
        if (length_per_link.at(i_link) < 2) {
          continue;
        }
        // move on from last word counting links or previous link
        packing::utility::CRC link_crc;
        i_event++;
        reader >> w;
        fpga_crc << w;
        link_crc << w;
        [[maybe_unused]] uint32_t roc_id =
            (w >> 16) & packing::utility::MASK<16>;
        [[maybe_unused]] bool crc_ok =
            ((w >> 15) & packing::utility::MASK<1>) == 1;
 
        // get readout map from the last 8 bits of this word
        // and the entire next word
        std::bitset<40> ro_map = w & packing::utility::MASK<8>;
        ro_map <<= 32;
        i_event++;
        reader >> w;
        fpga_crc << w;
        link_crc << w;
        ro_map |= w;
        // loop through channels on this link,
        //  since some channels may have been suppressed because of low
        //  amplitude the channel ID is not the same as the index it
        //  is listed in.
        int j{-1};
        for (uint32_t i_word{2}; i_word < length_per_link.at(i_link);
             i_word++) {
          // skip zero-suppressed channel IDs
          do {
            j++;
          } while (j < 40 and not ro_map.test(j));
 
          // next word is this channel
          i_event++;
          reader >> w;
          fpga_crc << w;
 
          if (j == 0) {
            link_crc << w;
            // v2
            eh.good_bxheader_[i_link] = ((w & 0xff000000) == 0xaa000000);
            // v3
            //
            // Shadows a previous declaration but is never used so renamed here
            [[maybe_unused]] uint32_t v3_bx_id =
                (w >> 16) & packing::utility::MASK<12>;
            [[maybe_unused]] uint32_t short_event =
                (w >> 10) & packing::utility::MASK<6>;
            [[maybe_unused]] uint32_t short_orbit =
                (w >> 7) & packing::utility::MASK<3>;
            [[maybe_unused]] uint32_t hamming_errs =
                (w >> 4) & packing::utility::MASK<3>;
          } else if (j == common_mode_channel) {
            link_crc << w;
          } else if (j == calib_channel) {
            // calib channel
            link_crc << w;
          } else if (j == 39) {
            // trailer on each link added by ROC
            // ROC v2 - IDLE word
            // ROC v3 - CRC checksum
            if (roc_version_ == 2) {
              bool good_idle = (w == 0xaccccccc);
              eh.good_trailer_[i_link] = good_idle;
            } else {
              bool good_crc = (link_crc.get() == w);
              eh.good_trailer_[i_link] = good_crc;
            }
            /*
            if (roc_version_ > 2 and link_crc.get() != w) {
              EXCEPTION_RAISE("BadCRC",
                              "Our calculated link checksum doesn't match the "
                              "one from raw data.");
            }
            */
          } else {
 
            link_crc << w;
            ldmx::HcalElectronicsID eid(fpga, i_link,
                                        j - 1 - 1 * (j > common_mode_channel) -
                                            1 * (j > calib_channel));
            // copy data into EID->sample map
            eid_to_samples[eid].emplace_back(w);
          }  // type of channel
        }  // loop over channels (j in Table 4)
      }  // loop over links
 
      // another CRC checksum from FPGA
      i_event++;
      reader >> w;
      [[maybe_unused]] uint32_t crc = w;
      /* TODO
       *  fix calculation of FPGA checksum
       *  I can't figure out why it isn't matching, but there
       *  is definitely a word here where the FPGA checksum would be.
      if (fpga_crc.get() != crc) {
        EXCEPTION_RAISE(
            "BadCRC",
            "Our calculated FPGA checksum doesn't match the one read in.");
      }
      */
      // padding to reach 64-bit boundary in version 2
      if (eh.version_ == 2u and length_per_sample.at(i_sample) % 2 == 1) {
        i_event++;
        reader >> head1;
      }
      i_sample++;
    }
 
    if (eh.version_ == 1u) {
      // special footer words
      reader >> head1 >> head2;
    }
 
    return eid_to_samples;
  }

References hcal::PolarfireEventHeader::bunch_, hcal::PolarfireEventHeader::dd_, hcal::PolarfireEventHeader::fpga_, packing::utility::CRC::get(), hcal::PolarfireEventHeader::good_bxheader_, hcal::PolarfireEventHeader::good_trailer_, hcal::PolarfireEventHeader::hh_, hcal::PolarfireEventHeader::mm_, hcal::PolarfireEventHeader::nsamples_, hcal::PolarfireEventHeader::number_, roc_version_, hcal::PolarfireEventHeader::run_, hcal::PolarfireEventHeader::spill_, hcal::PolarfireEventHeader::ticks_, and hcal::PolarfireEventHeader::version_.

Referenced by produce().

Member Data Documentation

detector_name_

std::string hcal::HcalRawDecoder::detector_name_

private

the detector name if we are reading from a file

Definition at line 403 of file HcalRawDecoder.h.

Referenced by beforeNewRun(), and configure().

file_reader_

packing::utility::Reader hcal::HcalRawDecoder::file_reader_

private

the file reader (if we are doing that)

Definition at line 413 of file HcalRawDecoder.h.

Referenced by configure(), and produce().

input_file_

std::string hcal::HcalRawDecoder::input_file_

private

input file of encoded data

Definition at line 395 of file HcalRawDecoder.h.

Referenced by configure().

input_names_

std::vector<std::string> hcal::HcalRawDecoder::input_names_

private

input object of encoded data

Definition at line 397 of file HcalRawDecoder.h.

Referenced by configure(), and produce().

input_pass_

std::string hcal::HcalRawDecoder::input_pass_

private

input pass of creating encoded data

Definition at line 399 of file HcalRawDecoder.h.

Referenced by configure(), and produce().

output_name_

std::string hcal::HcalRawDecoder::output_name_

private

output object to put onto event bus

Definition at line 401 of file HcalRawDecoder.h.

Referenced by configure(), and produce().

read_from_file_

bool hcal::HcalRawDecoder::read_from_file_

private

is the input_name a file or an event object

Definition at line 409 of file HcalRawDecoder.h.

Referenced by beforeNewRun(), configure(), and produce().

roc_version_

int hcal::HcalRawDecoder::roc_version_

private

version of HGC ROC we are decoding

Definition at line 405 of file HcalRawDecoder.h.

Referenced by configure(), produce(), and read().

translate_eid_

bool hcal::HcalRawDecoder::translate_eid_

private

are get translating electronic IDs?

Definition at line 407 of file HcalRawDecoder.h.

Referenced by configure(), and produce().

---

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

• Hcal/include/Hcal/HcalRawDecoder.h
• Hcal/src/Hcal/HcalRawDecoder.cxx