rtl: PopRoCCRouter v1 — funct7 decode + dispatch + per-source ordering #104

New issue

Closed

opened 2026-05-26 13:33:22 -03:00 by navigator · 3 comments

navigator commented

2026-05-26 13:33:22 -03:00

Owner

Goal

Implement the v1 behaviour of PopRoCCRouter as pinned by the Draft SPEC at rtl/src/pop/specs/PopRoCCRouter.SPEC.md (#96). The existing skeleton at rtl/src/pop/PopRoCCRouter.scala (PR #69) already has the cmd and resp ports plus the local RoCCCommand / RoCCResponse mirrors. This issue lands the actual decode + dispatch logic.

Scope — strictly what the Draft SPEC pins

Behaviour to implement (all sourced from §Behavior of the Draft):

funct7 decode: extract the top 2 bits as gemmini-id per ADR-006 Consequences (Edu 4-tile addressing).
Forward cmd payload onto the selected per-tile attach; the rest of funct7 and funct/rs1/rs2/rd flow through unchanged.
In-flight tracking table keyed by (originating-core-id, rd, xd) to restore the writeback register on resp.
Per-source ordering preserved on resp; cross-source not preserved.
xd=0 is fire-and-forget; xd=1 paired with resp.valid.

Open Questions — DO NOT INVENT

Per-tile bundle shape — Open per §Interface. Use a parameterised N-element Vec(N, Decoupled(_)) with N: Int constructor parameter (default 4 for Edu), but do not invent the per-tile element bundle type beyond what the Draft already exposes (RoCCCommand/RoCCResponse mirrors).
In-flight table depth — Open per §Behavior. Parameterise it as a constructor inFlightDepth: Int = 8 and add // Open question per SPEC §Behavior next to the parameter declaration.
Cross-source arbitration policy — Open per §Behavior. Use round-robin between two cores (matches ADR-006 Edu 2-core decision); annotate that this is a default choice, not a pinned ADR decision.
Exception path — Open per §Interface. Leave // TBD per SPEC §Interface — exception path and do not surface a port.

Acceptance criteria

rtl/src/pop/PopRoCCRouter.scala body materialises decode + dispatch + in-flight table per the bullets above
rtl/tests/PopRoCCRouter/PopRoCCRouterSpec.scala extended with at least three chiseltest scenarios:
- cmd.valid with xd=1 → resp.valid arrives with matching rd within inFlightDepth + 2 cycles
- cmd.valid with xd=0 → fire-and-forget; no resp.valid on the same-core port
- Two parallel cmd streams on different per-tile attaches make forward progress under sustained back-pressure on one of them (no-deadlock contract)
sbt -no-colors compile and sbt -no-colors test green from rtl/
All Open Questions above stay as comments / parameter defaults — no fabricated widths
No edits outside rtl/src/pop/PopRoCCRouter.scala and rtl/tests/PopRoCCRouter/

Plan refs

PLAN.md §8.2 (custom module list), §12.3 (per-module verification floor); ADR-001, ADR-006, ADR-011.

## Goal Implement the v1 behaviour of `PopRoCCRouter` as pinned by the Draft SPEC at `rtl/src/pop/specs/PopRoCCRouter.SPEC.md` (#96). The existing skeleton at `rtl/src/pop/PopRoCCRouter.scala` (PR #69) already has the `cmd` and `resp` ports plus the local `RoCCCommand` / `RoCCResponse` mirrors. This issue lands the actual decode + dispatch logic. ## Scope — strictly what the Draft SPEC pins Behaviour to implement (all sourced from §Behavior of the Draft): - `funct7` decode: extract the **top 2 bits** as gemmini-id per ADR-006 Consequences (Edu 4-tile addressing). - Forward `cmd` payload onto the selected per-tile attach; the rest of `funct7` and `funct`/`rs1`/`rs2`/`rd` flow through unchanged. - In-flight tracking table keyed by `(originating-core-id, rd, xd)` to restore the writeback register on `resp`. - Per-source ordering preserved on `resp`; cross-source not preserved. - `xd=0` is fire-and-forget; `xd=1` paired with `resp.valid`. ## Open Questions — DO NOT INVENT - Per-tile bundle shape — Open per §Interface. Use a parameterised `N`-element `Vec(N, Decoupled(_))` with `N: Int` constructor parameter (default 4 for Edu), but do not invent the per-tile element bundle type beyond what the Draft already exposes (`RoCCCommand`/`RoCCResponse` mirrors). - In-flight table depth — Open per §Behavior. Parameterise it as a constructor `inFlightDepth: Int = 8` and add `// Open question per SPEC §Behavior` next to the parameter declaration. - Cross-source arbitration policy — Open per §Behavior. Use round-robin between two cores (matches ADR-006 Edu 2-core decision); annotate that this is a default choice, not a pinned ADR decision. - Exception path — Open per §Interface. Leave `// TBD per SPEC §Interface — exception path` and do not surface a port. ## Acceptance criteria - [ ] `rtl/src/pop/PopRoCCRouter.scala` body materialises decode + dispatch + in-flight table per the bullets above - [ ] `rtl/tests/PopRoCCRouter/PopRoCCRouterSpec.scala` extended with at least three chiseltest scenarios: - `cmd.valid` with `xd=1` → `resp.valid` arrives with matching `rd` within `inFlightDepth + 2` cycles - `cmd.valid` with `xd=0` → fire-and-forget; no `resp.valid` on the same-core port - Two parallel `cmd` streams on different per-tile attaches make forward progress under sustained back-pressure on one of them (no-deadlock contract) - [ ] `sbt -no-colors compile` and `sbt -no-colors test` green from `rtl/` - [ ] All Open Questions above stay as comments / parameter defaults — no fabricated widths - [ ] No edits outside `rtl/src/pop/PopRoCCRouter.scala` and `rtl/tests/PopRoCCRouter/` ## Plan refs PLAN.md §8.2 (custom module list), §12.3 (per-module verification floor); ADR-001, ADR-006, ADR-011.