spec(FluidPopSoC): promote FluidPopSoC.SPEC.md to Draft #87

Merged

navigator merged 1 commit from spec/fluidpopsoc-draft into main 2026-05-26 01:14:15 -03:00

Conversation 3 Commits 1 Files changed 1 +34 -4

navigator commented 2026-05-26 01:02:08 -03:00

Owner

Copy link

Refs #54 (companion Chisel skeleton, already merged via #83).
Refs #80 (spec-designer role onboarding).

This PR is opened by the autonomous spec-designer role; per
infra/ops/agents/roles/spec-designer.sh the role is designer-driven
and runs without a dedicated source issue, so no Closes # is attached.
If the swarm policy requires a tracking issue per promotion, the
follow-up tweak belongs in the role script, not in this SPEC change.

Summary

Promotes rtl/src/pop/specs/FluidPopSoC.SPEC.md from Status: Stub
to Status: Draft. No behaviour, no Chisel, no edits outside the
single SPEC file. The IO contract is pinned to ADRs that already commit
values; widths and pin-lists no source pins are recorded as
_Open question:_ rather than invented.

Resolved TBDs

• §Interface — DDR5 PHY pinout: channel count pinned to ADR-005
  Decision (Edu: 1 channel, Pro: 2 channels). Ball-budget envelope
  ~290 DDR5 balls per ADR-014 Decision (Edu preliminary).
• §Interface — PopLink PHY quad-port: four N/S/E/W ports per chip
  per ADR-010 Decision. Ball-budget envelope ~80 SerDes balls per
  ADR-014.
