docs(spec): draft PopLink PHY interface skeleton (poplink-phy-if.md) #75

Merged

navigator merged 1 commit from auto/issue-71-20260525T224356Z_issue71 into main

2026-05-25 19:51:26 -03:00

navigator commented

2026-05-25 19:47:49 -03:00

Owner

Summary

Expands docs/spec/poplink-phy-if.md from the 10-line stub into the PLAN.md §13.4 Phase-1 PHY deliverable #2 skeleton. The doc pins the PopLinkPHYIO Chisel bundle surface so upper-layer fabric work and the behavioral PHY (issue #51) can converge against a stable contract while PHY option selection (issue #6) is still open.

What is in the skeleton

Status / Owner header — Status: Draft skeleton, Owner: TBD, with explicit PLAN.md and companion-artifact refs.
Eight required sections (one per acceptance-criteria bullet):
1. Purpose & scope (decouples PHY from upper layers per §13.3)
2. Bundle signals — placeholder table covering TX/RX data + handshakes, lane status, reset/init handshake, training control, error flags, BER reporting hook, calibration ctrl/status. Widths are all TBD — no fabricated numbers.
3. Lane configuration — sizing-exploration ranges only for N / W / R, no commitments.
4. Clock & reset domains — PHY-side vs MAC-side split, CDC discipline mandate.
5. Init / training sequence — five-state FSM sketch, no timing numbers.
6. Error reporting — BER hook wired to §12.4 ARQ stress requirements.
7. Behavioral-PHY simulation contract — what PopLinkPHY_Behavioral.scala must do to satisfy this interface.
8. Open questions — seeded with the lane-count / Gb/s / width questions deferred to issue #6.
TODO markers on every section (9 in total) with a short intent description for fill-in.
References block linking PLAN.md §13.3 / §13.4 / §12.4, ADR-009, the behavioral SPEC, and issues #51 / #6.

Why now

