fpgacapZero

fpgacapZero (fcapz)

Open-source FPGA debug cores — in native Verilog and VHDL — that you drop into any design to see and control what’s happening inside your FPGA over JTAG: no extra board pins, no soft CPU, no vendor lock-in.

Think of it as an open, vendor-neutral alternative to ChipScope / SignalTap / Reveal that works the same way across AMD/Xilinx, Intel/Altera, Lattice, Gowin, and Microchip parts (with Efinix support synthesized in Efinity, hardware validation pending), plus a Python / CLI / web host stack on top.

📖 New here? Start with the User Manual — especially First capture in 10 minutes. This page is just the quick tour.

What’s in the box

Four small RTL cores, all driven over JTAG:

• ELA — Embedded Logic Analyzer — capture internal signals into a waveform with flexible triggers, and export to VCD / CSV / JSON.
• EIO — Embedded I/O — read and drive fabric signals live at runtime.
• EJTAG-AXI — a JTAG-to-AXI4 master bridge for memory-mapped bus access.
• EJTAG-UART — a JTAG-to-UART console bridge.

Plus a host stack: a browser-based web interface (fcapz-web) with an embedded Surfer waveform viewer that you can reach from the local machine or across the network, a Python API, the fcapz command-line tool, a JSON-RPC server, and an MCP server (fcapz-mcp) that exposes the lab controls to coding agents.

Why fpgacapZero

• Vendor-agnostic — one portable core with thin TAP wrappers for AMD/Xilinx 7-series, AMD/Xilinx UltraScale / UltraScale+, Lattice ECP5, Intel / Altera, Gowin, and Microchip PolarFire-family devices. An Efinix (Trion / Titanium) wrapper (two JTAG User TAP blocks via the Efinity Interface Designer) synthesizes, places and routes in Efinity on Trion and Titanium; hardware validation is pending.
• Small, and only as big as you need — a usable 8-bit / 1024-sample ELA fits in about 600 LUTs + 0.5 BRAM. Extra triggers, timestamps, decimation, segmenting, and more are compile-time options you enable only when a design needs them.
• Verilog and VHDL — the portable core ships as native Verilog and native VHDL, with shared regression coverage for both.
• Apache-2.0 — usable in proprietary designs.

Will it work on my board?

Any board with JTAG access works. You drive it through OpenOCD (any OpenOCD-supported adapter — FTDI, WCH CH347, CMSIS-DAP, J-Link, …), the AMD/Xilinx hw_server (Vivado — hardware-validated on the Arty A7 and on the Kria KV260, a Zynq UltraScale+ MPSoC), or Quartus quartus_stp (Intel/Altera USB-Blaster — hardware-validated on the DE25-Nano / Agilex 5), or directly over an FTDI cable (--backend ftdi: the FlashPro5 on Microchip boards or a Digilent cable, no OpenOCD or vendor server — hardware-validated on the PolarFire SoC Discovery Kit). A board with no JTAG to the fabric can use the serial TAP bridge instead: two spare pins and a UART (--backend serial; hardware-validated on the Forgix board’s Efinix Trion). On Zynq UltraScale+ MPSoC parts (xck*, xczu*) the host picks the PS TAP’s chain mode from the tap name, so all four USER chains work with no extra setup. The full per-vendor matrix and JTAG-chain rules are in the manual’s RTL integration chapter; see also Support status below.

Quick start

You need Python 3.10+, a JTAG-capable FPGA board, and one of OpenOCD, Vivado hw_server, or Quartus quartus_stp (Intel/Altera USB-Blaster). Full setup is in Installation.

git clone https://github.com/lcapossio/fpgacapZero.git
cd fpgacapZero
pip install -e ".[web]"      # core host stack + web interface
fcapz-web                    # the easiest way to take your first capture

Then open http://127.0.0.1:7373 in your browser: connect to the board, arm an ELA capture with the run controls, set triggers, and inspect the result in the embedded Surfer waveform viewer — EIO and JTAG-AXI live there too. It runs over the same JSON-RPC API as the rest of the stack and can be exposed across the network with a bearer token. See Web interface.

Prefer the command line? Build the Arty A7 reference bitstream (see Build from source — or use your own), then capture:

fcapz --backend hw_server --port 3121 \
  --program examples/arty_a7/arty_a7_vex_top.bit \
  capture --trigger-value 0 --trigger-mask 0xFF --out capture.vcd --format vcd

