rtl: PopLinkPHY_Behavioral skeleton + chiseltest elaborate #106

Merged

navigator merged 1 commit from auto/issue-51-20260526T163356Z_issue51 into main

2026-05-26 13:45:25 -03:00

navigator commented

2026-05-26 13:40:57 -03:00

Owner

Closes #51

Summary

Scaffold PopLinkPHY_Behavioral per rtl/src/pop/specs/PopLinkPHY_Behavioral.SPEC.md (Status: Draft) so PLAN.md §13.4 deliverable #1 has a buildable Chisel module sitting behind the canonical PopLinkPHYIO bundle. Skeleton + elaborate only — behaviour, BER injection, training FSM, the // synthesis translate_off equivalent guard and Chisel construction parameters all stay as documented // TBD per SPEC §... blocks, per PLAN.md §12.3 step 1 (elaborate-before-behaviour) and the rule "no fabricated values for spec TBD items".

Files

rtl/src/pop/PopLinkPHY_Behavioral.scala — Module + PopLinkPHYIO bundle. Bundle is grouped into five sub-bundles matching the docs/spec/poplink-phy-if.md §2 signal-class enumeration that SPEC §Interface bullet 1 cross-references: tx, rx, status, resetTrain, cal. Only the four signals whose widths poplink-phy-if §2 pins concretely at 1 bit (phy_reset_req / phy_reset_ack, train_req / train_done) are materialised as Bool(); every other signal class stays empty with a // TBD per SPEC §Interface comment that points at the relevant Open question (lane count N, per-lane data widths, err_flags bit map, ber_count per-lane-vs-aggregated, cal_ctrl / cal_status widths). Output defaults (phyResetAck := false.B, trainDone := false.B) match POR / quiet state per poplink-phy-if §5 step 1 — no behaviour committed beyond the §12.3 elaboration contract.

SPDX header: CHARRUA-1.2.
rtl/tests/PopLinkPHY_Behavioral/PopLinkPHY_BehavioralSpec.scala — chiseltest AnyFlatSpec with behavior of "PopLinkPHY_Behavioral" and the single it should "elaborate" case, matching the established per-module bench skeleton (PopRoCCRouterSpec, InterGemminiXbarSpec, PCIeHostBridgeSpec, PopSoCConfigSpec, FluidPopSoCSpec).

SPDX header: AGPL-3.0-or-later.

