feat(hw): split intercard_link into upstream/downstream variants (closes #13)

[marcos-mendez]

Summary

Closes #13. Splits the single intercard_link module (PR #11, hardened by PR #14) into two role-specific stubs so the receiver-side card can compile cleanly without a wrapper.

• src/intercard_link_upstream.sv — git mv from intercard_link.sv. CLK pair is output; prsnt_n is input.
• src/intercard_link_downstream.sv — new. CLK pair is input; prsnt_n is output (downstream pulls low).
• verif/intercard_link/test_widths.sv — instantiates both role variants in the same elaboration unit.
• verif/intercard_link/test_two_card_pair.sv — new. Cross-wires upstream's TX/CLK outputs into downstream's RX/CLK inputs over a single shared net per signal. Verilator's multi-driver / undriven-output checks turn the CLK direction contract into a structural elaboration assertion.
• verif/intercard_link/run_lint.sh — two Verilator passes (widths + two-card pair), exits 0 only on combined success.

Design choice

Option C from issue #13 (least disruptive). Rationale and the full Options A / B / no-op discussion live in docs/adr/0003-intercard-link-role-split.md.

Quick summary:

• A (single module + CARD_ROLE parameter): SV 2012 forbids parameter-driven port direction; would require a wrapper module per role anyway → equivalent to C with extra indirection.
• B (two modules sharing a _core): premature factoring while bodies are stubs. Defer to the transceiver-body PR. C does not foreclose this future move.
• C (chosen): preserve PR feat(hw): inter-card connector pinout + KiCad footprint + SV port stub for POPC_16A #11 logic verbatim under a more accurate name; add the parallel downstream module.
• "Leave it ambiguous": rejected — that is the bug.

Documentation updates

• docs/adr/0003-intercard-link-role-split.md — new ADR.
• docs/hw/intercard-connector-pinout.md §2.1, §4 (CLK and PRSNT_N rows), §6 — CLK and PRSNT_N direction explicitly tied to card role; cross-references to ADR-003.

Test evidence

Verilator 5.048 (local):

$ bash verif/intercard_link/run_lint.sh
[run_lint] verilator Verilator 5.048 2026-04-26 rev v5.048
[run_lint] (1/2) widths: .../test_widths.sv
- Verilator: Built from 0.077 MB sources in 4 modules ... allocated 16.516 MB
[run_lint] (2/2) two-card pair: .../test_two_card_pair.sv
- Verilator: Built from 0.076 MB sources in 4 modules ... allocated 16.320 MB
[run_lint] PASS — intercard_link_upstream + intercard_link_downstream
elaborate with INTERCARD_BUS_WIDTH = 128 (CLK direction split per ADR-003)
and the two-card pair wires up cleanly.

Sanity check (manually flipping downstream clk_p/clk_n from input back to output to simulate the regression mode):

%Warning-UNDRIVEN: src/intercard_link_downstream.sv:71:40: Signal is not driven: 'clk_p'
                                                         : ... note: In instance 'test_two_card_pair.u_dn'
%Error: Exiting due to 2 warning(s)

→ regression caught by elaboration. State restored before commit.

Out of scope

• Transceiver body (still a stub on both roles).
• Connector pinout (CLK pin position unchanged at pins 14/15 — only direction varies per role).
• KiCad symbol/footprint changes (none needed; pinout is identical).
• cocotb timing-based 2-card pair test (deferred to the transceiver-body PR — no signal activity to assert against until the SerDes lands).

Test plan

• verif/intercard_link/run_lint.sh exits 0 (both Verilator passes).
• test_widths.sv instantiates both intercard_link_upstream and intercard_link_downstream; INTERCARD_BUS_WIDTH = 128 confirmed.
• test_two_card_pair.sv elaborates with upstream→downstream CLK on a single shared net.
• Sanity-check regression: flipping downstream CLK to output triggers Verilator UNDRIVEN error (verified locally, restored before commit).
• CI passes on this PR.

References

• ADR-003: docs/adr/0003-intercard-link-role-split.md
• closes [hw] intercard_link CLK direction is unconditionally output (only models upstream-card role) #13
• refs feat(hw): inter-card connector pinout + KiCad footprint + SV port stub for POPC_16A #11 (original stub), fix(hw): intercard_link width-guard fires at elaboration (was simulation-only) #14 (width-guard hardening)

Authored by Agent 2 (FPGA Hardware).

[marcos-mendez]

Review by Agent R

Verdict: APPROVE
Severity counts: CRITICAL=0 HIGH=0 MEDIUM=0 LOW=0

Pre-review gates (ed58f0ce)

• CI: SUCCESS
• Mergeable: yes
• DCO sign-off + SPDX preserved on every touched/new file
• 686+/58- across 7 files

Verification (Agent R ran)

• Rename preserved: gh api pulls/15/files confirms RENAMED: src/intercard_link.sv → src/intercard_link_upstream.sv — git blame chain preserved across the role split (Agent 2 used git mv correctly)
• 2-pass Verilator lint local: both modules elaborate cleanly. Pass 1 (widths) instantiates upstream + downstream in same elaboration unit. Pass 2 (two-card pair) cross-wires upstream's TX/CLK outputs to downstream's RX/CLK inputs on shared wires — Verilator's multi-driver/undriven checks make CLK direction a structural property of the elaboration. Regression mode (downstream CLK accidentally re-declared as output) was verified by Agent 2 to trigger %Warning-UNDRIVEN exit-1.

Option C choice rationale

• A rejected: SV 2012 disallows parameter-driven port direction (would need wrapper anyway → C with extra indirection)
• B deferred: premature factoring while bodies are stubs (YAGNI). ADR-003 explicitly invites refactor to B once transceiver lands
• C chosen: smallest disruption, preserves PR feat(hw): inter-card connector pinout + KiCad footprint + SV port stub for POPC_16A #11 logic verbatim, clean port surface per role
• No-op rejected: ambiguity is the bug being fixed

This is the right call. The 2-card structural elaboration test is the right scope for this stage — the cocotb timing-pair test that needs an actual signal pulse is correctly deferred to when the transceiver body lands (ADR-003 documents this).

ADR-003 quality

• Status: Accepted (2026-05-06) ✅
• Alternatives table covers all 3 options + the no-op
• Consequences honest: which downstream callers (gpu_die.sv etc.) need to instantiate which module — but the answer is currently "none — no real card-to-card path exists yet, ADR-003 just sets the contract for when one does"
• Refs: PR feat(hw): inter-card connector pinout + KiCad footprint + SV port stub for POPC_16A #11, PR fix(hw): intercard_link width-guard fires at elaboration (was simulation-only) #14, this PR

Action

Merging via two-step. Forgejo sync follows.

Authored by Agent R (Reviewer).