The end-to-end walkthrough lives in First capture in 10 minutes. For every command and flag, see the CLI reference; for scripting, the Python API (every signature in the API reference) and JSON-RPC server. For driving fpgacapZero from a coding agent, see the MCP server.

Add it to your design

One instantiation per core — swap the wrapper suffix to match your FPGA vendor:

wire [127:0] my_signals;

// Embedded Logic Analyzer (all JTAG plumbing bundled inside the wrapper)
fcapz_ela_xilinx7 #(.SAMPLE_W(128), .DEPTH(4096)) u_ela (
    .sample_clk (sys_clk),
    .sample_rst (reset),
    .probe_in   (my_signals)
);

That’s the minimal ELA. Wrapper names follow fcapz_<core>_<vendor> (e.g. fcapz_ela_ecp5, fcapz_eio_intel). Every parameter, the EIO / AXI / UART cores, LiteX integration, VHDL sources under rtl/vhdl/, and the per-vendor JTAG-chain rules are covered in RTL integration. The canonical register / shift maps live in docs/specs/register_map.md.

Support status

Area	Status
AMD/Xilinx hw_server backend	✅ Hardware-validated on Arty A7 and Kria KV260 (Zynq UltraScale+ MPSoC)
OpenOCD backend	✅ Hardware-validated on Gowin BRS-100 and the PolarFire SoC Discovery Kit; AMD/Xilinx/OpenOCD path still less exercised than hw_server
Quartus USB-Blaster (quartus_stp) backend	✅ Hardware-validated on DE25-Nano (Agilex 5)
Direct FTDI backend (--backend ftdi, FTDI D2XX)	✅ Hardware-validated on the PolarFire SoC Discovery Kit’s embedded FlashPro5
Serial TAP bridge (--backend serial, fcapz_ela_uart)	✅ Hardware-validated on Forgix (Efinix Trion T8F49, over its configuration pins)
AMD/Xilinx 7-series wrappers	✅ Hardware-validated on Arty A7-100T
Gowin wrapper	✅ Hardware-validated on BRS-100-GW1NR9
Intel / Altera wrapper	✅ Hardware-validated on DE25-Nano (Agilex 5) via USB-Blaster
Microchip PolarFire wrapper	✅ Hardware-validated on the PolarFire SoC Discovery Kit (MPFS095T) over OpenOCD
AMD/Xilinx UltraScale / UltraScale+ wrappers	✅ Hardware-validated on Kria KV260 (xck26) and on a Kintex UltraScale KU035 (proprietary board); standalone UltraScale+ not yet tested
ECP5 wrappers	RTL complete; host / hardware validation still limited
Efinix (Trion / Titanium) wrapper	⏳ Synthesized, placed and routed in Efinity 2025.1 (Trion T20F256, Titanium Ti60F225); hardware validation pending
ELA / EIO / EJTAG-AXI / EJTAG-UART	✅ Validated on Arty A7 and Kria KV260 (details in the manual)

The full, always-current matrix is in Overview and RTL integration.

Build from source

# Build the Arty A7 reference bitstream (Vivado)
python examples/arty_a7/build.py

# Or the Kria KV260 one (Zynq UltraScale+ MPSoC; needs the kv260_som board files)
python examples/kv260/build.py

# Run the host test suite — no hardware needed
pip install -e ".[dev,hdl]"
pytest tests/ -v

RTL simulation (Icarus / Verilator / cocotb / GHDL), the VHDL parity gates, the CI jobs, and the hardware-in-the-loop tests are all documented in CONTRIBUTING.md. Live CI status is the badge at the top.

Project layout

rtl/        Portable Verilog cores + vendor TAP wrappers (VHDL in rtl/vhdl/)
host/fcapz/ Python host stack: Analyzer, transports, CLI, RPC, web, MCP
examples/   Reference designs (Arty A7, Kria KV260, DE25-Nano, Gowin BRS-100,
            PolarFire SoC Discovery Kit, Forgix, and more)
docs/       User manual (start at docs/README.md) + canonical specs
tb/, sim/   Testbenches and simulation runners

Project links

• 📖 User Manual — the complete guide; it also builds into a searchable HTML site (mkdocs serve)
• 📝 CHANGELOG — releases, with breaking changes called out
• 🤝 CONTRIBUTING — dev setup, testing, adding a board
• 🐛 Troubleshooting — common errors and fixes

Author

Leonardo Capossio — bard0 design — [email protected]

Contributors

• Brisbane Silicon

Sponsoring

If fpgacapZero helps your FPGA debug flow, you can support continued development through GitHub Sponsors.

License

Apache License 2.0 — see LICENSE for details.