sw/runtime: scaffold §14.3 canonical names + tree README #103

Merged

navigator merged 1 commit from auto/issue-99-20260526T120744Z_issue99 into main

2026-05-26 09:17:02 -03:00

navigator commented

2026-05-26 09:13:12 -03:00

Owner

Summary

Adds the PLAN.md §14.3 canonical-name stub declarations to
sw/runtime/include/fluidpop.h and creates sw/runtime/README.md.

Context: when issue #99 was opened, the assumption was that the runtime
header did not yet exist. The runtime API design landed instead via
issue #7 / PR #16, which spells the public surface in CUDA-style
(fluidpop_device_open, fluidpop_buf_alloc, fluidpop_memcpy_*,
fluidpop_kernel_launch, fluidpop_telemetry_read). PLAN.md §14.3,
however, names the canonical symbol set verbatim as fluidpop_open,
fluidpop_alloc, fluidpop_copy_h2d / _d2h / _d2d,
fluidpop_launch, fluidpop_query_telemetry. Future docs
(programming-model spec, ISA reference) need a stable landing path for
those exact spellings even before ADR-011 finalizes parameter shapes.

What changed

sw/runtime/include/fluidpop.h: appended a "PLAN.md §14.3 canonical
surface (stub declarations)" block with declarations for
fluidpop_open, fluidpop_alloc, fluidpop_copy_h2d / _d2h /
_d2d, fluidpop_launch, fluidpop_query_telemetry. Each prototype
carries a one-line /* TODO: ... */ comment marking what is pending
ADR-011 / runtime API + driver scaffolding issue (#7). The CUDA-style
entry points and the existing fluidpop_barrier / _broadcast /
_all_gather / _all_reduce (with fluidpop_op_t SUM/MAX/MIN/AVG)
- stream/event APIs are left untouched.
sw/runtime/README.md (new): documents the tree, the four-layer
stack (PLAN.md §14.1), the §14.3 → declared-symbol map, and points
at PLAN.md §14 and the runtime API + driver scaffolding issue (#7).

Acceptance criteria (from #99)

sw/runtime/include/fluidpop.h exists with declarations above
Header is syntactically valid C (compiles standalone as a
header-only TU; verified with gcc -std=c11 -Wpedantic -Werror
and g++ -std=c++17 -Wpedantic)
All function names from §14.3 present as declarations
all_reduce op enum present with the four operations
(FLUIDPOP_OP_SUM / _MAX / _MIN / _AVG)
Each newly-added declaration has a brief one-line /* TODO: ... */
describing what is still undecided
sw/runtime/README.md created and references PLAN.md Section 14
and the runtime API design issue (#7)
No .c implementation files created — header-only scaffolding

Notes

ADR-017 off-limits paths untouched. LICENSE.md not modified — the
header keeps the short SPDX-License-Identifier: AGPL-3.0-or-later
line and points readers at the project license.
No new ABI symbols are promised: the canonical-name stubs have no
implementation backing yet; the README states this explicitly.
Pre-existing missing _POSIX_C_SOURCE macro in fluidpop_mock.c is
unrelated and predates this change; with the macro defined the mock
still compiles cleanly against the updated header.

Closes #99.

## Summary Adds the PLAN.md §14.3 canonical-name stub declarations to `sw/runtime/include/fluidpop.h` and creates `sw/runtime/README.md`. Context: when issue #99 was opened, the assumption was that the runtime header did not yet exist. The runtime API design landed instead via issue #7 / PR #16, which spells the public surface in CUDA-style (`fluidpop_device_open`, `fluidpop_buf_alloc`, `fluidpop_memcpy_*`, `fluidpop_kernel_launch`, `fluidpop_telemetry_read`). PLAN.md §14.3, however, names the canonical symbol set verbatim as `fluidpop_open`, `fluidpop_alloc`, `fluidpop_copy_h2d` / `_d2h` / `_d2d`, `fluidpop_launch`, `fluidpop_query_telemetry`. Future docs (programming-model spec, ISA reference) need a stable landing path for those exact spellings even before ADR-011 finalizes parameter shapes. ## What changed - `sw/runtime/include/fluidpop.h`: appended a "PLAN.md §14.3 canonical surface (stub declarations)" block with declarations for `fluidpop_open`, `fluidpop_alloc`, `fluidpop_copy_h2d` / `_d2h` / `_d2d`, `fluidpop_launch`, `fluidpop_query_telemetry`. Each prototype carries a one-line `/* TODO: ... */` comment marking what is pending ADR-011 / runtime API + driver scaffolding issue (#7). The CUDA-style entry points and the existing `fluidpop_barrier` / `_broadcast` / `_all_gather` / `_all_reduce` (with `fluidpop_op_t` SUM/MAX/MIN/AVG) + stream/event APIs are left untouched. - `sw/runtime/README.md` (new): documents the tree, the four-layer stack (PLAN.md §14.1), the §14.3 → declared-symbol map, and points at PLAN.md §14 and the runtime API + driver scaffolding issue (#7). ## Acceptance criteria (from #99) - [x] `sw/runtime/include/fluidpop.h` exists with declarations above - [x] Header is syntactically valid C (compiles standalone as a header-only TU; verified with `gcc -std=c11 -Wpedantic -Werror` and `g++ -std=c++17 -Wpedantic`) - [x] All function names from §14.3 present as declarations - [x] all_reduce op enum present with the four operations (`FLUIDPOP_OP_SUM` / `_MAX` / `_MIN` / `_AVG`) - [x] Each newly-added declaration has a brief one-line `/* TODO: ... */` describing what is still undecided - [x] `sw/runtime/README.md` created and references PLAN.md Section 14 and the runtime API design issue (#7) - [x] No `.c` implementation files created — header-only scaffolding ## Notes - ADR-017 off-limits paths untouched. `LICENSE.md` not modified — the header keeps the short `SPDX-License-Identifier: AGPL-3.0-or-later` line and points readers at the project license. - No new ABI symbols are promised: the canonical-name stubs have no implementation backing yet; the README states this explicitly. - Pre-existing missing `_POSIX_C_SOURCE` macro in `fluidpop_mock.c` is unrelated and predates this change; with the macro defined the mock still compiles cleanly against the updated header. Closes #99.

navigator added 1 commit

2026-05-26 09:13:12 -03:00

sw/runtime: scaffold §14.3 canonical names + tree README

build / scalafmt-check (pull_request) Successful in 3s

Details

build / sbt-compile (pull_request) Successful in 3s

Details

build / shell-lint (pull_request) Successful in 1m51s

Details

0a957c3564

The runtime API design that landed via #7 spells the public surface in
CUDA-style (fluidpop_device_open, fluidpop_buf_alloc, fluidpop_memcpy_*,
etc.), but PLAN.md §14.3 names the canonical symbol set verbatim as
fluidpop_open, fluidpop_alloc, fluidpop_copy_h2d/d2h/d2d,
fluidpop_launch and fluidpop_query_telemetry. Future docs
(programming-model spec, ISA reference) need a known landing path for
those exact spellings even before ADR-011 finalizes the parameter
shapes.

This patch:
  - adds stub declarations in sw/runtime/include/fluidpop.h for the
    PLAN.md §14.3 canonical names that did not already match
    (fluidpop_barrier / broadcast / all_gather / all_reduce + streams
    and events were already declared);
  - keeps parameter shapes deliberately loose, with a one-line TODO
    comment per prototype marking what is pending ADR-011 / #7;
  - leaves the richer CUDA-style entry points untouched — both
    spellings coexist until ADR-011 closes;
  - creates sw/runtime/README.md describing the tree, the layered
    stack, the PLAN.md §14.3 → declared-symbol map, and pointing at
    PLAN.md §14 and the runtime API + driver scaffolding issue (#7);
  - header-only scaffolding: no new .c file, no ABI symbols promised.
    Verified the header still compiles standalone (C11 and C++17) and
    that fluidpop_mock.c still builds.

Closes #99.

navigator added the

ready-for-review

label

2026-05-26 09:13:21 -03:00

navigator commented

2026-05-26 09:16:11 -03:00

Author

Owner

VERDICT: PASS

PR #103 adds the PLAN.md §14.3 canonical-name stub declarations to the existing sw/runtime/include/fluidpop.h and creates a new sw/runtime/README.md, scoped cleanly to Issue #99. Mechanical guardrails pass: new README carries CC-BY-SA-4.0 SPDX header at line 1 (correct for doc/README), existing fluidpop.h retains its AGPL-3.0-or-later header (correct for software), no AI/Anthropic attribution, no off-limits paths (only sw/runtime/), no Chisel module so rules 4–6 don't apply. The header is verified syntactically valid C/C++ per the acceptance criteria. Rule 7 is handled carefully: each newly-added stub declaration carries an explicit /* TODO: ... */ comment naming what's still pending (ADR-011 closure, driver IOCTL surface, PopLink cross-chip routing parameters), no parameter semantics are committed beyond what's syntactically necessary to declare the prototype using existing types from the prior surface (fluidpop_dev_t, fluidpop_buf_t, fluidpop_size_t, etc.), and the file-level block-comment explicitly disclaims linkage: "no implementation backs these symbols yet. Do not link against them. They are header-only scaffolding." The PR honestly addresses the situation that Issue #99 was opened under a stale assumption — the runtime header had already landed via Issue #7 / PR #16 in CUDA-style spelling — and rather than disrupting the working API surface, lands the §14.3 canonical names as stubs alongside it, with the README's "PLAN.md §14.3 → declared symbol map" table making the relationship between the two name sets explicit. The README's claims are all attributed to specific PLAN.md sections (§14.1 layer stack, §14.2 driver responsibilities, §14.3 API surface, §14.4 partitioning, §14.6 mock-driver/co-sim, §14.7 15–22 person-months estimate) and consistent with prior approved PRs in this thread on ADR-011 framing. Scope matches Issue #99 (header + README only, no .c implementation files), no drive-by edits, and the PR body honestly flags one unrelated pre-existing issue (_POSIX_C_SOURCE macro missing in fluidpop_mock.c) without attempting to fix it as a drive-by.

Findings

None.

**VERDICT:** PASS PR #103 adds the PLAN.md §14.3 canonical-name stub declarations to the existing `sw/runtime/include/fluidpop.h` and creates a new `sw/runtime/README.md`, scoped cleanly to Issue #99. Mechanical guardrails pass: new README carries `CC-BY-SA-4.0` SPDX header at line 1 (correct for doc/README), existing `fluidpop.h` retains its `AGPL-3.0-or-later` header (correct for software), no AI/Anthropic attribution, no off-limits paths (only `sw/runtime/`), no Chisel module so rules 4–6 don't apply. The header is verified syntactically valid C/C++ per the acceptance criteria. Rule 7 is handled carefully: each newly-added stub declaration carries an explicit `/* TODO: ... */` comment naming what's still pending (ADR-011 closure, driver IOCTL surface, PopLink cross-chip routing parameters), no parameter semantics are committed beyond what's syntactically necessary to declare the prototype using existing types from the prior surface (`fluidpop_dev_t`, `fluidpop_buf_t`, `fluidpop_size_t`, etc.), and the file-level block-comment explicitly disclaims linkage: "no implementation backs these symbols yet. Do not link against them. They are header-only scaffolding." The PR honestly addresses the situation that Issue #99 was opened under a stale assumption — the runtime header had already landed via Issue #7 / PR #16 in CUDA-style spelling — and rather than disrupting the working API surface, lands the §14.3 canonical names as stubs alongside it, with the README's "PLAN.md §14.3 → declared symbol map" table making the relationship between the two name sets explicit. The README's claims are all attributed to specific PLAN.md sections (§14.1 layer stack, §14.2 driver responsibilities, §14.3 API surface, §14.4 partitioning, §14.6 mock-driver/co-sim, §14.7 15–22 person-months estimate) and consistent with prior approved PRs in this thread on ADR-011 framing. Scope matches Issue #99 (header + README only, no .c implementation files), no drive-by edits, and the PR body honestly flags one unrelated pre-existing issue (`_POSIX_C_SOURCE` macro missing in `fluidpop_mock.c`) without attempting to fix it as a drive-by. ## Findings _None._

navigator added the

review:pass

label

2026-05-26 09:16:11 -03:00