Scaffold sw/runtime/include/fluidpop.h header stub for runtime API #99

New issue

Closed

opened 2026-05-26 09:04:21 -03:00 by navigator · 3 comments

navigator commented

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

Owner

Goal

Create the C header stub at sw/runtime/include/fluidpop.h that PLAN.md Section 14.3 names as the canonical location for the user-space runtime API surface. The stub provides declarations only (no implementation), so the existing Runtime API design + driver scaffolding issue has a known landing path and future docs (programming-model spec, ISA reference) can cross-link the symbol names.

Contents:

File header banner with license note (project default; do NOT touch LICENSE.md itself)
#ifndef FLUIDPOP_H include guard
Opaque types: fluidpop_device_t, fluidpop_stream_t, fluidpop_event_t
Function declarations (no bodies) for the names enumerated in Section 14.3: fluidpop_open, fluidpop_alloc, fluidpop_copy_h2d, fluidpop_copy_d2h, fluidpop_copy_d2d, fluidpop_launch, fluidpop_barrier, fluidpop_broadcast, fluidpop_all_gather, fluidpop_query_telemetry
Enum stub for all_reduce op: FLUIDPOP_OP_SUM | MAX | MIN | AVG
Stream + event APIs (create / destroy / wait) per Section 14.3 async semantics
Each declaration carries a TODO comment marking parameters as TBD until ADR-011 / runtime design issue finalizes them
sw/runtime/README.md explaining the directory and pointing at the runtime API design issue

Acceptance criteria

sw/runtime/include/fluidpop.h exists with declarations above
Header is syntactically valid C (compiles standalone as a header-only TU with a trivial .c that includes it; no implementation required)
All function names from Section 14.3 present as declarations
all_reduce op enum present with the four operations from Section 14.3
Each declaration has a brief one-line /* TODO: ... */ describing what's still undecided
sw/runtime/README.md created and references PLAN.md Section 14 and the runtime API design issue
No .c implementation files created — header-only scaffolding

Plan refs

Section 14.3 (user-space runtime API), Section 14.1 (layer stack), Section 14.4 (tensor partitioning informing future param types)

Notes

Header-only scaffolding. Parameter types stay loose (TBD) on purpose — final types depend on driver IOCTL surface and ADR-011, which are tracked in the runtime API + driver scaffolding issue. Do NOT modify LICENSE.md (off-limits per ADR-017); use a short license-mention comment that points to LICENSE.md.

## Goal Create the C header stub at `sw/runtime/include/fluidpop.h` that PLAN.md Section 14.3 names as the canonical location for the user-space runtime API surface. The stub provides declarations only (no implementation), so the existing Runtime API design + driver scaffolding issue has a known landing path and future docs (programming-model spec, ISA reference) can cross-link the symbol names. Contents: - File header banner with license note (project default; do NOT touch LICENSE.md itself) - `#ifndef FLUIDPOP_H` include guard - Opaque types: `fluidpop_device_t`, `fluidpop_stream_t`, `fluidpop_event_t` - Function declarations (no bodies) for the names enumerated in Section 14.3: `fluidpop_open`, `fluidpop_alloc`, `fluidpop_copy_h2d`, `fluidpop_copy_d2h`, `fluidpop_copy_d2d`, `fluidpop_launch`, `fluidpop_barrier`, `fluidpop_broadcast`, `fluidpop_all_gather`, `fluidpop_query_telemetry` - Enum stub for all_reduce op: `FLUIDPOP_OP_SUM | MAX | MIN | AVG` - Stream + event APIs (create / destroy / wait) per Section 14.3 async semantics - Each declaration carries a TODO comment marking parameters as TBD until ADR-011 / runtime design issue finalizes them - `sw/runtime/README.md` explaining the directory and pointing at the runtime API design issue ## Acceptance criteria - [ ] `sw/runtime/include/fluidpop.h` exists with declarations above - [ ] Header is syntactically valid C (compiles standalone as a header-only TU with a trivial .c that includes it; no implementation required) - [ ] All function names from Section 14.3 present as declarations - [ ] all_reduce op enum present with the four operations from Section 14.3 - [ ] Each declaration has a brief one-line `/* TODO: ... */` describing what's still undecided - [ ] `sw/runtime/README.md` created and references PLAN.md Section 14 and the runtime API design issue - [ ] No `.c` implementation files created — header-only scaffolding ## Plan refs Section 14.3 (user-space runtime API), Section 14.1 (layer stack), Section 14.4 (tensor partitioning informing future param types) ## Notes Header-only scaffolding. Parameter types stay loose (TBD) on purpose — final types depend on driver IOCTL surface and ADR-011, which are tracked in the runtime API + driver scaffolding issue. Do NOT modify LICENSE.md (off-limits per ADR-017); use a short license-mention comment that points to LICENSE.md.