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 pending), plus a Python / CLI / GUI 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 optional PySide6 desktop GUI (fcapz-gui).

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 is planned — support 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), or Quartus quartus_stp (Intel/Altera USB-Blaster — hardware-validated on the DE25-Nano / Agilex 5). 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 a native desktop app? A PySide6 GUI with a built-in waveform preview ships alongside it:

pip install -e ".[gui]"     # core host stack + desktop GUI
fcapz-gui

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 and JSON-RPC 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
OpenOCD backend	✅ Hardware-validated on Gowin BRS-100; AMD/Xilinx/OpenOCD path still less exercised than hw_server
Quartus USB-Blaster (quartus_stp) backend	✅ Hardware-validated on DE25-Nano (Agilex 5)
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
UltraScale / ECP5 / PolarFire wrappers	RTL complete; host / hardware validation still limited
Efinix (Trion / Titanium) wrapper	⏳ Planned — support pending, wrapper not yet implemented
ELA / EIO / EJTAG-AXI / EJTAG-UART	✅ Validated on Arty A7 (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

# 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, GUI
examples/   Reference designs (Arty A7, Gowin BRS-100, 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
• 📝 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.