Batcher Protocol

The batcher protocol packs multiple logical records into a single stream frame for transport efficiency. Rogue provides parser and transform utilities for both supported wire formats:

In many systems, batching is done in FPGA firmware before data reaches software. The SURF firmware library (https://github.com/slaclab/surf) includes batcher modules that are commonly used for this purpose. The primary motivation is to reduce software/driver overhead from receiving many small frames by combining them into fewer larger transfers.

Rogue batcher support can then be used to unbatch these frames either:

  • inline while receiving live stream data, or

  • later when reading recorded stream files for analysis/replay.

How the classes fit together

The classes in rogue::protocols::batcher are composable:

  • CoreV1 / CoreV2 parse one super-frame and expose record metadata.

  • Data represents one parsed record payload plus routing/user metadata.

  • SplitterV1 / SplitterV2 use Core + Data to emit one output frame per record (true unbatching).

  • InverterV1 / InverterV2 use Core metadata to rewrite framing in-place and forward one transformed frame (single-frame reformat, not batching or unbatching).

Choose V1 or V2 classes to match the firmware protocol version.

Usage examples

Python splitter chain (v2)

import rogue.protocols.batcher
import rogue.interfaces.stream

src = MyBatchedFrameSource()                   # Produces batcher-v2 frames
split = rogue.protocols.batcher.SplitterV2()   # Super-frame -> per-record frames
filt = rogue.interfaces.stream.Filter(True, 3) # Keep channel/dest 3
dst = MyRecordSink()

src >> split >> filt >> dst

Python inverter chain (v1)

import rogue.protocols.batcher

src = MyBatchedFrameSource()                  # Produces batcher-v1 frames
inv = rogue.protocols.batcher.InverterV1()    # In-place framing transform
dst = MyTransformedFrameSink()

src >> inv >> dst

C++ splitter chain (v1)

#include <rogue/protocols/batcher/SplitterV1.h>

auto split = rogue::protocols::batcher::SplitterV1::create();
auto src   = MyBatchedFrameSource::create();
auto dst   = MyRecordSink::create();

*(*src >> split) >> dst;

C++ API details for batcher protocol classes are documented in Batcher Protocol Class Descriptions.

Batcher Protocol