docs: add design document for rcdaq JANA2 event source - #2623
Draft
wdconinc wants to merge 8 commits into
Draft
Conversation
Describes the architecture for a new JEventSourceRCDAQ plugin that reads rcdaq binary ONCS/PRDF files and exposes detector data as podio collections inside JANA events for EICrecon. Key design points covered: - rcdaq binary format (buffer/event/sub-event structure) - Eager decoding (Option A) vs lazy decoding via podio::FrameDataType (Option B) - RCDAQFrameData satisfying the podio::FrameDataType concept for on-demand sub-event decoding - RCDAQDecoder pure virtual interface for per-sub-event-ID decoders - RCDAQFileReader for binary file iteration - JEventSourceRCDAQ JANA2 event source - CMake integration with optional rcdaq dependency - Mermaid diagrams for component relations and sequence flows - Open questions for design discussion Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
github-actions
Bot
added
the
topic: documentation
Implements a JANA2 event source that reads rcdaq ONCS-format binary
data files and exposes their contents as JANA events for use in the
EICrecon reconstruction pipeline.
New files:
- src/services/io/rcdaq/RCDAQSubevent.h
Plain struct holding raw int32 payload + header metadata for one
sub-event record. Inserted into the JEvent under a tag equal to
the decimal sub-event ID; downstream factories decode it into
EDM4hep collections.
- src/services/io/rcdaq/RCDAQFileReader.{h,cc}
Sequential reader for uncompressed ONCS-format rcdaq files.
Reads 8 kB-aligned buffer blocks, iterates events by evt_length,
iterates sub-events by sub_length. LZO/GZ compressed buffers are
detected and an exception is thrown. BEGIN/END run records update
the stored run number without being emitted.
- src/services/io/rcdaq/JEventSourceRCDAQ.{h,cc}
JANA2 JEventSource subclass. Open() opens the file via
RCDAQFileReader; Emit() reads the next DATA event, sets run/event
numbers, and inserts one RCDAQSubevent* per sub-event.
CheckOpenable() returns 0.9 for .prdf / .evt / .rcdaq files.
- src/services/io/rcdaq/rcdaq.cc
Plugin entry point; registers JEventSourceGeneratorT<JEventSourceRCDAQ>.
- src/services/io/rcdaq/CMakeLists.txt
Optional plugin target. Uses find_path() to locate the rcdaq
format headers (EvtStructures.h etc.); silently skips the plugin
if they are not found. Point cmake to them via
-Drcdaq_INCLUDE_DIR=<path>.
Modified:
- src/services/CMakeLists.txt: add_subdirectory(io/rcdaq)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a new 'Runtime Source Selection' section explaining: - Automatic selection via CheckOpenable scores (RCDAQ 0.9 for .prdf/.evt/.rcdaq, PODIO 0.03 for .root with podio_metadata): no ambiguity since extensions are disjoint - Explicit override via JANA's built-in event_source_type parameter Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…g scheme
RCDAQDecoder::decode() now receives the full sub-event header context:
decode(int16_t sub_type, int16_t sub_decoding,
const int32_t* data, int nwords)
This allows decoder implementers to:
- Validate the expected sub_decoding constant (e.g. IDDCFEM=51)
- Warn or skip on unexpected sub_type values
- Support multi-mode devices in the future
RCDAQFrameData::getCollectionBuffers() forwards sub_type and sub_decoding
from the stored RCDAQSubevent struct.
Also adds a new 'Data Addressing and Decoder Mapping' section to the design
document, covering:
- The three-field (sub_id, sub_type, sub_decoding) sub-event address
- sub_decoding constant table from SubevtConstants.h
- Design rationale for keying the decoder map by sub_id only
- Concrete ID4EVT → edm4hep::RawCalorimeterHit example
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
New test suite src/tests/rcdaq_test/ (Catch2, conditionally built when
rcdaq_library target is available):
rcdaq_file_reader_parses_BEGRUNEVENT_and_DATAEVENT:
Builds a 8192-byte synthetic ONCS binary in memory with one BEGRUNEVENT
followed by one DATAEVENT carrying a two-word ID4EVT sub-event.
Verifies run_number, evt_sequence, sub_id, sub_type, sub_decoding and
payload words are parsed correctly.
rcdaq_file_reader_reports_EOF_on_empty_file:
Passes an empty file; nextEvent() must return false.
rcdaq_frame_data_getAvailableCollections_lists_decoder_collection:
Constructs RCDAQFrameData with a SpyDecoder; verifies that
getAvailableCollections() returns exactly the decoder's collection name.
rcdaq_frame_data_getCollectionBuffers_calls_decode_with_correct_args:
Verifies that getCollectionBuffers() returns nullopt for unknown names
without invoking the decoder, and that for a known name it calls
decode() with the correct sub_type, sub_decoding and nwords values.
rcdaq_frame_data_getParameters_contains_run_and_event_numbers:
Verifies that getParameters() returns a GenericParameters object with
the correct 'run_number' and 'event_sequence' int values.
Also changes plugin_add() to WITH_STATIC_LIBRARY so that rcdaq_library
is available as a linkable target for the tests (the .so plugin still
exists unchanged).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
- RCDAQSubevent: widen sub_id to int32_t; add packet_id field (packet_id = hdrinfo & 0xFFFF for PRDF, = sub_id for ONCS) - RCDAQFileReader: detect PRDF vs ONCS from buffer marker; store Format enum; parse 6-word PRDF packet header using packetdata_ptr from SubevtStructures.h - RCDAQDecoder: rename subeventID() -> packetID() with int32_t return type to match packet_id routing key - RCDAQFrameData: change DecoderMap key int16_t -> int32_t; look up decoders by packet_id instead of sub_id - JEventSourceRCDAQ: change decoder map key to int32_t; add rcdaq:dump parameter (default false) that logs raw sub-event packet headers + first 8 payload words per event without invoking any decoder - Tests: update SpyDecoder to use packetID()/int32_t; add PRDF integration test that reads first_100_run375_KCU0.evt if present; pass SRCDIR to test binary via cmake define Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…2636) This PR applies the include-what-you-use fixes as suggested by https://github.com/eic/EICrecon/actions/runs/24781191373. Please merge this PR into the branch `rcdaq-event-source-design` to resolve failures in PR #2623. Auto-generated by [create-pull-request][1] [1]: https://github.com/peter-evans/create-pull-request Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Briefly, what does this PR introduce? Please link to any relevant presentations or discussions.
Describes the architecture for a new JEventSourceRCDAQ plugin that reads rcdaq binary ONCS/PRDF files and exposes detector data as podio collections inside JANA events for EICrecon.
Key design points covered:
What is the urgency of this PR?
What kind of change does this PR introduce?
Please check if any of the following apply