Add FPGA-based test application for realtime predecoder

[wsttiger]

Summary

Add FPGA RDMA transport for the AI predecoder + PyMatching pipeline. Syndrome data arrives from a Hololink FPGA via RoCE v2, passes through TensorRT inference (AI predecoder), then PyMatching MWPM decoding, all orchestrated by realtime_pipeline.

Changes

New: FPGA predecoder bridge (hololink_predecoder_bridge.cpp)

• Creates a Hololink GpuRoceTransceiver (DOCA GPU-RoCE) and feeds its ring buffer into realtime_pipeline via the external_ringbuffer path
• Runs 8 TRT predecoder workers + 16 PyMatching decode threads
• Supports --data-dir for ground-truth correctness verification against observables.bin
• Logs per-shot diagnostic output confirming RDMA receipt, TRT inference result, and PyMatching decode

New: Orchestration script (hololink_predecoder_test.sh)

• 2-process FPGA mode: bridge + hololink_fpga_syndrome_playback
• 3-process emulated mode: emulator + bridge + playback
• Converts binary detectors.bin to the text format the playback tool expects
• Config-aware defaults for page size, num shots, and BRAM constraints

Fix: realtime_pipeline.cu external ring buffer consumer

• The consumer_loop gated slot processing on slot_occupied[], which is only set by the software ring_buffer_injector. With an FPGA-sourced external ring buffer, slots were silently skipped and no requests ever completed. Skip the slot_occupied and drain checks when external_ring_ is true.

Refactor: Consolidate shared predecoder code

• Extract ~350 lines of duplicated types (PipelineConfig, DecoderContext, PreLaunchCopyCtx, WorkerCtx, PyMatchQueue, TestData, SparseCSR, loaders) into predecoder_pipeline_common.{h,cpp}
• Move both drivers and the orchestration script into libs/qec/unittests/realtime/
• test_realtime_predecoder_w_pymatching.cpp is a git mv from libs/qec/lib/realtime/ with the shared code removed

Test results

Software benchmark (d13_r104, 20s, 104 us injection rate):

Metric	Value
Submitted / Completed	192,309 / 192,309
Throughput	9,610 req/s
Mean latency	370 us (p50=332, p99=1,204)
PyMatching decode	218 us avg
Syndrome reduction	98.3%
Pipeline LER	0.0020 (384 / 192,309)
Predecoder-only LER	0.3980

FPGA bridge (d13_r104, 1 shot via real Hololink FPGA on GB200):

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[bmhowe23]

/ok to test 87a6872

[bmhowe23]

I submitted the regular per-PR CI plus

• https://github.com/NVIDIA/cudaqx/actions/runs/24115254143 (All libs (Release))
• https://github.com/NVIDIA/cudaqx/actions/runs/24115823050 (Build wheels)

[bmhowe23]

The changes to the core part of the library some pretty minimal and low-risk, so this LGTM.