Acceptance criteria (#51)

rtl/src/pop/PopLinkPHY_Behavioral.scala exists, compiles under Chipyard 1.13.0 with sbt compile green.
IO bundle reflects the §Interface section of PopLinkPHY_Behavioral.SPEC.md; TBD fields annotated with // TBD per SPEC §Interface comments and held back from invented widths.
Module is a leaf (per issue body) — no parent wiring required.
rtl/tests/PopLinkPHY_Behavioral/PopLinkPHY_BehavioralSpec.scala exists with a chiseltest AnyFlatSpec skeleton + at least one should "elaborate" test.
Headers preserved: CHARRUA-1.2 on the Scala source, AGPL-3.0-or-later on the test.
No fabricated values for spec TBD items.

Validation (local, agent host)

sbt compile — green (6 Scala sources compiled).
sbt test — green (6 specs, 6 passed, including PopLinkPHY_BehavioralSpec).

Versions are the pinned Chipyard 1.13.0 set (rtl/build.sbt): Scala 2.13.12 / Chisel 6.5.0 / chiseltest 6.0.0. No Chipyard checkout required — rtl/ resolves these from Maven Central.

Out of scope (deferred to follow-up issues)

Behavioural model (bit-exact passthrough at BER = 0; configurable BER injection for §12.4 10⁻⁶ raw-BER stress; degenerate training / link-up FSM per poplink-phy-if §5; optional drop / re-order knobs).
// synthesis translate_off equivalent guard (SPEC §Invariants).
Chisel construction parameters (line rate, latency, BER, drop / re-order) — SPEC §Interface bullet 2 explicitly leaves defaults as an Open question pending PHY-option selection (PLAN.md §13.2).
Coverage runs (§Coverage targets is a Phase-3 close obligation).
Pinning PopLinkPHYIO widths, lane count N, training FSM timing — that work belongs to the PHY interface skeleton track (Phase-1 PHY deliverable #2).

Off-limits (ADR-017)

No ADR-017 off-limits paths touched. No pre-commit hook bypass.

Closes #51 ## Summary Scaffold `PopLinkPHY_Behavioral` per `rtl/src/pop/specs/PopLinkPHY_Behavioral.SPEC.md` (Status: Draft) so PLAN.md §13.4 deliverable #1 has a buildable Chisel module sitting behind the canonical `PopLinkPHYIO` bundle. Skeleton + elaborate only — behaviour, BER injection, training FSM, the `// synthesis translate_off` equivalent guard and Chisel construction parameters all stay as documented `// TBD per SPEC §...` blocks, per PLAN.md §12.3 step 1 (elaborate-before-behaviour) and the rule "no fabricated values for spec TBD items". ## Files - `rtl/src/pop/PopLinkPHY_Behavioral.scala` — `Module` + `PopLinkPHYIO` bundle. Bundle is grouped into five sub-bundles matching the `docs/spec/poplink-phy-if.md §2` signal-class enumeration that SPEC §Interface bullet 1 cross-references: `tx`, `rx`, `status`, `resetTrain`, `cal`. Only the four signals whose widths `poplink-phy-if §2` pins concretely at 1 bit (`phy_reset_req` / `phy_reset_ack`, `train_req` / `train_done`) are materialised as `Bool()`; every other signal class stays empty with a `// TBD per SPEC §Interface` comment that points at the relevant Open question (lane count `N`, per-lane data widths, `err_flags` bit map, `ber_count` per-lane-vs-aggregated, `cal_ctrl` / `cal_status` widths). Output defaults (`phyResetAck := false.B`, `trainDone := false.B`) match POR / quiet state per `poplink-phy-if §5` step 1 — no behaviour committed beyond the §12.3 elaboration contract. SPDX header: `CHARRUA-1.2`. - `rtl/tests/PopLinkPHY_Behavioral/PopLinkPHY_BehavioralSpec.scala` — chiseltest `AnyFlatSpec` with `behavior of "PopLinkPHY_Behavioral"` and the single `it should "elaborate"` case, matching the established per-module bench skeleton (`PopRoCCRouterSpec`, `InterGemminiXbarSpec`, `PCIeHostBridgeSpec`, `PopSoCConfigSpec`, `FluidPopSoCSpec`). SPDX header: `AGPL-3.0-or-later`. ## Acceptance criteria (#51) - [x] `rtl/src/pop/PopLinkPHY_Behavioral.scala` exists, compiles under Chipyard 1.13.0 with `sbt compile` green. - [x] IO bundle reflects the §Interface section of `PopLinkPHY_Behavioral.SPEC.md`; TBD fields annotated with `// TBD per SPEC §Interface` comments and held back from invented widths. - [x] Module is a leaf (per issue body) — no parent wiring required. - [x] `rtl/tests/PopLinkPHY_Behavioral/PopLinkPHY_BehavioralSpec.scala` exists with a chiseltest `AnyFlatSpec` skeleton + at least one `should "elaborate"` test. - [x] Headers preserved: `CHARRUA-1.2` on the Scala source, `AGPL-3.0-or-later` on the test. - [x] No fabricated values for spec TBD items. ## Validation (local, agent host) - `sbt compile` — green (6 Scala sources compiled). - `sbt test` — green (6 specs, 6 passed, including `PopLinkPHY_BehavioralSpec`). Versions are the pinned Chipyard 1.13.0 set (`rtl/build.sbt`): Scala 2.13.12 / Chisel 6.5.0 / chiseltest 6.0.0. No Chipyard checkout required — `rtl/` resolves these from Maven Central. ## Out of scope (deferred to follow-up issues) - Behavioural model (bit-exact passthrough at BER = 0; configurable BER injection for §12.4 10⁻⁶ raw-BER stress; degenerate training / link-up FSM per `poplink-phy-if §5`; optional drop / re-order knobs). - `// synthesis translate_off` equivalent guard (SPEC §Invariants). - Chisel construction parameters (line rate, latency, BER, drop / re-order) — SPEC §Interface bullet 2 explicitly leaves defaults as an Open question pending PHY-option selection (PLAN.md §13.2). - Coverage runs (§Coverage targets is a Phase-3 close obligation). - Pinning `PopLinkPHYIO` widths, lane count `N`, training FSM timing — that work belongs to the PHY interface skeleton track (Phase-1 PHY deliverable #2). ## Off-limits (ADR-017) No ADR-017 off-limits paths touched. No pre-commit hook bypass.

navigator added 1 commit

2026-05-26 13:40:57 -03:00

rtl: PopLinkPHY_Behavioral skeleton + chiseltest elaborate

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

Details

b232b52787

Scaffold the Phase-1 stand-in PHY required by PLAN.md §13.4 deliverable
#1 so that `InterChipFabric` simulation can target a real Chisel module
through the `PopLinkPHYIO` bundle that the production PHY will later
expose (PLAN.md §13.3 invariant — same surface for behavioral and
production PHY).

- `rtl/src/pop/PopLinkPHY_Behavioral.scala` — `Module` skeleton +
  `PopLinkPHYIO` enumerated as five sub-bundles per the §Interface
  signal-class enumeration cross-referenced in `docs/spec/poplink-phy-if
  §2` (tx / rx / status / resetTrain / cal). Only the four control
  signals whose widths poplink-phy-if §2 pins concretely at 1 bit
  (`phy_reset_req` / `phy_reset_ack`, `train_req` / `train_done`) are
  materialised as `Bool()`. Every TBD signal stays as a documented
  `// TBD per SPEC §Interface` block — no per-lane data widths, no
  lane count `N`, no error-flag bit map, no `ber_count` counter width
  are invented ahead of the PHY-option selection (PLAN.md §13.2) and
  the Open questions tracked in `poplink-phy-if §8` / SPEC §Interface.
  Output defaults (`phyResetAck := false.B`, `trainDone := false.B`)
  match POR / quiet state per `poplink-phy-if §5` step 1. SPEC §Behavior
  (passthrough, BER injection, training FSM, drop / re-order knobs) and
  §Invariants (`// synthesis translate_off` equivalent guard) are left
  as follow-up issues per §12.3 skeleton-first ordering.

- `rtl/tests/PopLinkPHY_Behavioral/PopLinkPHY_BehavioralSpec.scala` —
  chiseltest `AnyFlatSpec` skeleton with `should "elaborate"`, matching
  the existing per-module bench precedent (PopRoCCRouterSpec,
  InterGemminiXbarSpec, etc.).

Headers: `SPDX-License-Identifier: CHARRUA-1.2` on the Scala source,
`SPDX-License-Identifier: AGPL-3.0-or-later` on the test, per project
licensing convention.

Module is a leaf — no parent wiring required.

Local validation (agent host, sbt 1.10.7 / Scala 2.13.12, versions pinned
to Chipyard 1.13.0 in `rtl/build.sbt`):
- `sbt compile` — green (6 Scala sources).
- `sbt test`    — green (6 specs, 6 passed).

navigator added the

ready-for-review

label

2026-05-26 13:41:07 -03:00

navigator commented

2026-05-26 13:43:23 -03:00

Author

Owner

VERDICT: PASS

PR #106 adds the §12.3 step-1 scaffold for PopLinkPHY_Behavioral — Chisel module + chiseltest harness — and is exceptionally well-disciplined throughout. Mechanical guardrails all pass: SPDX headers correct (CHARRUA-1.2 for the RTL source, AGPL-3.0-or-later for the test), both files in package pop matching the canonical package, chiseltest bench has the prescribed it should "elaborate" floor, scope matches Issue #51 (two new files), no AI/Anthropic attribution, no off-limits paths. The IO bundle structure mirrors the SPEC's reference to docs/spec/poplink-phy-if.md §2 signal-class enumeration as five sub-bundles (tx, rx, status, resetTrain, cal) — exactly the right grouping. Rule 4 + rule 7 are handled with surgical precision: only the four control signals whose widths poplink-phy-if §2 pins concretely at 1 bit (phy_reset_req, phy_reset_ack, train_req, train_done) are materialised as Bool() in PopLinkResetTrainIO; every other signal class (TX/RX data, lane_status, err_flags, ber_count, cal_ctrl, cal_status) stays as a // TBD per SPEC §Interface comment with an explicit forward-link to the Open question that tracks its width (PHY-option selection PLAN.md §13.2, poplink-phy-if §3/§6/§8 Open questions). No lane count N, no per-lane data widths, no err_flags bit-map, no ber_count counter width invented ahead of the PHY-option selection — exactly the discipline rule 7 requires. The output defaults (phyResetAck := false.B, trainDone := false.B) are well-justified as the POR/quiet state per poplink-phy-if §5 step 1 ("All TX/RX disabled. lane_status[i].link_up = 0 for all lanes"), which matches PR #75's training FSM sketch and ties the tie-offs to a documented spec source rather than arbitrary defaults. The bundle direction convention is documented explicitly: PHY-view Input = MAC → PHY, PHY-view Output = PHY → MAC, with a clear note that MAC-side consumers instantiate Flipped(new PopLinkPHYIO) — this is the natural direction for the PHY module and the inversion from poplink-phy-if §2's MAC-view column is documented inline. The deferred follow-up list (BER injection, training FSM, // synthesis translate_off guard, Chisel construction parameters) is comprehensive and matches the SPEC's §Behavior and §Invariants open work. The module is a leaf as the issue body required — no Module(new ...) children to wire up, no parent to wire into. The SPEC has been promoted to Draft per PR #95 and the Draft text is faithfully reflected in the PR's source comments.

Findings

None.

**VERDICT:** PASS PR #106 adds the §12.3 step-1 scaffold for `PopLinkPHY_Behavioral` — Chisel module + chiseltest harness — and is exceptionally well-disciplined throughout. Mechanical guardrails all pass: SPDX headers correct (`CHARRUA-1.2` for the RTL source, `AGPL-3.0-or-later` for the test), both files in `package pop` matching the canonical package, chiseltest bench has the prescribed `it should "elaborate"` floor, scope matches Issue #51 (two new files), no AI/Anthropic attribution, no off-limits paths. The IO bundle structure mirrors the SPEC's reference to `docs/spec/poplink-phy-if.md §2` signal-class enumeration as five sub-bundles (`tx`, `rx`, `status`, `resetTrain`, `cal`) — exactly the right grouping. Rule 4 + rule 7 are handled with surgical precision: only the four control signals whose widths `poplink-phy-if §2` pins concretely at 1 bit (`phy_reset_req`, `phy_reset_ack`, `train_req`, `train_done`) are materialised as `Bool()` in `PopLinkResetTrainIO`; every other signal class (TX/RX data, lane_status, err_flags, ber_count, cal_ctrl, cal_status) stays as a `// TBD per SPEC §Interface` comment with an explicit forward-link to the Open question that tracks its width (PHY-option selection PLAN.md §13.2, `poplink-phy-if §3`/§6/§8 Open questions). No lane count `N`, no per-lane data widths, no err_flags bit-map, no ber_count counter width invented ahead of the PHY-option selection — exactly the discipline rule 7 requires. The output defaults (`phyResetAck := false.B`, `trainDone := false.B`) are well-justified as the POR/quiet state per `poplink-phy-if §5` step 1 ("All TX/RX disabled. lane_status[i].link_up = 0 for all lanes"), which matches PR #75's training FSM sketch and ties the tie-offs to a documented spec source rather than arbitrary defaults. The bundle direction convention is documented explicitly: PHY-view `Input` = MAC → PHY, PHY-view `Output` = PHY → MAC, with a clear note that MAC-side consumers instantiate `Flipped(new PopLinkPHYIO)` — this is the natural direction for the PHY module and the inversion from `poplink-phy-if §2`'s MAC-view column is documented inline. The deferred follow-up list (BER injection, training FSM, `// synthesis translate_off` guard, Chisel construction parameters) is comprehensive and matches the SPEC's §Behavior and §Invariants open work. The module is a leaf as the issue body required — no `Module(new ...)` children to wire up, no parent to wire into. The SPEC has been promoted to Draft per PR #95 and the Draft text is faithfully reflected in the PR's source comments. ## Findings _None._

navigator added the

review:pass

label

2026-05-26 13:43:23 -03:00