Skip to content

[QEC] Rename hololink: GPU-side transceiver software to gpu_roce/GpuRoceTransceiver, FPGA-facing to hsb - #754

Merged
cketcham2333 merged 8 commits into
NVIDIA:mainfrom
cketcham2333:hololink_rename
Aug 3, 2026
Merged

[QEC] Rename hololink: GPU-side transceiver software to gpu_roce/GpuRoceTransceiver, FPGA-facing to hsb#754
cketcham2333 merged 8 commits into
NVIDIA:mainfrom
cketcham2333:hololink_rename

Conversation

@cketcham2333

@cketcham2333 cketcham2333 commented Jul 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Companion to the cuda-quantum hololink_rename PR, which renames the realtime bridge's hololink_*() C API to gpu_roce_*() and the provider library to libcudaq-realtime-bridge-gpu-roce.so. This PR applies the same naming policy to everything cudaqx owns: "hololink" referring to the GPU-side transceiver software becomes gpu_roce/GpuRoceTransceiver; "hololink" referring to the HSB FPGA becomes hsb.

  • GPU-side transceiver software → gpu_roce / GpuRoceTransceiver
    • Provider config value "hololink" → "gpu_roce" (transport.device_graph.provider in YAML/C++/Python) and the default provider library string in DeviceGraphTransceiver.cpp
    • hololink_predecoder_bridge → gpu_roce_predecoder_bridge, hololink_qldpc_graph_decoder_bridge → gpu_roce_qldpc_graph_decoder_bridge (plus their test scripts); all hololink_*() call sites → gpu_roce_*()
    • kHololinkMonitorStartupGrace → kGpuRoceMonitorStartupGrace; kHsbWqeNum → kGpuRoceWqeNum (it mirrors the software transceiver's WQE_NUM, not an FPGA property)
  • FPGA-facing → hsb
    • hololink_fpga_syndrome_playback → hsb_fpga_syndrome_playback; its CLI flag --hololink <ip> → --hsb-ip <ip> (updated in all three consumer test scripts)
    • CMake: CUDAQX_QEC_ENABLE_HOLOLINK_TOOLS → CUDAQX_QEC_ENABLE_HSB_TOOLS; HOLOLINK_{CORE,COMMON}_LIB → HSB_{CORE,COMMON}_LIB; CUDAQ_REALTIME_BRIDGE_HOLOLINK_LIBRARY → CUDAQ_REALTIME_BRIDGE_GPU_ROCE_LIBRARY
  • Docs/CI: realtime_relay_bp.rst, realtime_predecoder_fpga.rst, build_qec.sh, and the realtime design docs updated to match; the FPGA backpressure-model prose now says hsb.

Names owned by the external holoscan-sensor-bridge repo are unchanged (hololink:: namespace, <hololink/...> headers, hololink_core, -DHOLOLINK_BUILD_*, HOLOSCAN_SENSOR_BRIDGE_{SOURCE,BUILD}_DIR, src/hololink/ paths).

@cketcham2333
Rename hololink: GPU-side transceiver software -> gpu_roce/GpuRoceTra…
ae76f54 
…nsceiver, FPGA-facing -> hsb

Companion to the cuda-quantum hololink_rename branch (which renames the
hololink_*() bridge C API to gpu_roce_*() and the provider .so to
libcudaq-realtime-bridge-gpu-roce.so). cudaqx-owned renames:

- GPU-side transceiver software -> gpu_roce / GpuRoceTransceiver:
  * Provider config value "hololink" -> "gpu_roce"
    (transport.device_graph.provider in YAML/C++/Python; hard rename,
    no alias) and the default provider library string in
    DeviceGraphTransceiver.cpp
  * hololink_predecoder_bridge -> gpu_roce_predecoder_bridge,
    hololink_qldpc_graph_decoder_bridge -> gpu_roce_qldpc_graph_decoder_bridge
    (+ their test scripts), all hololink_*() call sites -> gpu_roce_*()
  * kHololinkMonitorStartupGrace -> kGpuRoceMonitorStartupGrace,
    kHsbWqeNum -> kGpuRoceWqeNum (it mirrors the software transceiver's
    WQE_NUM, not an FPGA property)
- FPGA-facing -> hsb:
  * hololink_fpga_syndrome_playback -> hsb_fpga_syndrome_playback;
    its CLI flag --hololink <ip> -> --hsb-ip <ip> (updated in all three
    consumer test scripts)
  * CUDAQX_QEC_ENABLE_HOLOLINK_TOOLS -> CUDAQX_QEC_ENABLE_HSB_TOOLS;
    HOLOLINK_{CORE,COMMON}_LIB -> HSB_{CORE,COMMON}_LIB;
    CUDAQ_REALTIME_BRIDGE_HOLOLINK_LIBRARY ->
    CUDAQ_REALTIME_BRIDGE_GPU_ROCE_LIBRARY (finds
    cudaq-realtime-bridge-gpu-roce)
- Docs (realtime_relay_bp.rst, realtime_predecoder_fpga.rst), CI
  (build_qec.sh), and design docs updated to match; the FPGA
  backpressure-model prose now says hsb.

External holoscan-sensor-bridge names are unchanged (hololink::
namespace, <hololink/...> headers, hololink_core, -DHOLOLINK_BUILD_*,
HOLOSCAN_SENSOR_BRIDGE_{SOURCE,BUILD}_DIR, src/hololink/ paths).

BREAKING: YAML/Python configs using provider "hololink" must switch to
"gpu_roce". Requires the cuda-quantum hololink_rename branch; neither
should merge alone.

.cudaq_version temporarily pins cketcham2333/cuda-quantum @ 994b8f03
(the hololink_rename commit) so CI builds against the renamed realtime
API; re-pin to an NVIDIA/cuda-quantum SHA once that side merges.

Signed-off-by: Chuck Ketcham <cketcham@nvidia.com>
@cketcham2333 cketcham2333 changed the title [Realtime] Rename hololink: GPU-side transceiver software to gpu_roce/GpuRoceTransceiver, FPGA-facing to hsb [QEC] Rename hololink: GPU-side transceiver software to gpu_roce/GpuRoceTransceiver, FPGA-facing to hsb Jul 28, 2026
@cketcham2333
clang format
e4099b4 
Signed-off-by: Chuck Ketcham <cketcham@nvidia.com>
@cketcham2333
Re-pin .cudaq_version to the cuda-quantum hololink_rename head
67f69a9 
Advances the pin from 994b8f03 to 61130dfb so CI builds the actual head
of the paired cuda-quantum PR, which now also carries its formatting
fixes (clang-format reflows, markdownlint rewraps, and the relabeled
base64-embedded 3-kernel diagram).

Still a temporary fork pin (cketcham2333/cuda-quantum); re-point to an
NVIDIA/cuda-quantum SHA once that PR merges, before merging this one.

Signed-off-by: Chuck Ketcham <cketcham@nvidia.com>
@cketcham2333
Make the cudaq Python-component CMake edits drift-proof
7a33939 
The wheel builds apply a hardcoded `git apply` patch to the cuda-quantum
source to link the Python bindings against Python3::Module instead of
Python3::Python.  A diff must also match its surrounding context, and that
context drifts independently of the lines we actually care about:
cuda-quantum removed `cudaq-py-utils` from the cudaq-pyscf link line in
"Use shared libcudaqMLIR dependency everywhere" (#4928), and because that
line sat in the trailing context of the second hunk the whole patch is now
rejected:

  error: python/runtime/cudaq/domains/plugins/CMakeLists.txt: patch does
  not apply

Neither the existing -C1 fallback nor --3way recovers from this (the
inline patch carries no index lines, so 3-way has nothing to resolve
against), so replace the patch with line-local sed substitutions plus a
guard that fails loudly if either substitution stops matching -- otherwise
an upstream rename here would silently produce a wheel that hard-links
libpython.

This surfaced when .cudaq_version was re-pinned to the paired
cuda-quantum hololink_rename branch, but it is not specific to that
branch: any bump onto current cuda-quantum main hits it, including the
re-pin to an NVIDIA/cuda-quantum SHA once the rename merges.

Signed-off-by: Chuck Ketcham <cketcham@nvidia.com>
@cketcham2333
cketcham2333 marked this pull request as ready for review July 28, 2026 21:42
vedika-saravanan
vedika-saravanan reviewed Jul 31, 2026
View reviewed changes

@vedika-saravanan vedika-saravanan left a comment •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, Chuck. Overall, the rename looks consistent with the companion CUDA-Q changes. I left two comments for clarification.

Comment thread libs/qec/include/cudaq/qec/realtime/decoding_config.h
Comment thread .github/workflows/scripts/build_cudaq.sh Outdated
@cketcham2333
Address PR 754 review: provider soname mapping + positive sed guards
b49f370 
1. Map snake_case provider names to the hyphenated bridge sonames
   (review: provider "gpu_roce" resolved to
   libcudaq-realtime-bridge-gpu_roce.so while CUDA-Q builds
   libcudaq-realtime-bridge-gpu-roce.so).

   resolve_provider_lib() now maps '_' -> '-' when turning a bare
   provider name into libcudaq-realtime-bridge-<name>.so, and probes
   QEC_BRIDGE_PROVIDER_DIR with the literal spelling as a fallback so an
   out-of-tree provider whose soname really contains an underscore keeps
   resolving.  This also fixes the pre-existing --transport=cpu_roce
   mismatch (the shipped soname has always been hyphenated:
   libcudaq-realtime-bridge-cpu-roce.so); that path previously only
   worked on dev boxes with a hand-made compatibility symlink.
   Documented the mapping in decoding_config.h, the server's file
   header, and its --help text.

   Verified with the standalone server against a fresh cuda-quantum
   realtime install (which contains no compatibility symlinks):
   --transport=foo_bar now reports libcudaq-realtime-bridge-foo-bar.so,
   and --transport=cpu_roce resolves and dlopens the shipped hyphenated
   library (failure moves to the provider's create(), as expected
   without RDMA device args).

2. Require the substituted forms after the cudaq CMake edits (review:
   validate Development.Module / Python3::Module exist after sed).

   The guards in .github/workflows/scripts/build_cudaq.sh and
   scripts/ci/build_cudaq_wheel.sh now check that the substituted forms
   are present, not merely that the old forms are gone -- if upstream
   reshapes these lines, sed matches nothing and both old checks would
   have passed silently, producing a wheel that hard-links libpython.
   Verified all three states against a real cuda-quantum tree: pristine
   (applies, exit 0), already-substituted (idempotent, exit 0), and a
   simulated upstream reshape (exit 1 with a pointed error).

Signed-off-by: Chuck Ketcham <cketcham@nvidia.com>
@cketcham2333
Merge remote-tracking branch 'upstream/main' into hololink_rename
8b18748
@cketcham2333
Fix docs build: Doxygen rejects <name> placeholder in decoding_config.h
b61d2a8 
The provider-resolution doc comment added for the PR 754 review wrote the
soname pattern as libcudaq-realtime-bridge-<name>.so; the docs build's
Doxygen parses <name> as an HTML/XML tag and fails:

  decoding_config.h:108: error: Unsupported xml/html tag <name> found

Reword to spell the pattern without angle brackets
("libcudaq-realtime-bridge-" + name + ".so").  Verified with a local
Doxygen XML pass over the header (no tag errors) and confirmed no other
angle-bracket placeholders exist in public-header doc comments.

Signed-off-by: Chuck Ketcham <cketcham@nvidia.com>
@cketcham2333
Bump cudaq_version to match PR 5006
96e3ebe 
Signed-off-by: Chuck Ketcham <cketcham@nvidia.com>
vedika-saravanan
vedika-saravanan approved these changes Aug 3, 2026
View reviewed changes

@vedika-saravanan vedika-saravanan left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks @cketcham2333. LGTM

@cketcham2333
cketcham2333 merged commit 32ff0e6 into NVIDIA:main Aug 3, 2026
67 checks passed
cketcham2333 added a commit to cketcham2333/cudaqx that referenced this pull request Aug 3, 2026
@cketcham2333
Fix semantic merge leftovers from the hololink->hsb rename (PR 754)
5bb0ffc 
The upstream/main merge auto-merged cleanly around three references this
branch added to the playback tool by its pre-rename name (main renamed the
target/binary in NVIDIA#754, this branch's additions were on untouched lines):

- unittests/utils/CMakeLists.txt: install rule referenced the deleted
  hololink_fpga_syndrome_playback target (the CI configure failure).
- run_realtime_decoding.sh: --install-prefix binary resolution pointed at
  the old binary name (would fail at runtime); plus two help-text mentions.
- realtime_decoding_demo.rst: two doc mentions of the old tool name.

Signed-off-by: Chuck Ketcham <cketcham@nvidia.com>
melody-ren added a commit to melody-ren/cudaqx that referenced this pull request Aug 5, 2026
@melody-ren
Merge upstream/main into melodyr/goodbye-inproc-rpc
db95218 
Conflict resolutions, all in favor of upstream's post-NVIDIA#682/NVIDIA#750 realtime
structure with the inproc_rpc path kept out:

- qec_realtime_session.cpp: deleted (upstream's touch was to removed code).
- GpuRoceTransceiver.cpp: deleted; NVIDIA#754 renamed it to
  DeviceGraphTransceiver.cpp. The stale qec_realtime_session comment
  reference the branch scrubbed moved to DeviceGraphRingConsumer.cpp and is
  scrubbed there instead.
- realtime_decoding.cpp: reset_decoder takes NVIDIA#698's pin_decode_device(),
  dropping the rpc_producer dispatch branch.
- decoding_server.cpp: upstream's per-ring rewrite; its comments no longer
  reference qec_realtime_session, so the branch's scrub is subsumed.
- app_examples/CMakeLists.txt: upstream's add_surface_code_4_yaml_test
  signature (onnx_path folded into ARGN) with an empty test environment.
- surface_code-4-yaml-test.sh: keep the num_logical echo, drop the
  CUDAQ_QEC_REALTIME_MODE echo.
- realtime_relay_bp.rst: single Building subsection renamed Hololink -> HSB,
  target list on the NVIDIA#754 names, CI-unit-test section dropped (the test is
  removed) and the Surface Code Test section kept.

Upstream added no new inproc_rpc surface: DeviceGraphTransceiver,
DeviceGraphRingConsumer, surface_code-5-per-decoder-rings and
realtime_decoding_demo are all inproc-free.

Signed-off-by: Melody Ren <melodyr@nvidia.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vedika-saravanan vedika-saravanan vedika-saravanan approved these changes
@bmhowe23 bmhowe23 Awaiting requested review from bmhowe23
@melody-ren melody-ren Awaiting requested review from melody-ren
@Renaud-K Renaud-K Awaiting requested review from Renaud-K

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@cketcham2333 @vedika-saravanan