Add docs/spec/programming-model.md skeleton (non-coherent multi-chip view) #72

New issue

Closed

opened 2026-05-25 19:41:04 -03:00 by navigator · 2 comments

navigator commented

2026-05-25 19:41:04 -03:00

Owner

Goal

Create the programming-model spec skeleton at docs/spec/programming-model.md, listed as deliverable #4 in PLAN.md Section 10. The doc gives the software-facing view of the 8-SoC non-coherent memory architecture (ADR-011 placeholder), so future runtime and ISA spec work can land against a shared mental model.

Sections to include:

Overview (8 SoCs, 2x4 torus, designated master, non-coherent shared address space)
Memory model (explicit copy semantics; no hardware cache coherence between chips; per-chip DDR5 visibility)
Address spaces (per-chip local DRAM, PopLink-mapped peer windows, host PCIe MMIO)
Synchronization primitives (barriers, events, broadcast, all_gather, all_reduce — naming aligned with Section 14.3 API)
Tensor partitioning patterns (tensor / pipeline / expert parallelism per Section 14.4)
Failure model (link errors, BER recovery hooks per Section 12.4)
Programmer-visible telemetry (Section 14.3 fluidpop_query_telemetry)
Open questions (ordering guarantees, fence semantics — defer until ADR-011 lands)

Acceptance criteria

docs/spec/programming-model.md exists with the sections above
Status: Draft skeleton + Owner: TBD header
Each section has TODO markers + 2-3 line intent
Explicitly references the runtime API names from Section 14.3 (fluidpop_open, fluidpop_alloc, fluidpop_copy_*, fluidpop_barrier, fluidpop_broadcast, fluidpop_all_gather)
States explicitly that hardware coherence between chips is NOT provided (ADR-011 non-coherent)
No fabricated timing/latency numbers
Cross-references PLAN.md Sections 10, 14.1-14.4 and the runtime API design / driver scaffolding issue

Plan refs

Section 10 (deliverable #4), Section 14.1 (layer stack), Section 14.3 (runtime API), Section 14.4 (tensor partitioning), Section 8.1 board-level ADR-011 (non-coherent memory)

Notes

Spec scaffolding only — keep vendor- and frequency-neutral. Final semantics depend on ADR-011 being finalized; this doc documents the intended contract so runtime API issue has somewhere to point.

## Goal Create the programming-model spec skeleton at `docs/spec/programming-model.md`, listed as deliverable #4 in PLAN.md Section 10. The doc gives the software-facing view of the 8-SoC non-coherent memory architecture (ADR-011 placeholder), so future runtime and ISA spec work can land against a shared mental model. Sections to include: - Overview (8 SoCs, 2x4 torus, designated master, non-coherent shared address space) - Memory model (explicit copy semantics; no hardware cache coherence between chips; per-chip DDR5 visibility) - Address spaces (per-chip local DRAM, PopLink-mapped peer windows, host PCIe MMIO) - Synchronization primitives (barriers, events, broadcast, all_gather, all_reduce — naming aligned with Section 14.3 API) - Tensor partitioning patterns (tensor / pipeline / expert parallelism per Section 14.4) - Failure model (link errors, BER recovery hooks per Section 12.4) - Programmer-visible telemetry (Section 14.3 `fluidpop_query_telemetry`) - Open questions (ordering guarantees, fence semantics — defer until ADR-011 lands) ## Acceptance criteria - [ ] `docs/spec/programming-model.md` exists with the sections above - [ ] `Status: Draft skeleton` + `Owner: TBD` header - [ ] Each section has `TODO` markers + 2-3 line intent - [ ] Explicitly references the runtime API names from Section 14.3 (`fluidpop_open`, `fluidpop_alloc`, `fluidpop_copy_*`, `fluidpop_barrier`, `fluidpop_broadcast`, `fluidpop_all_gather`) - [ ] States explicitly that hardware coherence between chips is NOT provided (ADR-011 non-coherent) - [ ] No fabricated timing/latency numbers - [ ] Cross-references PLAN.md Sections 10, 14.1-14.4 and the runtime API design / driver scaffolding issue ## Plan refs Section 10 (deliverable #4), Section 14.1 (layer stack), Section 14.3 (runtime API), Section 14.4 (tensor partitioning), Section 8.1 board-level ADR-011 (non-coherent memory) ## Notes Spec scaffolding only — keep vendor- and frequency-neutral. Final semantics depend on ADR-011 being finalized; this doc documents the intended contract so runtime API issue has somewhere to point.