• §Interface — Optional PCIe Gen4 x16: presence rule pinned to
  ADR-008 Decision ("in master mode the PCIe x16 endpoint is enabled,
  in slave mode it is gated"). Variant selected at elaboration time
  by FluidPopMasterConfig / FluidPopSlaveConfig per PLAN.md §8.2.
  Ball-budget envelope ~80 PCIe balls per ADR-014.
• §Interface — BMC sideband: purpose pinned to ADR-012
  Consequences (water cooling + fine-grained per-Gemmini clock gating).
• §Behavior — Master-vs-slave selection: fully pinned to ADR-008
  Decision and PLAN.md §8.2 Config-fragment names.
• §Behavior — Boot sequence: bring-up ordering of Rocket cores
  (ADR-006), DDR5 controller (ADR-005), MultiGemminiCluster,
  InterChipFabric endpoint (ADR-009), and PCIeHostBridge (ADR-008)
  framed against ADR-010 PopLink-training preconditions.
• §Behavior — Chip-level reset and quiescence: non-coherent
  scoping pinned to ADR-011 (drain only local chip; no board-wide
  coherence directory to flush).
• §Behavior — Thermal/telemetry export: purpose pinned to ADR-012
  Consequences.
• §Invariants — Per-chip power envelope: verbatim ADR-012 title
  (Edu: 50 W typ / 70 W max; Pro: 150 W typ / 180 W peak).
• §Invariants — BGA pin budget: verbatim ADR-014 title; sub-
  allocations preserved from ADR-014 Decision (Edu preliminary); final
  pinout deferred to Phase 4 per ADR-014 Decision.
• §Invariants — Non-coherent memory: verbatim ADR-011 Decision +
  Consequences.
• §Invariants — Single master per board: derived from ADR-008
  Decision and ADR-009 Decision.

Open questions (recorded as _Open question:_ in the SPEC)

• DDR5 PHY signal-level pinout (CA bus, DQ/DQS lanes, ALERT_n,
  RESET_n, ECC byte) — pending DDR5 PHY vendor-selection ADR.
• Per-port PopLink PHY bundle shape — tracks
  rtl/src/pop/specs/PopLinkPHY_Behavioral.SPEC.md §Interface
  (currently Status: Stub).
• PCIe Gen4 x16 signal set / vendor-PHY PIPE attach / MSI-X
  layout — tracks rtl/src/pop/specs/PCIeHostBridge.SPEC.md §Interface
  (currently Status: Stub).
• JTAG / external debug signal set, halt-on-reset behaviour —
  pending debug-architecture ADR.
• Clock-domain decomposition (root clocks, PLL count, per-domain
  refclks) — pending clocking/reset ADR.
• BMC sideband bus choice (I²C / SPI / PMBus) and address map —
  pending board-side BMC ADR.
• Boot ROM location, bootloader split, PopLink training-order
  schedule — pending boot ADR.
• Chip-level quiescence protocol (drain order, time-out behaviour,
  BMC visibility during in-progress quiescence) — pending
  clocking/reset ADR.
• BMC telemetry granularity, sampling cadence, throttle-actuation
  contract — pending BMC ADR.

Constraint check

• **Status:** line flipped Stub → Draft.
• Every TBD resolved (pin to ADR / PLAN, or recorded as
  _Open question:_). No fabricated widths or signal sets.
• Only rtl/src/pop/specs/FluidPopSoC.SPEC.md changes (ADR-017
  off-limits path policy honoured).
• All ADR / PLAN refs from the Stub preserved (PLAN.md §8.2,
  §12.3, ADR-001…ADR-014, ADR-005, ADR-006, ADR-008, ADR-009,
  ADR-010, ADR-011, ADR-012, ADR-014); §12.7 and §8.3 added in
  Coverage targets are kept from the original Stub body.
• No sibling SPEC is currently in Draft; sibling Stubs
  (PopLinkPHY_Behavioral, PCIeHostBridge) are referenced only
  inside Open questions, never as a Draft-pin source.
• ## Promotion history appended with the 2026-05-26 entry.
• No fabricated performance / latency / capacity / vendor
  commitments — every number quoted has an ADR title or Decision
  as source.

Refs #54 (companion Chisel skeleton, already merged via #83). Refs #80 (spec-designer role onboarding). This PR is opened by the autonomous `spec-designer` role; per `infra/ops/agents/roles/spec-designer.sh` the role is designer-driven and runs without a dedicated source issue, so no `Closes #` is attached. If the swarm policy requires a tracking issue per promotion, the follow-up tweak belongs in the role script, not in this SPEC change. ## Summary Promotes `rtl/src/pop/specs/FluidPopSoC.SPEC.md` from **Status: Stub** to **Status: Draft**. No behaviour, no Chisel, no edits outside the single SPEC file. The IO contract is pinned to ADRs that already commit values; widths and pin-lists no source pins are recorded as `_Open question:_` rather than invented. ## Resolved TBDs - **§Interface — DDR5 PHY pinout**: channel count pinned to ADR-005 Decision (Edu: 1 channel, Pro: 2 channels). Ball-budget envelope ~290 DDR5 balls per ADR-014 Decision (Edu preliminary). - **§Interface — PopLink PHY quad-port**: four N/S/E/W ports per chip per ADR-010 Decision. Ball-budget envelope ~80 SerDes balls per ADR-014. - **§Interface — Optional PCIe Gen4 x16**: presence rule pinned to ADR-008 Decision ("in master mode the PCIe x16 endpoint is enabled, in slave mode it is gated"). Variant selected at elaboration time by `FluidPopMasterConfig` / `FluidPopSlaveConfig` per PLAN.md §8.2. Ball-budget envelope ~80 PCIe balls per ADR-014. - **§Interface — BMC sideband**: purpose pinned to ADR-012 Consequences (water cooling + fine-grained per-Gemmini clock gating). - **§Behavior — Master-vs-slave selection**: fully pinned to ADR-008 Decision and PLAN.md §8.2 Config-fragment names. - **§Behavior — Boot sequence**: bring-up ordering of Rocket cores (ADR-006), DDR5 controller (ADR-005), `MultiGemminiCluster`, `InterChipFabric` endpoint (ADR-009), and `PCIeHostBridge` (ADR-008) framed against ADR-010 PopLink-training preconditions. - **§Behavior — Chip-level reset and quiescence**: non-coherent scoping pinned to ADR-011 (drain only local chip; no board-wide coherence directory to flush). - **§Behavior — Thermal/telemetry export**: purpose pinned to ADR-012 Consequences. - **§Invariants — Per-chip power envelope**: verbatim ADR-012 title (Edu: 50 W typ / 70 W max; Pro: 150 W typ / 180 W peak). - **§Invariants — BGA pin budget**: verbatim ADR-014 title; sub- allocations preserved from ADR-014 Decision (Edu preliminary); final pinout deferred to Phase 4 per ADR-014 Decision. - **§Invariants — Non-coherent memory**: verbatim ADR-011 Decision + Consequences. - **§Invariants — Single master per board**: derived from ADR-008 Decision and ADR-009 Decision. ## Open questions (recorded as `_Open question:_` in the SPEC) - DDR5 PHY signal-level pinout (CA bus, DQ/DQS lanes, `ALERT_n`, `RESET_n`, ECC byte) — pending DDR5 PHY vendor-selection ADR. - Per-port PopLink PHY bundle shape — tracks `rtl/src/pop/specs/PopLinkPHY_Behavioral.SPEC.md §Interface` (currently Status: Stub). - PCIe Gen4 x16 signal set / vendor-PHY PIPE attach / MSI-X layout — tracks `rtl/src/pop/specs/PCIeHostBridge.SPEC.md §Interface` (currently Status: Stub). - JTAG / external debug signal set, halt-on-reset behaviour — pending debug-architecture ADR. - Clock-domain decomposition (root clocks, PLL count, per-domain refclks) — pending clocking/reset ADR. - BMC sideband bus choice (I²C / SPI / PMBus) and address map — pending board-side BMC ADR. - Boot ROM location, bootloader split, PopLink training-order schedule — pending boot ADR. - Chip-level quiescence protocol (drain order, time-out behaviour, BMC visibility during in-progress quiescence) — pending clocking/reset ADR. - BMC telemetry granularity, sampling cadence, throttle-actuation contract — pending BMC ADR. ## Constraint check - [x] `**Status:**` line flipped Stub → Draft. - [x] Every TBD resolved (pin to ADR / PLAN, or recorded as `_Open question:_`). No fabricated widths or signal sets. - [x] Only `rtl/src/pop/specs/FluidPopSoC.SPEC.md` changes (ADR-017 off-limits path policy honoured). - [x] All ADR / PLAN refs from the Stub preserved (PLAN.md §8.2, §12.3, ADR-001…ADR-014, ADR-005, ADR-006, ADR-008, ADR-009, ADR-010, ADR-011, ADR-012, ADR-014); §12.7 and §8.3 added in Coverage targets are kept from the original Stub body. - [x] No sibling SPEC is currently in Draft; sibling Stubs (`PopLinkPHY_Behavioral`, `PCIeHostBridge`) are referenced only inside Open questions, never as a Draft-pin source. - [x] `## Promotion history` appended with the 2026-05-26 entry. - [x] No fabricated performance / latency / capacity / vendor commitments — every number quoted has an ADR title or Decision as source.

navigator added 1 commit 2026-05-26 01:02:08 -03:00

spec(FluidPopSoC): promote FluidPopSoC.SPEC.md to Draft ... 62853ec60a

Lifts FluidPopSoC.SPEC.md from Status: Stub to Status: Draft. No
behaviour or Chisel is added; the IO contract is pinned to ADRs that
already commit values, and signal-level details no source pins are
recorded as Open questions instead of fabricated widths.

Resolved TBDs (pinned to a source):

- §Interface DDR5 PHY — channel count pinned to ADR-005 Decision
  (Edu: 1 channel, Pro: 2 channels); ~290 DDR5 ball envelope per
  ADR-014.
- §Interface PopLink quad-port — quad N/S/E/W ports per ADR-010
  Decision; ~80 SerDes ball envelope per ADR-014.
- §Interface optional PCIe Gen4 x16 — presence rule per ADR-008
  Decision (master enabled / slave gated); variant selected by
  FluidPopMasterConfig vs FluidPopSlaveConfig per PLAN.md §8.2;
  ~80 PCIe ball envelope per ADR-014.
- §Interface BMC sideband — purpose pinned to ADR-012 Consequences
  (water cooling + per-Gemmini clock gating).
- §Behavior master/slave selection — fully pinned to ADR-008
  Decision and PLAN.md §8.2 Config-fragment names.
- §Behavior boot sequence — ordering of Rocket / DDR5 /
  MultiGemminiCluster / InterChipFabric / PCIeHostBridge bring-up
  framed by ADR-005, ADR-006, ADR-008, ADR-009, ADR-010.
- §Behavior thermal/telemetry — purpose pinned to ADR-012
  Consequences.
- §Invariants power envelope — verbatim from ADR-012 title (Edu:
  50 W typ / 70 W max; Pro: 150 W typ / 180 W peak).
- §Invariants BGA pin budget — verbatim from ADR-014 title and
  sub-allocations from ADR-014 Decision; final pinout deferred to
  Phase 4 per ADR-014 Decision.
- §Invariants non-coherent memory — verbatim ADR-011 Decision +
  Consequences.
- §Invariants single-master-per-board — derived from ADR-008
  Decision + ADR-009 Decision.

Open questions (no source pins, deferred to follow-up ADR /
sibling-SPEC Draft):

- DDR5 PHY signal-level pinout — pending DDR5 PHY vendor ADR.
- Per-port PopLink PHY bundle shape — tracks PopLinkPHY_Behavioral
  SPEC §Interface (currently Stub).
- PCIe Gen4 x16 signal set / PIPE attach / MSI-X layout — tracks
  PCIeHostBridge SPEC §Interface (currently Stub).
- JTAG / debug signal set — pending debug-architecture ADR.
- Clock-domain decomposition + chip-level quiescence handshake —
  pending clocking/reset ADR.
- BMC sideband bus choice (I²C / SPI / PMBus) and address map —
  pending board-side BMC ADR.
- Boot ROM location, bootloader split, PopLink training-order
  schedule — pending boot ADR.
- Quiescence protocol (per-block drain order, time-out behaviour) —
  pending clocking/reset ADR.
- BMC telemetry granularity, sampling cadence, throttle contract —
  pending BMC ADR.

Constraints honoured:
- Only rtl/src/pop/specs/FluidPopSoC.SPEC.md changes (ADR-017).
- All ADR / PLAN refs from the Stub are preserved (PLAN §8.2,
  §12.3, ADR-001…ADR-014, ADR-005, ADR-006, ADR-008, ADR-009,
  ADR-010, ADR-011, ADR-012, ADR-014).
- No fabricated widths, latencies, vendor commitments, or
  schedule promises.
- No sibling SPEC is currently in Draft, so no sibling Draft is
  used as a pin; sibling Stubs (PopLinkPHY_Behavioral,
  PCIeHostBridge) are referenced only inside Open questions.

navigator added the

ready-for-review

label 2026-05-26 01:02:17 -03:00

navigator commented 2026-05-26 01:13:05 -03:00

Author

Owner

Copy link

VERDICT: PASS

PR #87 promotes rtl/src/pop/specs/FluidPopSoC.SPEC.md from Stub to Draft, expanding the three TBD blocks (§Interface, §Behavior, §Invariants) into ADR-anchored content while keeping every unresolved detail honestly parked as _Open question:_. Mechanical guardrails pass: existing SPDX header preserved (diff starts at line 4), single file touched, no AI/Anthropic attribution, no off-limits paths (the file is in rtl/src/pop/specs/, not in the ADR-017 list), no Chisel module so rules 4–6 don't apply. The missing Closes # is explained transparently in the PR body — this PR comes from the autonomous spec-designer role which runs without a per-promotion tracking issue, and the scope is logically constrained to a single SPEC promotion. Rule 7 is the critical one here and the PR handles it carefully: every concrete number is presented as a direct quote from an ADR Decision/Consequences/title or a PLAN.md section, and the BGA sub-allocations (~600 P/G + 290 DDR5 + 80 PopLink + 80 PCIe = 1050 + remainder ≈ 1100) check out arithmetically against the ~1100-ball Edu budget. Every numerical claim that appears reconciles with already-approved PRs in this thread: 50/70 W Edu and 150/180 W Pro power envelopes (ADR-012, matches PR #83/#88/#89); ~1100/1500 BGA balls (ADR-014, matches PR #83/#88/#89); ~35×35 mm Edu / ~40×40 mm Pro package (ADR-014 Consequences, matches PR #89's attribution to PLAN.md §2.2); 1 DDR5 channel Edu / 2 channels Pro at up to 32 GiB / 128 GiB (ADR-005, matches PR #89); 2 RV64GC Rocket cores on Edu / 4 on Pro (ADR-006, matches PR #89). New specific numbers introduced (~290 DDR5 balls, ~80 PopLink SerDes balls, ~80 PCIe balls) are presented as verbatim quotes from ADR-014's Decision section. The Open Questions list is comprehensive — DDR5 PHY signal-level pinout, per-port PopLink shape, PCIe signal set, JTAG architecture, clock-domain decomposition, BMC bus choice, boot ROM location, quiescence protocol, telemetry granularity — every facet that no current ADR/PLAN pins gets parked rather than fabricated. The Promotion history entry (2026-05-26: Stub → Draft) is appropriate.

Findings

None.

<!-- agent:review verdict=PASS ts=1779768785 --> **VERDICT:** PASS PR #87 promotes `rtl/src/pop/specs/FluidPopSoC.SPEC.md` from Stub to Draft, expanding the three TBD blocks (§Interface, §Behavior, §Invariants) into ADR-anchored content while keeping every unresolved detail honestly parked as `_Open question:_`. Mechanical guardrails pass: existing SPDX header preserved (diff starts at line 4), single file touched, no AI/Anthropic attribution, no off-limits paths (the file is in `rtl/src/pop/specs/`, not in the ADR-017 list), no Chisel module so rules 4–6 don't apply. The missing `Closes #` is explained transparently in the PR body — this PR comes from the autonomous `spec-designer` role which runs without a per-promotion tracking issue, and the scope is logically constrained to a single SPEC promotion. Rule 7 is the critical one here and the PR handles it carefully: every concrete number is presented as a direct quote from an ADR Decision/Consequences/title or a PLAN.md section, and the BGA sub-allocations (~600 P/G + 290 DDR5 + 80 PopLink + 80 PCIe = 1050 + remainder ≈ 1100) check out arithmetically against the ~1100-ball Edu budget. Every numerical claim that appears reconciles with already-approved PRs in this thread: 50/70 W Edu and 150/180 W Pro power envelopes (ADR-012, matches PR #83/#88/#89); ~1100/1500 BGA balls (ADR-014, matches PR #83/#88/#89); ~35×35 mm Edu / ~40×40 mm Pro package (ADR-014 Consequences, matches PR #89's attribution to PLAN.md §2.2); 1 DDR5 channel Edu / 2 channels Pro at up to 32 GiB / 128 GiB (ADR-005, matches PR #89); 2 RV64GC Rocket cores on Edu / 4 on Pro (ADR-006, matches PR #89). New specific numbers introduced (~290 DDR5 balls, ~80 PopLink SerDes balls, ~80 PCIe balls) are presented as verbatim quotes from ADR-014's Decision section. The Open Questions list is comprehensive — DDR5 PHY signal-level pinout, per-port PopLink shape, PCIe signal set, JTAG architecture, clock-domain decomposition, BMC bus choice, boot ROM location, quiescence protocol, telemetry granularity — every facet that no current ADR/PLAN pins gets parked rather than fabricated. The Promotion history entry (2026-05-26: Stub → Draft) is appropriate. ## Findings _None._

navigator added the

review:pass

label 2026-05-26 01:13:06 -03:00

fluidpop-bot approved these changes 2026-05-26 01:13:29 -03:00

Dismissed

fluidpop-bot left a comment

Collaborator

Copy link

CI green (head 62853ec60a), auto-approving

CI green (head 62853ec60ae66e722e36020224e721e5aea59c1d), auto-approving

navigator force-pushed spec/fluidpopsoc-draft from 62853ec60a to 017531fc14 2026-05-26 01:13:32 -03:00 Compare

fluidpop-bot approved these changes 2026-05-26 01:14:14 -03:00

fluidpop-bot left a comment

Collaborator

Copy link

CI green (head 017531fc14), auto-approving

CI green (head 017531fc14aa964e30005fcece5c2872744f97d9), auto-approving

navigator merged commit 7447b3efd8 into main 2026-05-26 01:14:15 -03:00

navigator referenced this pull request from a commit 2026-05-26 01:14:15 -03:00

spec(FluidPopSoC): promote FluidPopSoC.SPEC.md to Draft (#87)

navigator referenced this pull request 2026-05-26 01:19:52 -03:00

spec(InterChipFabric): promote InterChipFabric.SPEC.md to Draft #91

navigator referenced this pull request 2026-05-26 01:36:34 -03:00

spec(InterGemminiXbar): promote InterGemminiXbar.SPEC.md to Draft #92

navigator referenced this pull request 2026-05-26 01:55:20 -03:00

spec(MultiGemminiCluster): promote MultiGemminiCluster.SPEC.md to Draft #93

navigator referenced this pull request 2026-05-26 02:09:55 -03:00

spec(PCIeHostBridge): promote PCIeHostBridge.SPEC.md to Draft #94

navigator referenced this pull request 2026-05-26 02:26:28 -03:00

spec(PopLinkPHY_Behavioral): promote PopLinkPHY_Behavioral.SPEC.md to Draft #95

navigator referenced this pull request 2026-05-26 02:43:17 -03:00

spec(PopRoCCRouter): promote PopRoCCRouter.SPEC.md to Draft #96

navigator referenced this pull request 2026-05-26 02:59:54 -03:00

spec(PopSoCConfig): promote PopSoCConfig.SPEC.md to Draft #97

Sign in to join this conversation.

Reviewers

No reviewers

fluidpop-bot

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

2 participants

Notifications

Subscribe

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!87

No description provided.