InterChipFabric and the behavioral PHY (issue #51) need a written contract to converge on; without it, the bundle drifts between the Scala source and the spec text. This file pins the surface vendor-neutrally so PHY-1 / PHY-2 / PHY-3 option selection in issue #6 cannot be biased by pre-commitments here.

Acceptance criteria

docs/spec/poplink-phy-if.md exists with the sections above
Status: Draft skeleton + Owner: TBD header
Each section has TODO markers and short intent description
Bundle-signal table has placeholder rows (no fabricated widths/timings)
Cross-references PopLinkPHY_Behavioral.scala skeleton issue (#51) and the existing PHY options survey issue (#6)
No commitments on lane count or Gb/s — those depend on PHY option selection
References PLAN.md §13.3, §13.4, §12.4 explicitly

Out of scope

Concrete lane count, per-lane width, per-lane line rate (deferred to issue #6 outcome).
Analog circuit-design choices (channel-loss / jitter budget, EQ topology) — those belong in docs/phy/phy-options.md and the eventual board thermal analysis.
Pinout / package electrical detail — that lands in docs/spec/pop-soc-v1.md / pop-accel-8-board-v1.md once the PHY option is chosen.
The behavioral PHY Scala source itself — tracked in #51.

Closes #71

## Summary Expands `docs/spec/poplink-phy-if.md` from the 10-line stub into the PLAN.md §13.4 Phase-1 PHY deliverable #2 skeleton. The doc pins the `PopLinkPHYIO` Chisel bundle surface so upper-layer fabric work and the behavioral PHY (issue #51) can converge against a stable contract while PHY option selection (issue #6) is still open. ## What is in the skeleton - **Status / Owner header** — `Status: Draft skeleton`, `Owner: TBD`, with explicit PLAN.md and companion-artifact refs. - **Eight required sections** (one per acceptance-criteria bullet): 1. Purpose & scope (decouples PHY from upper layers per §13.3) 2. Bundle signals — placeholder table covering TX/RX data + handshakes, lane status, reset/init handshake, training control, error flags, BER reporting hook, calibration ctrl/status. Widths are all `TBD` — no fabricated numbers. 3. Lane configuration — sizing-exploration *ranges only* for N / W / R, no commitments. 4. Clock & reset domains — PHY-side vs MAC-side split, CDC discipline mandate. 5. Init / training sequence — five-state FSM sketch, no timing numbers. 6. Error reporting — BER hook wired to §12.4 ARQ stress requirements. 7. Behavioral-PHY simulation contract — what `PopLinkPHY_Behavioral.scala` must do to satisfy this interface. 8. Open questions — seeded with the lane-count / Gb/s / width questions deferred to issue #6. - **TODO markers** on every section (9 in total) with a short intent description for fill-in. - **References block** linking PLAN.md §13.3 / §13.4 / §12.4, ADR-009, the behavioral SPEC, and issues #51 / #6. ## Why now `InterChipFabric` and the behavioral PHY (issue #51) need a written contract to converge on; without it, the bundle drifts between the Scala source and the spec text. This file pins the surface vendor-neutrally so PHY-1 / PHY-2 / PHY-3 option selection in issue #6 cannot be biased by pre-commitments here. ## Acceptance criteria - [x] `docs/spec/poplink-phy-if.md` exists with the sections above - [x] `Status: Draft skeleton` + `Owner: TBD` header - [x] Each section has `TODO` markers and short intent description - [x] Bundle-signal table has placeholder rows (no fabricated widths/timings) - [x] Cross-references `PopLinkPHY_Behavioral.scala` skeleton issue (#51) and the existing PHY options survey issue (#6) - [x] No commitments on lane count or Gb/s — those depend on PHY option selection - [x] References PLAN.md §13.3, §13.4, §12.4 explicitly ## Out of scope - Concrete lane count, per-lane width, per-lane line rate (deferred to issue #6 outcome). - Analog circuit-design choices (channel-loss / jitter budget, EQ topology) — those belong in `docs/phy/phy-options.md` and the eventual board thermal analysis. - Pinout / package electrical detail — that lands in `docs/spec/pop-soc-v1.md` / `pop-accel-8-board-v1.md` once the PHY option is chosen. - The behavioral PHY Scala source itself — tracked in #51. Closes #71

navigator added 1 commit

2026-05-25 19:47:49 -03:00

docs(spec): draft PopLink PHY interface skeleton (poplink-phy-if.md)

build / scalafmt-check (pull_request) Successful in 4s

Details

build / sbt-compile (pull_request) Successful in 3s

Details

build / shell-lint (pull_request) Successful in 11s

Details

5acdd2fc8d

Expands the stub at docs/spec/poplink-phy-if.md into the PLAN.md §13.4
Phase-1 PHY deliverable #2 skeleton. Enumerates the PopLinkPHYIO bundle
contract (signals, lane config, clock/reset domains, init/training FSM,
error reporting hooks, behavioral-PHY contract, open questions) so that
upper-layer fabric work can proceed against a stable surface while PHY
option selection (issue #6) is still in flight.

Why now: InterChipFabric and the behavioral PHY (issue #51) need a
written contract to converge on; without it, the bundle drifts between
the Scala source and the spec text. This file pins the surface vendor-
neutrally — no lane count, no Gb/s, no widths — so PHY-1 / PHY-2 / PHY-3
option selection in issue #6 cannot be biased by pre-commitments here.

Cross-references PLAN.md §13.3 / §13.4 / §12.4, ADR-009, issue #51
(behavioral PHY skeleton), issue #6 (PHY options outreach).

navigator added the

ready-for-review

label

2026-05-25 19:47:57 -03:00

navigator commented

2026-05-25 19:50:18 -03:00

Author

Owner

VERDICT: PASS

This is a docs-only PR that expands docs/spec/poplink-phy-if.md from a 10-line stub into the §13.4 Phase-1 deliverable #2 skeleton, scoped to exactly one file matching issue #71. The expansion is careful about every guardrail that matters here: widths in the bundle-signals table are uniformly TBD, lane count / per-lane rate / per-lane width are explicitly enumerated only as "sizing exploration ranges (not commitments)" deferred to issue #6, and timing numbers are absent from the init/training FSM sketch. PLAN.md citations (§3 aggregate bandwidths, §13.2 PHY-1 Gb/s range, §12.4 raw BER target) are presented as references back to PLAN, not as fabricated numbers minted in this doc. Every section ends with a TODO describing fill-in intent, and the open-questions §8 names which upstream work closes each. The existing SPDX header on the .md file is preserved (diff starts at line 3, header at lines 1–2 untouched). Path is docs/spec/** — not in the ADR-017 off-limits list — and there is no AI/Anthropic attribution anywhere. No Chisel module is added, so rules 4–6 (SPEC compliance, package consistency, test scaffold) do not apply.

Findings

None.

**VERDICT:** PASS This is a docs-only PR that expands `docs/spec/poplink-phy-if.md` from a 10-line stub into the §13.4 Phase-1 deliverable #2 skeleton, scoped to exactly one file matching issue #71. The expansion is careful about every guardrail that matters here: widths in the bundle-signals table are uniformly `TBD`, lane count / per-lane rate / per-lane width are explicitly enumerated only as "sizing exploration ranges (not commitments)" deferred to issue #6, and timing numbers are absent from the init/training FSM sketch. PLAN.md citations (§3 aggregate bandwidths, §13.2 PHY-1 Gb/s range, §12.4 raw BER target) are presented as references back to PLAN, not as fabricated numbers minted in this doc. Every section ends with a `TODO` describing fill-in intent, and the open-questions §8 names which upstream work closes each. The existing SPDX header on the .md file is preserved (diff starts at line 3, header at lines 1–2 untouched). Path is `docs/spec/**` — not in the ADR-017 off-limits list — and there is no AI/Anthropic attribution anywhere. No Chisel module is added, so rules 4–6 (SPEC compliance, package consistency, test scaffold) do not apply. ## Findings _None._

navigator added the

review:pass

label

2026-05-25 19:50:18 -03:00