Summary
ADR-001 commits rev A to PCIe Gen2 via the ECP5 hard IP as the host link, with LitePCIe as the open-toolchain controller. Agent 4's first ecosystem-health survey (popsolutions/Stays#3, doc `docs/upstream-contributions/0001-rev-a-known-upstream-issues.md`) found that LitePCIe ships no ECP5 PHY module and has zero history of ECP5 work.
Without intervention, rev A cannot use PCIe through the open toolchain, which violates ADR-001's openness commitment.
Evidence
- `enjoy-digital/litepcie/litepcie/phy/` directory contents:
```
init.py
axis_adapters.py
c5pciephy.py ← Cyclone V (Intel)
gw5apciephy.py ← Gowin GW5A
lfcpnxpciephy.py ← Lattice CertusPro-NX (rev-B target, supported 2024-2025)
s7pciephy.py ← Xilinx 7-series
uspciephy.py ← Xilinx UltraScale
usppciephy.py ← Xilinx UltraScale+
xilinx_tuser.py
```
There is no `ecp5pciephy.py`.
- `gh search issues --repo enjoy-digital/litepcie "lattice OR ecp5"` (open + closed): 0 results.
- `gh search prs --repo enjoy-digital/litepcie "lattice OR ecp5"`: 0 results.
The CertusPro-NX PHY is recent (Copyright 2024-2025), so the ecosystem is moving — but ECP5 is not on its path.
Why this is rev-A blocking, not rev-B
ADR-001 deliberately picks ECP5 for rev A because the open toolchain is rock-solid for synthesis, place-and-route, and bitstream generation. The ADR table explicitly lists LitePCIe under the rev-A toolchain. CertusPro-NX (with the supported PHY) is rev-B per the same ADR — moving forward to rev-B silicon to gain PCIe defeats the rev-A purpose.
Three options (all costed)
Option 1 — Author `ecp5pciephy.py` upstream
- Scope: wrap ECP5 PCS hard IP (PCIe Gen2 x1/x4) in a LitePCIe PHY module. Reference: `lfcpnxpciephy.py` (~hundreds of LoC, wraps a Lattice IP block via LMMI).
- Owner: Agent 4 (this is exactly stream-4 territory).
- Time: non-trivial — likely 1-2 sprint-equivalents of focused work plus upstream review cycles. Risk that enjoy-digital decides not to merge.
- Wins: rev A keeps PCIe; cooperative ships a first-class upstream capability; Global-South-friendly mission stays intact.
Option 2 — Switch rev-A host link off PCIe
- Scope: USB3 via FT601 (≈ 400 MB/s sustained) or GbE via LiteEth (≈ 110 MB/s). Both are well-supported on ECP5.
- Owner: Agent 1 (RTL controller swap), Agent 2 (PCB connector / FT601 chip), Agent 3 (driver swap).
- Time: PCB rework if SO-DIMM-and-FT601 already on rev-A schematic; minor RTL/driver swap.
- Wins: ships rev-A on schedule; lower bring-up risk.
- Costs: loses PCIe Gen2 x1 (≈ 500 MB/s) or x4 (≈ 2 GB/s) — bandwidth headroom for inference workloads drops; multi-card host coordination loses the PCIe Gen2 latency profile.
Option 3 — Defer PCIe to rev B with CertusPro-NX
- Scope: rev A ships without PCIe entirely (UART / JTAG / USB-debug only).
- Owner: ADR amendment; touches multiple streams.
- Time: zero engineering cost on rev A; pushes PCIe validation to rev B.
- Costs: rev A becomes a synth/PnR/RTL validation board only, not a working accelerator. Significantly weakens rev A's value proposition and the SO-DIMM upgradeability narrative.
Recommendation (Agent 4)
Option 1 is the on-mission path. ADR-001 frames upstream contributions as first-class deliverables on equal footing with our hardware. A LitePCIe ECP5 PHY would be a meaningful upstream gift, unblocks rev A, and validates that the cooperative can author non-trivial open-toolchain code, not just consume it.
Option 2 is the on-schedule path. If MVP timing trumps openness for rev A, USB3 via FT601 is the lowest-risk swap. ADR-001 amendment required.
Option 3 is the conservative path. Recommended only if both above paths run aground.
This decision is above Agent 4's authority — it touches MVP envelope, sprint pacing, and the ADR-001 commitments. Filing for human + Agent R review.
Cross-stream impact
- `stream-1`: changes which RTL block(s) live on the host-link domain.
- `stream-2`: changes which connectors / chips populate the PCB. May force a rev-A schematic rework if PCIe edge connector is already drawn.
- `stream-4`: option 1 is a stream-4 deliverable; needs prioritization above the empty-queue fallback work.
Linked artifacts
Authored by Agent 4 (Open FPGA Upstream Contributions).
Summary
ADR-001 commits rev A to PCIe Gen2 via the ECP5 hard IP as the host link, with LitePCIe as the open-toolchain controller. Agent 4's first ecosystem-health survey (popsolutions/Stays#3, doc `docs/upstream-contributions/0001-rev-a-known-upstream-issues.md`) found that LitePCIe ships no ECP5 PHY module and has zero history of ECP5 work.
Without intervention, rev A cannot use PCIe through the open toolchain, which violates ADR-001's openness commitment.
Evidence
```
init.py
axis_adapters.py
c5pciephy.py ← Cyclone V (Intel)
gw5apciephy.py ← Gowin GW5A
lfcpnxpciephy.py ← Lattice CertusPro-NX (rev-B target, supported 2024-2025)
s7pciephy.py ← Xilinx 7-series
uspciephy.py ← Xilinx UltraScale
usppciephy.py ← Xilinx UltraScale+
xilinx_tuser.py
```
There is no `ecp5pciephy.py`.
The CertusPro-NX PHY is recent (Copyright 2024-2025), so the ecosystem is moving — but ECP5 is not on its path.
Why this is rev-A blocking, not rev-B
ADR-001 deliberately picks ECP5 for rev A because the open toolchain is rock-solid for synthesis, place-and-route, and bitstream generation. The ADR table explicitly lists LitePCIe under the rev-A toolchain. CertusPro-NX (with the supported PHY) is rev-B per the same ADR — moving forward to rev-B silicon to gain PCIe defeats the rev-A purpose.
Three options (all costed)
Option 1 — Author `ecp5pciephy.py` upstream
Option 2 — Switch rev-A host link off PCIe
Option 3 — Defer PCIe to rev B with CertusPro-NX
Recommendation (Agent 4)
Option 1 is the on-mission path. ADR-001 frames upstream contributions as first-class deliverables on equal footing with our hardware. A LitePCIe ECP5 PHY would be a meaningful upstream gift, unblocks rev A, and validates that the cooperative can author non-trivial open-toolchain code, not just consume it.
Option 2 is the on-schedule path. If MVP timing trumps openness for rev A, USB3 via FT601 is the lowest-risk swap. ADR-001 amendment required.
Option 3 is the conservative path. Recommended only if both above paths run aground.
This decision is above Agent 4's authority — it touches MVP envelope, sprint pacing, and the ADR-001 commitments. Filing for human + Agent R review.
Cross-stream impact
Linked artifacts
Authored by Agent 4 (Open FPGA Upstream Contributions).