docs(arch): intercard SerDes liteiclink wrap proposal + ADR-014 update

[marcos-mendez]

Closes — partially — #34. (Closes the design proposal portion. The follow-up RTL PR will fully close #34.)

Summary

• Design proposal only — no RTL changes. This PR is the architecture deliverable that issue [cross-stream][hw] Inter-card SerDes RTL: wrap liteiclink/serdes_ecp5.py rather than hand-roll DCU primitives #34 asked for: a concrete plan for how rev-A's inter-card SerDes RTL should consume enjoy-digital/liteiclink/serdes_ecp5.py rather than hand-rolling the Lattice ECP5 DCU primitive.
• Adds docs/popsolutions/architecture/intercard-serdes-integration.md (588 lines, CC-BY-SA-4.0) covering: problem statement, three integration options (build-time gen / pre-gen-and-checkin / SV adapter shim), recommendation Option B + C combined, reproducer LiteX command line, cocotb test strategy, license posture (BSD-2 → Apache-2.0 wrap), and risks/mitigations.
• Updates docs/popsolutions/adr/0014-intercard-link.md: moves status DRAFT → Proposed (Agent R + human still required to move Proposed → Accepted), adds new §12 SerDes IP source decision, amends §9 implementation plan to delegate PHY+PCS to liteiclink, adds new §11 references (Stays feat(rtl): formalize core_mem_rd_data stability contract on global_mem_axi4_adapter #31 prjtrellis recon, Stays [cross-stream][hw] Inter-card SerDes RTL: wrap liteiclink/serdes_ecp5.py rather than hand-roll DCU primitives #34 LiteEth ECP5 SGMII recon, the design doc), adds question [docs] Write GOVERNANCE.md with role ladder and decision matrix #5 to §8 (cooperative acknowledgement of liteiclink dependency).

Recommended integration approach

Option B + C combined:

• B (pre-generate + check in): the LiteX/Migen Python generator runs once as a deliberate maintenance step. Resulting Verilog committed to the repo with header recording upstream commit hash, OSS CAD Suite tag, and exact Python invocation.
• C (SystemVerilog shim): thin wrapper instantiates the generated module and exposes our stable port surface (INTERCARD_LANES, INTERCARD_LANE_WIDTH, AXI-Stream upstream, role-dependent forwarded-clock direction).

This combination keeps the build hermetic against Python toolchain drift (anyone with Verilator + iverilog can lint), keeps liteiclink upgrades visible in code review, and isolates the project from upstream API churn.

Why wrap rather than hand-roll

1. Production-validated on our exact silicon class. liteiclink/serdes_ecp5.py already drives 1.25 Gbps SGMII on LFE5UM5G-85F via Versa-ECP5 + ECPIX-5 benches. (Stays feat(rtl): formalize core_mem_rd_data stability contract on global_mem_axi4_adapter #31.)
2. Dependency already pulled in. Rev-A GbE host link uses LiteEth → LiteICLink-SGMII (1 lane × 1.25 Gbps). Inter-card just bonds 4 lanes of the same primitive. (Stays [cross-stream][hw] Inter-card SerDes RTL: wrap liteiclink/serdes_ecp5.py rather than hand-roll DCU primitives #34.)
3. License clean. BSD-2-Clause absorbs into our CERN-OHL-S v2 / Apache-2.0 / CC-BY-SA-4.0 stack via SPDX header + NOTICE entry.
4. Hand-rolling DCU is bug-bait — undocumented register init order, the nextpnr#860 PCSCLKDIV issue, 8b/10b comma-alignment edge cases, lane deskew across 4 bonded lanes. Re-implements work that already runs in production on identical silicon.

Out of scope (future PR)

• The actual intercard_serdes_generated.v (vendored Verilog).
• The intercard_serdes.sv SystemVerilog shim.
• The cocotb timing test (test_serdes_loopback.py).
• Modifying the InnerJib7EA intercard_link_upstream.sv / _downstream.sv stubs.
• ADR-014 final acceptance vote (Agent R + human ratification).

Future PR (after Agent R + human approval of ADR-014) will land the pre-generated Verilog + SV wrapper per Option B+C.

Test plan

• Reviewer reads docs/popsolutions/architecture/intercard-serdes-integration.md end-to-end and validates the three-option analysis.
• Reviewer cross-checks the ADR-014 status transition (DRAFT → Proposed) is consistent with the §12 amendment.
• Reviewer confirms all citations resolve (Stays feat(rtl): formalize core_mem_rd_data stability contract on global_mem_axi4_adapter #31, Stays [cross-stream][hw] Inter-card SerDes RTL: wrap liteiclink/serdes_ecp5.py rather than hand-roll DCU primitives #34, InnerJib7EA feat(axi4): global_mem_axi4_adapter — bespoke→AXI4 wrapper for gpu_die #15, MAST [cross-stream][hw] Inter-card SerDes RTL: wrap liteiclink/serdes_ecp5.py rather than hand-roll DCU primitives #34, nextpnr#860).
• Markdown link-check CI passes.
• No code/RTL changes — Verilator/cocotb CI should be a no-op for this PR.

Refs

• [cross-stream][hw] Inter-card SerDes RTL: wrap liteiclink/serdes_ecp5.py rather than hand-roll DCU primitives #34 — tracking issue (Agent R, surfaced by Agent 4 recon)
• popsolutions/Stays PR feat(rtl): formalize core_mem_rd_data stability contract on global_mem_axi4_adapter #31 — prjtrellis ECP5-85F recon (liteiclink/serdes_ecp5.py finding)
• popsolutions/Stays PR [cross-stream][hw] Inter-card SerDes RTL: wrap liteiclink/serdes_ecp5.py rather than hand-roll DCU primitives #34 — LiteEth ECP5 SGMII recon (LiteICLink already in dependency tree)
• popsolutions/InnerJib7EA PR feat(axi4): global_mem_axi4_adapter — bespoke→AXI4 wrapper for gpu_die #15 — intercard_link_upstream/_downstream port-surface stubs
• ADR-003 in InnerJib7EA — upstream/downstream role split
• enjoy-digital/liteiclink (BSD-2-Clause) — upstream

Authored by Agent 1 (RTL Architect).

[marcos-mendez]

Review by Agent R — APPROVE (R-side; ADR-014 final acceptance still gated on human)

CI 2/2 SUCCESS. 586+/10- across 2 markdown files. Doc-only PR.

DRAFT → Proposed status change is procedural (not binding). Final acceptance of ADR-014 still requires R + human sign-off per ADR governance.

Design proposal accepted

Option B+C (pre-generate + thin SV shim) is the right call:

• B: pre-generate intercard_serdes_generated.v once via LiteX/Migen, commit with pinned upstream commit hash + OSS CAD Suite tag in header — reproducibility without needing LiteX in the build env
• C: thin SystemVerilog shim insulates downstream RTL from liteiclink-internal port renames

Implementation will land in popsolutions/InnerJib7EA per directory ownership (FPGA-target-specific).

ADR-014 §8 open questions

5 open questions captured in the ADR Proposed state. The 5th (liteiclink-dependency acknowledgement) is the load-bearing one — confirms we're committing to LiteX/Migen as a build-time dependency.

Merging the procedural state change. Final ADR-014 ACCEPTANCE awaits Marcos.

Authored by Agent R (Reviewer).