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

Merged
navigator merged 1 commit from spec/interchipfabric-draft into main 2026-05-26 01:20:58 -03:00
Owner

Refs #53 (companion Chisel skeleton, area:rtl).
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.

Summary

Promotes rtl/src/pop/specs/InterChipFabric.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
and PLAN.md sections that already commit values; widths and per-port
shapes no source pins are recorded as _Open question:_ rather than
invented.

Resolved TBDs

  • §Interface — PopLink PHY quad-port (N/S/E/W): port count fixed
    by ADR-010 Decision ("Each chip has 4 PopLink ports (N/S/E/W).
    Row+column wrap. Network diameter = 2 hops."); per-port mapping to
    PopLinkTop per PLAN.md §3.7; bundle per PLAN.md §13.3.
  • §Interface — per-VC credit / return: credit-based flow control
    pinned to PLAN.md §3.4 ("Flow control: credit-based per VC"); VC
    count = 2 pinned to PLAN.md §3.5 ("Deadlock-free with 2 VCs") and
    ADR-010 Consequences; 4-bit VC field from §3.4 frame header.
  • §Interface — chip-side transaction-layer attach: transaction
    set pinned verbatim to PLAN.md §3.6
    (REMOTE_READ_REQ/RESP, REMOTE_WRITE, REMOTE_WRITE_ACK,
    ATOMIC_OP/RESP, DMA_DESC, DMA_COMPLETE, BARRIER_ARRIVE/RELEASE,
    DOORBELL, BROADCAST, MGMT); non-coherent semantics pinned to
    ADR-011 Decision.
  • §Behavior — XY routing: dimension-ordered (XY) routing pinned
    to PLAN.md §3.5; 5×5 router shape, arbitration policy, and 2-3
    cycle intra-router latency quoted verbatim from §3.5; torus
    diameter pinned to ADR-010 (2 hops).
  • §Behavior — VC allocation: 2 VCs per PLAN.md §3.5; arbitration
    round-robin with VC priorities per §3.5.
  • §Behavior — ARQ on retransmit: verbatim PLAN.md §3.4
    (selective-repeat, 64-pkt window per VC, 1 µs retransmit timeout)
    plus CRC-32K (Koopman 0x32583499) integrity check from §3.4.
  • §Behavior — deadlock avoidance via VC partitioning: PLAN.md
    §3.5 + ADR-010 Consequences ("Deadlock-free via XY routing + 2
    VCs"); formal proof obligation from PLAN.md §12.4 / §12.7.
  • §Behavior — non-coherent semantics: verbatim ADR-011 Decision
    • Consequences.
  • §Invariants — deadlock-free under any legal traffic pattern:
    PLAN.md §3.5 + §12.4 (formal proof) + §12.7 (sign-off).
  • §Invariants — tolerate 10⁻⁶ raw BER end-to-end: verbatim
    PLAN.md §12.4 + §12.7; mechanism is CRC-32K (§3.4) + selective-
    repeat ARQ (§3.4).
  • §Invariants — no silent packet loss: CRC + ARQ per §3.4;
    PLAN.md §3.4 link state machine (RESET / INIT / TRAINING /
    ACTIVE / ERROR) escalates fatal-link to software.
  • §Invariants — bounded per-(destination, VC) re-order window:
    64-pkt window per VC per PLAN.md §3.4; sequencing key is the
    16-bit SeqNum field of the §3.4 frame header.
  • §Invariants — per-port aggregate bandwidth envelope: verbatim
    PLAN.md §3.3 (Edu: 4 lanes × 4 Gb/s = 16 Gb/s/port/dir;
    Pro: 8 lanes × 16-32 Gb/s = 128-256 Gb/s/port/dir).
  • §Invariants — non-coherent invariant preserved end-to-end:
    ADR-011 Decision.

Open questions (no source pins)

  • Per-port PopLink PHY bundle shape (lane count, SerDes data width,
    sideband control set) — tracks PopLinkPHY_Behavioral.SPEC.md §Interface (Status: Stub) and the deferred lane / rate triple
    in docs/spec/poplink-phy-if.md §3 pending PHY-option selection.
  • Per-VC credit-counter width + initial-credit advertisement
    protocol at link-up — not pinned by PLAN.md §3.4 or ADR-010.
  • Chip-side bundle shape toward MultiGemminiCluster and
    PCIeHostBridge (request / response port count, request-ID width,
    in-flight tracking depth) — tracks MultiGemminiCluster.SPEC.md §Interface and PCIeHostBridge.SPEC.md §Interface (both Stub).
  • CSR address-map, register widths, access discipline for routing
    tables and telemetry — not pinned by any ADR or PLAN.md section.
  • VC-to-traffic-class binding (which §3.6 transaction types ride
    VC0 versus VC1 for the deadlock-freedom argument) — PLAN.md §3.5
    pins the partition count but not the binding.
  • Per-frame retransmit cap, fatal-link escalation threshold, and
    software-visible fault-event path — not pinned by §3.4 or §12.4.

Constraints honoured

  • Only rtl/src/pop/specs/InterChipFabric.SPEC.md changes (ADR-017).
  • All ADR / PLAN refs from the Stub are preserved (PLAN §8.2, §12.3,
    ADR-009, ADR-010); §3.4 / §3.5 / §3.6 / §3.7 / §12.4 / §13.3 /
    ADR-011 are added as additional pins.
  • No fabricated widths, latencies, vendor commitments, or schedule
    promises; numeric values are quoted from PLAN.md or ADRs verbatim.
  • No sibling SPEC is currently in Draft, so sibling Stubs are
    referenced only inside Open questions.
Refs #53 (companion Chisel skeleton, area:rtl). 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. ## Summary Promotes `rtl/src/pop/specs/InterChipFabric.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 and PLAN.md sections that already commit values; widths and per-port shapes no source pins are recorded as `_Open question:_` rather than invented. ## Resolved TBDs - **§Interface — PopLink PHY quad-port (N/S/E/W)**: port count fixed by ADR-010 Decision ("Each chip has 4 PopLink ports (N/S/E/W). Row+column wrap. Network diameter = 2 hops."); per-port mapping to PopLinkTop per PLAN.md §3.7; bundle per PLAN.md §13.3. - **§Interface — per-VC credit / return**: credit-based flow control pinned to PLAN.md §3.4 ("Flow control: credit-based per VC"); VC count = 2 pinned to PLAN.md §3.5 ("Deadlock-free with 2 VCs") and ADR-010 Consequences; 4-bit VC field from §3.4 frame header. - **§Interface — chip-side transaction-layer attach**: transaction set pinned verbatim to PLAN.md §3.6 (REMOTE_READ_REQ/RESP, REMOTE_WRITE, REMOTE_WRITE_ACK, ATOMIC_OP/RESP, DMA_DESC, DMA_COMPLETE, BARRIER_ARRIVE/RELEASE, DOORBELL, BROADCAST, MGMT); non-coherent semantics pinned to ADR-011 Decision. - **§Behavior — XY routing**: dimension-ordered (XY) routing pinned to PLAN.md §3.5; 5×5 router shape, arbitration policy, and 2-3 cycle intra-router latency quoted verbatim from §3.5; torus diameter pinned to ADR-010 (2 hops). - **§Behavior — VC allocation**: 2 VCs per PLAN.md §3.5; arbitration round-robin with VC priorities per §3.5. - **§Behavior — ARQ on retransmit**: verbatim PLAN.md §3.4 (selective-repeat, 64-pkt window per VC, 1 µs retransmit timeout) plus CRC-32K (Koopman 0x32583499) integrity check from §3.4. - **§Behavior — deadlock avoidance via VC partitioning**: PLAN.md §3.5 + ADR-010 Consequences ("Deadlock-free via XY routing + 2 VCs"); formal proof obligation from PLAN.md §12.4 / §12.7. - **§Behavior — non-coherent semantics**: verbatim ADR-011 Decision + Consequences. - **§Invariants — deadlock-free under any legal traffic pattern**: PLAN.md §3.5 + §12.4 (formal proof) + §12.7 (sign-off). - **§Invariants — tolerate 10⁻⁶ raw BER end-to-end**: verbatim PLAN.md §12.4 + §12.7; mechanism is CRC-32K (§3.4) + selective- repeat ARQ (§3.4). - **§Invariants — no silent packet loss**: CRC + ARQ per §3.4; PLAN.md §3.4 link state machine (RESET / INIT / TRAINING / ACTIVE / ERROR) escalates fatal-link to software. - **§Invariants — bounded per-(destination, VC) re-order window**: 64-pkt window per VC per PLAN.md §3.4; sequencing key is the 16-bit SeqNum field of the §3.4 frame header. - **§Invariants — per-port aggregate bandwidth envelope**: verbatim PLAN.md §3.3 (Edu: 4 lanes × 4 Gb/s = 16 Gb/s/port/dir; Pro: 8 lanes × 16-32 Gb/s = 128-256 Gb/s/port/dir). - **§Invariants — non-coherent invariant preserved end-to-end**: ADR-011 Decision. ## Open questions (no source pins) - Per-port PopLink PHY bundle shape (lane count, SerDes data width, sideband control set) — tracks `PopLinkPHY_Behavioral.SPEC.md §Interface` (Status: Stub) and the deferred lane / rate triple in `docs/spec/poplink-phy-if.md §3` pending PHY-option selection. - Per-VC credit-counter width + initial-credit advertisement protocol at link-up — not pinned by PLAN.md §3.4 or ADR-010. - Chip-side bundle shape toward `MultiGemminiCluster` and `PCIeHostBridge` (request / response port count, request-ID width, in-flight tracking depth) — tracks `MultiGemminiCluster.SPEC.md §Interface` and `PCIeHostBridge.SPEC.md §Interface` (both Stub). - CSR address-map, register widths, access discipline for routing tables and telemetry — not pinned by any ADR or PLAN.md section. - VC-to-traffic-class binding (which §3.6 transaction types ride VC0 versus VC1 for the deadlock-freedom argument) — PLAN.md §3.5 pins the partition count but not the binding. - Per-frame retransmit cap, fatal-link escalation threshold, and software-visible fault-event path — not pinned by §3.4 or §12.4. ## Constraints honoured - Only `rtl/src/pop/specs/InterChipFabric.SPEC.md` changes (ADR-017). - All ADR / PLAN refs from the Stub are preserved (PLAN §8.2, §12.3, ADR-009, ADR-010); §3.4 / §3.5 / §3.6 / §3.7 / §12.4 / §13.3 / ADR-011 are added as additional pins. - No fabricated widths, latencies, vendor commitments, or schedule promises; numeric values are quoted from PLAN.md or ADRs verbatim. - No sibling SPEC is currently in Draft, so sibling Stubs are referenced only inside Open questions.
spec(InterChipFabric): promote InterChipFabric.SPEC.md to Draft
All checks were successful
build / scalafmt-check (pull_request) Successful in 3s
build / sbt-compile (pull_request) Successful in 3s
build / shell-lint (pull_request) Successful in 19s
af12d7f858
Lifts InterChipFabric.SPEC.md from Status: Stub to Status: Draft. No
behaviour or Chisel is added; the IO contract is pinned to ADRs and
PLAN.md sections 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 PopLink PHY quad-port — N/S/E/W port count fixed by
  ADR-010 Decision ("Each chip has 4 PopLink ports (N/S/E/W). Row+
  column wrap. Network diameter = 2 hops."), with PHY bundle shape
  per PLAN.md §13.3 and per-port mapping to PLAN.md §3.7
  PopLinkTop instances.
- §Interface per-VC credit / return — credit-based flow control
  per PLAN.md §3.4 ("Flow control: credit-based per VC"); VC count
  fixed at two by PLAN.md §3.5 ("Deadlock-free with 2 VCs") and
  ADR-010 Consequences; 4-bit VC field comes from PLAN.md §3.4
  frame header.
- §Interface chip-side transaction-layer attach — transaction set
  pinned to PLAN.md §3.6 (REMOTE_READ_REQ/RESP, REMOTE_WRITE,
  REMOTE_WRITE_ACK, ATOMIC_OP/RESP, DMA_DESC, DMA_COMPLETE,
  BARRIER_ARRIVE/RELEASE, DOORBELL, BROADCAST, MGMT); non-coherent
  semantics pinned to ADR-011 Decision.
- §Behavior XY routing — pinned to PLAN.md §3.5 ("Routing:
  dimension-order (XY). Deadlock-free with 2 VCs"); 5×5 router
  shape and arbitration policy quoted verbatim from §3.5; torus
  diameter pinned to ADR-010 Decision (2 hops).
- §Behavior VC allocation — 2 VCs per PLAN.md §3.5; arbitration
  round-robin with VC priorities per §3.5.
- §Behavior ARQ on retransmit — verbatim PLAN.md §3.4
  (selective-repeat, 64-pkt window per VC, 1 µs retransmit
  timeout); CRC-32K (Koopman 0x32583499) integrity check from §3.4.
- §Behavior deadlock avoidance via VC partitioning — pinned to
  PLAN.md §3.5 + ADR-010 Consequences ("Deadlock-free via XY
  routing + 2 VCs"); formal proof obligation from §12.4 / §12.7.
- §Behavior non-coherent semantics — verbatim ADR-011 Decision
  + Consequences.
- §Invariants deadlock-free under any legal traffic pattern —
  PLAN.md §3.5 + §12.4 (formal proof) + §12.7 (sign-off).
- §Invariants tolerate 10⁻⁶ raw BER — verbatim PLAN.md §12.4
  + §12.7; mechanism = CRC-32K (§3.4) + selective-repeat ARQ
  (§3.4).
- §Invariants no silent packet loss — CRC + ARQ per §3.4; link
  state machine per §3.4 escalates fatal-link to software.
- §Invariants bounded per-(destination, VC) re-order window —
  64-pkt window per VC per PLAN.md §3.4; sequencing key is the
  16-bit SeqNum field of the §3.4 frame header.
- §Invariants per-port aggregate-bandwidth envelope — verbatim
  PLAN.md §3.3 (Edu: 4 lanes × 4 Gb/s = 16 Gb/s/port/dir; Pro:
  8 lanes × 16-32 Gb/s = 128-256 Gb/s/port/dir).
- §Invariants non-coherent invariant — pinned to ADR-011
  Decision.

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

- Per-port PopLink PHY bundle shape (lane count, SerDes data
  width, sideband control set) — tracks
  PopLinkPHY_Behavioral.SPEC.md §Interface (Status: Stub) and
  docs/spec/poplink-phy-if.md §3 lane / rate triple deferred
  to PHY-option selection.
- Per-VC credit-counter width + initial-credit advertisement
  at link-up — not pinned by §3.4 or ADR-010.
- Chip-side bundle shape toward MultiGemminiCluster and
  PCIeHostBridge (request / response port count, request-ID
  width, in-flight tracking depth) — tracks
  MultiGemminiCluster.SPEC.md §Interface and
  PCIeHostBridge.SPEC.md §Interface (both Status: Stub).
- CSR address-map, register widths, access discipline for
  routing tables and telemetry — not pinned by any ADR /
  PLAN.md section.
- VC-to-traffic-class binding (which §3.6 transaction types
  ride VC0 versus VC1 for the deadlock proof).
- Per-frame retransmit cap, fatal-link escalation threshold,
  software-visible fault path.

Constraints honoured:
- Only rtl/src/pop/specs/InterChipFabric.SPEC.md changes
  (ADR-017).
- All ADR / PLAN refs from the Stub are preserved (PLAN §8.2,
  §12.3, ADR-009, ADR-010); §3.4 / §3.5 / §3.6 / §3.7 /
  §12.4 / §13.3 / ADR-011 added as additional pins.
- No fabricated widths, latencies, vendor commitments, or
  schedule promises; numeric values are quoted from PLAN.md
  / ADRs verbatim.
- No sibling SPEC is currently in Draft, so sibling Stubs
  (PopLinkPHY_Behavioral, MultiGemminiCluster,
  PCIeHostBridge) are referenced only inside Open questions.
Author
Owner

VERDICT: PASS

PR #91 promotes rtl/src/pop/specs/InterChipFabric.SPEC.md from Stub to Draft, mirroring the careful pattern established by PR #87 (FluidPopSoC). Mechanical guardrails pass: existing SPDX header preserved (diff starts at line 4), single file touched, no AI/Anthropic attribution, no off-limits paths, no Chisel module so rules 4–6 don't apply. The missing Closes # is explained transparently — autonomous spec-designer role with no per-promotion tracking issue. Rule 7 is the critical one, and the PR is meticulous: every concrete number, opcode, layout, and policy is presented as a verbatim quote from a specific PLAN.md section or ADR Decision/Consequences, with the source pinned inline. Numerical sanity checks: 64-bit PopLink header decomposes correctly (SeqNum 16b + VC 4b + RSV 12b + Length 16b + TypeFlags 16b = 64); 5×5 router crossbar matches 4 PHY ports + 1 local port; Edu bandwidth math 4 Gb/s/lane × 4 lanes/port = 16 Gb/s/port/dir checks; Pro 16–32 Gb/s/lane × 8 lanes/port = 128–256 Gb/s/port/dir checks. Importantly, this promotion explicitly attributes "2 VCs" to both PLAN.md §3.5 ("Deadlock-free with 2 VCs") and ADR-010 Consequences ("Deadlock-free via XY routing + 2 VCs") with verbatim quotes — which retroactively vindicates the same "2 VCs" attribution to ADR-010 that I had flagged on PR #82 as possibly fabricated. The ARQ details (selective-repeat, 64-pkt window per VC, 1 µs retransmit timeout, CRC-32K Koopman 0x32583499) all carry verbatim §3.4 attributions, as does the link state machine (RESET/INIT/TRAINING/ACTIVE/ERROR). The transaction set (REMOTE_READ_REQ/RESP, REMOTE_WRITE, REMOTE_WRITE_ACK, ATOMIC_OP/RESP, DMA_DESC, DMA_COMPLETE, BARRIER_ARRIVE/RELEASE, DOORBELL, BROADCAST, MGMT) is quoted verbatim from §3.6. ADR-011 quotes match PR #87. The Open Questions section is honest and comprehensive — per-port PopLink PHY shape, credit-counter width and init-credit advertisement, chip-side bundle shape, CSR address map, VC-to-traffic-class binding, retransmit cap / fatal-link escalation — none are silently chosen. The Promotion history entry is appropriate.

Findings

None.

<!-- agent:review verdict=PASS ts=1779769192 --> **VERDICT:** PASS PR #91 promotes `rtl/src/pop/specs/InterChipFabric.SPEC.md` from Stub to Draft, mirroring the careful pattern established by PR #87 (FluidPopSoC). Mechanical guardrails pass: existing SPDX header preserved (diff starts at line 4), single file touched, no AI/Anthropic attribution, no off-limits paths, no Chisel module so rules 4–6 don't apply. The missing `Closes #` is explained transparently — autonomous `spec-designer` role with no per-promotion tracking issue. Rule 7 is the critical one, and the PR is meticulous: every concrete number, opcode, layout, and policy is presented as a verbatim quote from a specific PLAN.md section or ADR Decision/Consequences, with the source pinned inline. Numerical sanity checks: 64-bit PopLink header decomposes correctly (SeqNum 16b + VC 4b + RSV 12b + Length 16b + TypeFlags 16b = 64); 5×5 router crossbar matches 4 PHY ports + 1 local port; Edu bandwidth math 4 Gb/s/lane × 4 lanes/port = 16 Gb/s/port/dir checks; Pro 16–32 Gb/s/lane × 8 lanes/port = 128–256 Gb/s/port/dir checks. Importantly, this promotion explicitly attributes "2 VCs" to both PLAN.md §3.5 ("Deadlock-free with 2 VCs") and ADR-010 Consequences ("Deadlock-free via XY routing + 2 VCs") with verbatim quotes — which retroactively vindicates the same "2 VCs" attribution to ADR-010 that I had flagged on PR #82 as possibly fabricated. The ARQ details (selective-repeat, 64-pkt window per VC, 1 µs retransmit timeout, CRC-32K Koopman 0x32583499) all carry verbatim §3.4 attributions, as does the link state machine (RESET/INIT/TRAINING/ACTIVE/ERROR). The transaction set (REMOTE_READ_REQ/RESP, REMOTE_WRITE, REMOTE_WRITE_ACK, ATOMIC_OP/RESP, DMA_DESC, DMA_COMPLETE, BARRIER_ARRIVE/RELEASE, DOORBELL, BROADCAST, MGMT) is quoted verbatim from §3.6. ADR-011 quotes match PR #87. The Open Questions section is honest and comprehensive — per-port PopLink PHY shape, credit-counter width and init-credit advertisement, chip-side bundle shape, CSR address map, VC-to-traffic-class binding, retransmit cap / fatal-link escalation — none are silently chosen. The Promotion history entry is appropriate. ## Findings _None._
fluidpop-bot approved these changes 2026-05-26 01:20:34 -03:00
Dismissed
fluidpop-bot left a comment
Collaborator

CI green (head af12d7f858), auto-approving

CI green (head af12d7f858366ff6eb95de203da1d1a49433347b), auto-approving
navigator force-pushed spec/interchipfabric-draft from af12d7f858
All checks were successful
build / scalafmt-check (pull_request) Successful in 3s
build / sbt-compile (pull_request) Successful in 3s
build / shell-lint (pull_request) Successful in 19s
to 2e3b16524d
All checks were successful
build / scalafmt-check (pull_request) Successful in 3s
build / sbt-compile (pull_request) Successful in 3s
build / shell-lint (pull_request) Successful in 11s
2026-05-26 01:20:36 -03:00
Compare
fluidpop-bot left a comment
Collaborator

CI green (head 2e3b16524d), auto-approving

CI green (head 2e3b16524dc5837c913f918c8b56f855d6b6e39b), auto-approving
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
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!91
No description provided.