docs(spec): rewrite pop-soc-v1.md as Draft skeleton #89

Merged

navigator merged 1 commit from auto/issue-84-20260526T040021Z_issue84 into main

2026-05-26 01:11:12 -03:00

navigator commented

2026-05-26 01:04:01 -03:00

Owner

Summary

Promotes docs/spec/pop-soc-v1.md from a single-paragraph Stub into a Draft-skeleton chip specification with the 11 sections enumerated in issue #84 (Overview → Open questions).
Each section ends with a TODO marker and a 2-3 line intent description.
Explicit ADR cross-references: ADR-001 through ADR-007, plus ADR-008 (designated master), ADR-009 (PopLink), ADR-012 (power envelope), ADR-014 (BGA pin budget).
Cross-references PLAN.md §10 (deliverable #1), §8.1 (chip-level ADRs), §8.2 (custom Chisel modules), §13.3 (PHY decoupling), and the companion specs poplink-phy-if.md, pop-accel-8-board-v1.md, programming-model.md, driver-design.md.
No fabricated numbers — all cited frequencies, dimensions, and power values trace back to ADR text or PLAN.md. Pre-commits to structure, not to numbers; flags the §2.2 vs ADR-012 envelope-versus-working-point reconciliation as an explicit open question.

Notes

Status: Draft skeleton / Owner: TBD — matches the pattern of poplink-phy-if.md and programming-model.md.
Diff is +122 / -3 lines, well under the 600-LOC ceiling.

Closes #84.

## Summary - Promotes `docs/spec/pop-soc-v1.md` from a single-paragraph Stub into a Draft-skeleton chip specification with the 11 sections enumerated in issue #84 (Overview → Open questions). - Each section ends with a `TODO` marker and a 2-3 line intent description. - Explicit ADR cross-references: ADR-001 through ADR-007, plus ADR-008 (designated master), ADR-009 (PopLink), ADR-012 (power envelope), ADR-014 (BGA pin budget). - Cross-references PLAN.md §10 (deliverable #1), §8.1 (chip-level ADRs), §8.2 (custom Chisel modules), §13.3 (PHY decoupling), and the companion specs `poplink-phy-if.md`, `pop-accel-8-board-v1.md`, `programming-model.md`, `driver-design.md`. - No fabricated numbers — all cited frequencies, dimensions, and power values trace back to ADR text or PLAN.md. Pre-commits to structure, not to numbers; flags the §2.2 vs ADR-012 envelope-versus-working-point reconciliation as an explicit open question. ## Notes - Status: `Draft skeleton` / Owner: `TBD` — matches the pattern of `poplink-phy-if.md` and `programming-model.md`. - Diff is +122 / -3 lines, well under the 600-LOC ceiling. Closes #84.

navigator added 1 commit

2026-05-26 01:04:01 -03:00

docs(spec): rewrite pop-soc-v1.md as Draft skeleton

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 11s

Details

65c77ba58c

Promotes the single-paragraph Stub at docs/spec/pop-soc-v1.md into a
Draft-skeleton chip specification that gathers the chip-level ADRs
(ADR-001..ADR-007, ADR-008, ADR-009, ADR-012, ADR-014) into one
contributor-facing document so RTL, synthesis, and supply-chain work
share a canonical chip reference (PLAN.md Section 10 deliverable #1).

The doc commits to structure, not numbers — every section ends with a
TODO marker, and frequency / die-area / per-block power figures are
deliberately left to flow from the synthesis flow (PLAN.md Section 9)
and from ADRs as they move from Proposed/Draft to Accepted. All cited
values trace back to ADR text or PLAN.md.

Closes #84.

navigator added the

ready-for-review

label

2026-05-26 01:04:10 -03:00

navigator commented

2026-05-26 01:10:10 -03:00

Author

Owner

VERDICT: PASS

PR #89 promotes docs/spec/pop-soc-v1.md from one-paragraph stub to an 11-section Draft skeleton, mirroring the structure now established by programming-model.md, poplink-phy-if.md, and pop-accel-8-board-v1.md (PR #88). All mechanical guardrails pass: existing CC-BY-SA-4.0 SPDX header preserved (diff starts at line 4), single file touched matching Issue #84, no AI/Anthropic attribution, no off-limits paths, no Chisel module so rules 4–6 don't apply. Every section ends with a TODO marker plus 2-3 line intent, every numeric claim is anchored to an ADR or PLAN.md section, and where attribution would invite drift the section explicitly defers ("Pin the per-block power breakdown once synthesis flow produces numbers", "treat L2 sizing as a Chipyard default to be measured, not declared"). Cross-checking the numerical claims against prior approved PRs: 50/70 W Edu envelope and ~1100/1500 BGA from ADR-012/ADR-014 match PR #83 and PR #88; 4 Gemminis (ADR-001), 16×16 INT8 systolic (ADR-002), 4×4 xbar (ADR-003), 256 KiB scratchpad (ADR-004), 2 RV64GC Rocket cores (ADR-006), 4 PopLink fabric ports per ADR-009 match the SPEC citations seen in PR #69, PR #81, PR #82, PR #83. Math-verifiable claims check: 16×16×4 = 1024 PEs/chip, DDR5-5600 → 5600 MT/s × 8 bytes = 44.8 GB/s (~45 GB/s), 8 channels × 45 = ~360 GB/s aggregate. Pro-variant cites are consistent (16 Gemminis × 32×32 systolic per PLAN.md §2.2 Config B; 150/180 W from ADR-012 alt). The board-total ~500 W typ / ~700 W peak from PLAN.md §2.6 vs. PR #88's chip-only ~400/~560 W reconciles cleanly when DDR5+BMC+PHY+conversion losses are included, which PR #88 had explicitly excluded. The "envelope vs. working point" tension between ADR-012 (50/70 W) and Configuration A's 5–15 W bring-up range is honestly parked as Open Question #6 rather than silently chosen, the master/slave SKU question (single SKU with NC pins vs. two SKUs) is honestly parked as Open Question #5, and the PopLink (N, W, R) tuple is deferred to the PHY option selection rather than fabricated.

Findings

None.

**VERDICT:** PASS PR #89 promotes `docs/spec/pop-soc-v1.md` from one-paragraph stub to an 11-section Draft skeleton, mirroring the structure now established by `programming-model.md`, `poplink-phy-if.md`, and `pop-accel-8-board-v1.md` (PR #88). All mechanical guardrails pass: existing `CC-BY-SA-4.0` SPDX header preserved (diff starts at line 4), single file touched matching Issue #84, no AI/Anthropic attribution, no off-limits paths, no Chisel module so rules 4–6 don't apply. Every section ends with a TODO marker plus 2-3 line intent, every numeric claim is anchored to an ADR or PLAN.md section, and where attribution would invite drift the section explicitly defers ("Pin the per-block power breakdown once synthesis flow produces numbers", "treat L2 sizing as a Chipyard default to be measured, not declared"). Cross-checking the numerical claims against prior approved PRs: 50/70 W Edu envelope and ~1100/1500 BGA from ADR-012/ADR-014 match PR #83 and PR #88; 4 Gemminis (ADR-001), 16×16 INT8 systolic (ADR-002), 4×4 xbar (ADR-003), 256 KiB scratchpad (ADR-004), 2 RV64GC Rocket cores (ADR-006), 4 PopLink fabric ports per ADR-009 match the SPEC citations seen in PR #69, PR #81, PR #82, PR #83. Math-verifiable claims check: 16×16×4 = 1024 PEs/chip, DDR5-5600 → 5600 MT/s × 8 bytes = 44.8 GB/s (~45 GB/s), 8 channels × 45 = ~360 GB/s aggregate. Pro-variant cites are consistent (16 Gemminis × 32×32 systolic per PLAN.md §2.2 Config B; 150/180 W from ADR-012 alt). The board-total ~500 W typ / ~700 W peak from PLAN.md §2.6 vs. PR #88's chip-only ~400/~560 W reconciles cleanly when DDR5+BMC+PHY+conversion losses are included, which PR #88 had explicitly excluded. The "envelope vs. working point" tension between ADR-012 (50/70 W) and Configuration A's 5–15 W bring-up range is honestly parked as Open Question #6 rather than silently chosen, the master/slave SKU question (single SKU with NC pins vs. two SKUs) is honestly parked as Open Question #5, and the PopLink (N, W, R) tuple is deferred to the PHY option selection rather than fabricated. ## Findings _None._

navigator added the

review:pass

label

2026-05-26 01:10:10 -03:00