Skip to content

docs(qec): standalone decoding server reference page#686

Draft
vedika-saravanan wants to merge 1 commit into
NVIDIA:mainfrom
vedika-saravanan:docs/decoding-server
Draft

docs(qec): standalone decoding server reference page#686
vedika-saravanan wants to merge 1 commit into
NVIDIA:mainfrom
vedika-saravanan:docs/decoding-server

Conversation

@vedika-saravanan

Copy link
Copy Markdown
Collaborator

Description

Adds docs/sphinx/examples_rst/qec/decoding_server.rst, a new
reference page for the standalone decoding_server binary introduced
in the realtime decoding server work.

  • Transports: table covering udp (CI/dev), cpu_roce (SoftRoCE /
    HSB FPGA HOST_CALL), and gpu_roce (DOCA + Hololink device-graph
    scheduler), with when-to-use guidance for each.
  • YAML configuration: full field reference including transport and
    cuda_device_id; Python binding note for cuda_device_id; note on
    orchestration script auto-injection.
  • GPU affinity reconciliation: four-case table for
    cuda_device_id vs HOLOLINK_GPU_ID resolution at startup.
  • Building: prerequisites, CMake flags, private graph-dispatch
    symbols (decoder_rpc_dispatch.cu / cudaq-qec-realtime-decoder-rpc-dispatch
    whole-archive link) with public-build fallback behavior explained.
  • Running: CLI reference, readiness signals, and launch examples for
    all three transports.
  • GB200 / aarch64 page-size alignment: explains the 64 KiB host-page
    constraint, the 512 x 64 = 32768 failure case, and the
    --gpu-roce-num-pages auto fix.
  • Orchestration script (hsb_fpga_decoding_server_test.sh): full
    option reference (modes, actions, decoder options, data generation,
    run options, network options, build options) with quick-start examples.
  • Troubleshooting: covers DOCA allocation failures, GPU ID mismatch,
    missing proprietary symbols, ILA deterministic verification fix
    (expected sample count vs. stabilization heuristic), and common
    network issues.

Linked from the QEC examples toctree (examples.rst) and the
realtime decoding section of introduction.rst.

Generated with Claude Code

Runtime / performance impact

Self-review checklist

Please confirm each item before requesting review. Check [x] or strike
through and explain.

Before requesting review

  • I reviewed my own full diff in GitHub or my editor.
  • PR is in Draft if it is not yet ready for review.
  • Temporary / debugging changes have been removed.
  • Local test logs reviewed; no unexplained warnings or errors.
  • CI logs reviewed; no unexplained warnings or errors.
  • Full CI has been run.

Scope and size

  • PR is under ~1000 lines, or an exception is justified in the description.
  • Refactoring-only changes are isolated in their own PR(s).
  • No existing tests were disabled or modified just to make this PR pass
    (if so, an issue has been raised).

Tests

  • New functionality has new tests.
  • Tests fail if the new functionality is broken (including crashes), not
    just when it is missing.
  • Negative tests added where exceptions are expected.
  • Truth data added where simple EXPECT_* / assert checks are
    insufficient for algorithmic correctness.
  • CI runtime impact considered; team notified if significant.

Documentation

  • Public-facing APIs have Doxygen docs.
  • User-visible behavior changes have public docs, or a follow-up is
    tracked.

Code style

  • Naming follows the existing convention (snake_case vs camelCase) for
    the area being modified.

Dependencies

  • No new third-party dependencies, or the team has been notified and
    OSRB tickets filed.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant