Fluid/fluidpop-v1
1
0
Fork 0
Code Issues 17 Pull requests Projects Releases Packages Wiki Activity Actions

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

New issue
Open
opened 2026-05-27 09:07:12 -03:00 by navigator · 3 comments
navigator commented 2026-05-27 09:07:12 -03:00
Owner
Copy link

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)
  • 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 open 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 the 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) - 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 open 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 the runtime API issue has somewhere to point.
navigator commented 2026-05-27 09:10:23 -03:00
Author
Owner
Copy link
No description provided.
<!-- agent:claim by=dispatcher run=20260527T121023Z_issue118 ts=1779883823 -->
navigator commented 2026-05-27 09:11:25 -03:00
Author
Owner
Copy link

The deliverable in this issue is already satisfied by docs/spec/programming-model.md as it exists on main today (landed via PR #76 / commit 2552f61, merged 2026-05-25).

Verification against the acceptance criteria:

  • File docs/spec/programming-model.md exists with all eight sections (Overview, Memory model, Address spaces, Synchronization primitives, Tensor partitioning patterns, Failure model, Telemetry, Open questions).
  • Header carries **Status:** Draft skeleton and **Owner:** TBD.
  • Each section has a TODO: marker + 2–3 line intent.
  • Runtime API names from PLAN.md §14.3 are present: fluidpop_open, fluidpop_alloc, fluidpop_copy_d2d, fluidpop_copy_h2d, fluidpop_copy_d2h, fluidpop_barrier, fluidpop_broadcast, fluidpop_all_gather, plus the future fluidpop_all_reduce and fluidpop_query_telemetry.
  • Explicit ADR-011 non-coherence callout: "hardware does NOT provide cache coherence between chips. Cross-chip visibility is the application's responsibility."
  • No timing/latency numbers (the doc explicitly forbids them until ADR-011 + PHY survey close).
  • Cross-references PLAN.md §10 deliverable #4, §14.1–14.4, §12.4, plus driver-design.md and issue #7 / PR #16.

Recommendation: close as duplicate of PR #76 — no PR will be opened from this resolver run. If subsequent expansion is wanted (e.g., promoting the skeleton beyond Draft once ADR-011 is Accepted), please file a follow-up issue that names the new content gap rather than re-requesting the skeleton.

<!-- agent:fail reason=blocker:already-done --> The deliverable in this issue is **already satisfied** by `docs/spec/programming-model.md` as it exists on `main` today (landed via PR #76 / commit `2552f61`, merged 2026-05-25). Verification against the acceptance criteria: - [x] File `docs/spec/programming-model.md` exists with all eight sections (Overview, Memory model, Address spaces, Synchronization primitives, Tensor partitioning patterns, Failure model, Telemetry, Open questions). - [x] Header carries `**Status:** Draft skeleton` and `**Owner:** TBD`. - [x] Each section has a `TODO:` marker + 2–3 line intent. - [x] Runtime API names from PLAN.md §14.3 are present: `fluidpop_open`, `fluidpop_alloc`, `fluidpop_copy_d2d`, `fluidpop_copy_h2d`, `fluidpop_copy_d2h`, `fluidpop_barrier`, `fluidpop_broadcast`, `fluidpop_all_gather`, plus the future `fluidpop_all_reduce` and `fluidpop_query_telemetry`. - [x] Explicit ADR-011 non-coherence callout: *"hardware does NOT provide cache coherence between chips. Cross-chip visibility is the application's responsibility."* - [x] No timing/latency numbers (the doc explicitly forbids them until ADR-011 + PHY survey close). - [x] Cross-references PLAN.md §10 deliverable #4, §14.1–14.4, §12.4, plus `driver-design.md` and issue #7 / PR #16. Recommendation: **close as duplicate of PR #76** — no PR will be opened from this resolver run. If subsequent expansion is wanted (e.g., promoting the skeleton beyond Draft once ADR-011 is Accepted), please file a follow-up issue that names the *new* content gap rather than re-requesting the skeleton.
navigator commented 2026-05-27 09:16:28 -03:00
Author
Owner
Copy link
No description provided.
<!-- agent:fail reason=no-pr-marker run=20260527T121023Z_issue118 -->
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
auto/issue-112-20260526T211219Z_issue112
auto/issue-113-20260526T211252Z_issue113
auto/issue-104-20260526T163428Z_issue104
auto/issue-105-20260526T163459Z_issue105
auto/issue-51-20260526T163356Z_issue51
auto/issue-52-20260526T001333Z_issue52
auto/issue-53-20260526T001906Z_issue53
auto/issue-98-20260526T120712Z_issue98
auto/issue-99-20260526T120744Z_issue99
auto/issue-100-20260526T120815Z_issue100
spec/popsocconfig-draft
spec/poproccrouter-draft
spec/poplinkphy_behavioral-draft
spec/pciehostbridge-draft
spec/multigemminicluster-draft
spec/intergemminixbar-draft
spec/interchipfabric-draft
spec/fluidpopsoc-draft
auto/issue-84-20260526T040021Z_issue84
auto/issue-86-20260526T040124Z_issue86
auto/issue-85-20260526T040052Z_issue85
auto/issue-73-20260525T225502Z_issue73
feat/spec-designer-role
auto/issue-54-20260526T001939Z_issue54
auto/issue-47-20260526T001302Z_issue47
fix/pr-reviewer-label-detect
auto/issue-72-20260525T224929Z_issue72
auto/issue-71-20260525T224356Z_issue71
fix/pr-approver-gate-on-review
auto/issue-68-20260525T205321Z_issue68
feat/pr-reviewer-role
auto/issue-58-20260525T203246Z_issue58
auto/issue-51-20260525T202210Z_issue51
auto/issue-50-20260525T201137Z_issue50
auto/issue-49-20260525T200104Z_issue49
auto/issue-48-20260525T195031Z_issue48
fix/auto-merge-rebase-refspec
auto/issue-57-20260525T192021Z_issue57
auto/issue-56-20260525T191448Z_issue56
auto/issue-46-20260525T174915Z_issue46
auto/issue-6-20260525T173842Z_issue6
fix/auto-merge-result-return
fix/auto-merge-rebase-behind-base
auto/issue-40-20260525T121803Z_issue40
auto/issue-39-20260525T121230Z_issue39
auto/issue-38-20260525T120657Z_issue38
auto/issue-32-20260524T183617Z_issue32
auto/issue-31-20260524T183039Z_issue31
feature/hotfix-approver-reap
auto/issue-30-20260524T182505Z_issue30
feature/hotfix-cache-invalidation
feature/hotfix-swarm-labels
feature/adr-017-accepted
feature/adr-017-swarm-security
feature/swarm-approver-install
feature/swarm-resolver-dispatcher-on-25
feature/swarm-lib-operator-opener
feature/bridge-stream-json-logs
feature/gitignore-claude-workspace
feature/bridge-resilience-fix
feature/telegram-claude-bridge
feature/telegram-notify
feature/cfd-case-template
feature/runtime-driver-spec
feature/phy-outreach-letters
feature/risk-dashboard
feature/auto-merge-helper
feature/initial-adrs
feature/forgejo-bot-reviewer
feature/ci-runner-setup
No results found.
Labels
Clear labels   
adr

Architecture Decision Record

  
agent:blocked-ci

CI failed on the PR

  
agent:blocked-human

Operator escalated; awaiting Marcos input

  
agent:blocked-resolver

Resolver crashed, returned empty, or timed out

  
agent:done

PR merged; issue auto-closed

  
agent:in-progress

Resolver claimed and running

  
agent:no-touch

Human-reserved; swarm Opener/Dispatcher skip

  
agent:pinged

Operator already escalated; suppress repeat pings

  
agent:pr-open

Resolver opened a PR; awaiting review/merge

  
agent:queued

Issue ready for swarm Resolver to claim

  
agent:wip

PR work-in-progress; Approver skips

  
area:board

PCB / mechanical / cooling

  
area:funding

PACID / grants / RFQs

  
area:infra

Dev env, CI, containers

  
area:phy

Physical layer / SerDes

  
area:poplink

PopLink protocol

  
area:rtl

Chisel/RTL work

  
area:software

Driver / runtime / frameworks

  
area:supply-chain

Foundry, OSAT, PCB, components

  
area:verification

Test, formal, coverage

  
ci-failed

auto-merge.sh detected CI failure

  
ci-timeout

auto-merge.sh hit CI timeout

  
docs

Documentation

  
do-not-merge

Hard hold; PR Approver skips

  
human-approved

Marcos approved via Telegram; release governance hold

  
needs-human-approval

Touches governance path; awaits Marcos label human-approved

  
needs-rebase

PR is not mergeable; rebase needed

  
needs-triage

Issue from untrusted author; Marcos triage needed

  
phase:1

Phase 1 (Section 6 of PLAN.md)

  
ready-for-review

Resolver done; PR Approver triages

  
review:findings

PR semantic review flagged blocking findings

  
review:pass

PR semantic review passed; safe for pr-approver

  
risk:tripwire

Section 0.5 tripwire fired

  
swarm:quarantined

Escalation tripwire fired; resolver tried off-limits paths

No labels
adr
agent:blocked-ci
agent:blocked-human
agent:blocked-resolver
agent:done
agent:in-progress
agent:no-touch
agent:pinged
agent:pr-open
agent:queued
agent:wip
area:board
area:funding
area:infra
area:phy
area:poplink
area:rtl
area:software
area:supply-chain
area:verification
ci-failed
ci-timeout
docs
do-not-merge
human-approved
needs-human-approval
needs-rebase
needs-triage
phase:1
ready-for-review
review:findings
review:pass
risk:tripwire
swarm:quarantined
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Fluid/fluidpop-v1#118
No description provided.