update econd-decoding to handle header/trailer

[tomeichlersmith]

The daq software inserts one more header defining the packet length, econ ID, and sample index. The decoding should be able to handle this extra header.

Update:

• first pass using SoftWrapped* in econd decoding update #249
• drop SoftWrapped* and instead update MultiSample* (started on in 246-update-econ-decoding-again)
• support live decoding by updating the daq run consumers to be templated over the different event packets (started on in 246-econd-live-decoding) work continued level_pedestals now has its daq format set by DAQ->SETTINGS->FORMAT #252
• update SW-emulation of FW headers/trailers in TargetFiberless and HcalBackplaneZCU (started on in 246-update-econ-decoding-again)

[tomeichlersmith]

This part of the decoding already does the header that the sw currently inserts

pflib/src/pflib/packing/MultiSampleECONDEventPacket.cxx

Lines 40 to 87 in 7a7d3d6

	/**
	* The software emulation adds another header before the ECOND packet,
	* which looks like
	*
	* 4b flag | 12b ECON ID | L | 3b il1a | I | 11b length
	*
	* - flag is hardcoded to 0b0001 right now in software
	* - ECOND ID is what it was configured in the software to be
	* - L signals if this is the last sample (1) or not (0)
	* - il1a is the index of the sample relative to this event
	* - I signals if this is the sample of interest (1) or not (0)
	* - length is the total length of this link subpacket including this header
	* word
	*/
	uint32_t link_len = (data[offset] & mask<11>);
	uint32_t il1a = (data[offset] >> 13) & mask<3>;
	uint32_t econ_id = ((data[offset] >> 16) & mask<12>);
	// uint32_t head_flag = (data[offset] >> 28);
	bool is_soi = (((data[offset] >> 12) & mask<1>) == 1);
	bool is_last = (((data[offset] >> 15) & mask<1>) == 1);
	// other flags about SOI or last sample
	pflib_log(trace) << hex(data[offset])
	<< " -> link_len, il1a, econ_id, is_soi, is_last = "
	<< link_len << ", " << il1a << ", " << econ_id << ", "
	<< is_soi << ", " << is_last;
	if (i_sample != il1a) {
	pflib_log(warn) << "mismatch between transmitted index and unpacking "
	"index for sample "
	<< i_sample << " != " << il1a;
	}
	if (is_soi) {
	i_soi = i_sample;
	}
	samples.emplace_back(n_links_);
	samples.back().from(data.subspan(offset + 1, link_len - 1));
	offset += link_len;
	if (is_last) {
	pflib_log(trace) << "Last sample packet found, leaving loop at offset = "
	<< offset << " (data.size() = " << data.size() << ")";
	break;
	}
	i_sample++;
	}

I'm going to collect a short pedestal run today and then start working on updating the decoding. Not sure right now if MultiSampleECONDEventPacket is close enough or if I'll want to factor out this extra header deduction and put it somewhere else. I want to keep ECONDEventPacket the way that it is because it represents the packets output by the ECOND as documented in the manual and is well tested. Any extra headers/trailers we insert in our firmware/software should be put somewhere else in order to reflect this separation in origin.

[tomeichlersmith]

Got a pedestal run done and it does indeed look like pedestals.

tom@appa:~/code/ldmx/hgcroc/pflib$ just hexdump -n 60 econd-pedestal-20251112-154219.raw 
hexdump -v -e '1/4 "%08x" "\n"' -n 60 econd-pedestal-20251112-154219.raw
3ffc1051
f313f02a
00e30055
e045801f
ffffffff
0c732400
0a329000
0a329400
0b42dc00
0d735c00
0cf34400
0bf2fc00
0db37400
0d134c00
0c231400

Confirmed that current econd-decoder never finds the right signal word and doesn't unpack anything:

denv ./build/econd-decoder 1 econd-pedestal-20251112-154219.raw
(2025-11-12 15:46:39) [econd-decoder]  warn: The ECOND decoding is not well tested. Inspect the results carefully and please contribute!
(2025-11-12 15:46:39) [econd-decoder]  info: popping 0 event from stream
cat econd-pedestal-20251112-154219.csv 
i_link,bx,event,orbit,channel,Tp,Tc,adc_tm1,adc,tot,toa

[tomeichlersmith]

#249 did the majority of this update

I need to follow up and change TargetFiberless::read_event to insert the same header that HcalBackplaneZCUTarget::read_event is inserting since the backplane one is doing what the firmware is actually written to do. Then I can change MultiSample* to hold SoftWrapped* and maybe rename SoftWrapped* since it is not expected to only be software.

[tomeichlersmith]

Just talked with Jeremy - instead of having a "last sample" bit in the header the software/firmware is adding to the ECOND packet, we are going to have a special "trailer word" that marks the end of the packet. This will make the firmware easier to write and is pretty simple to implement on the software decoding side (just consume Wrapped* ECOND packets until the special trailer word is encountered).