Metadata-Version: 2.4
Name: fpgacapzero
Version: 0.4.9
Summary: Open-source, vendor-agnostic full-featured FPGA debug cores
Author-email: Leonardo Capossio - bard0 design <hello@bard0.com>
License: Apache-2.0
Project-URL: Homepage, https://bard0.com/projects/fcapz.html
Project-URL: Repository, https://github.com/lcapossio/fpgacapZero/
Project-URL: Issues, https://github.com/lcapossio/fpgacapZero/issues
Project-URL: Changelog, https://github.com/lcapossio/fpgacapZero/blob/main/CHANGELOG.md
Keywords: fpga,debug,vhdl,verilog,axi
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Requires-Dist: tomli-w>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-qt>=4.2; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Provides-Extra: gui
Requires-Dist: PySide6>=6.6; extra == "gui"
Requires-Dist: pyqtgraph>=0.13; extra == "gui"
Provides-Extra: gui-preview
Requires-Dist: fpgacapzero[gui]; extra == "gui-preview"
Provides-Extra: hdl
Requires-Dist: cocotb>=2; extra == "hdl"
Requires-Dist: cocotb-tools>=0.1.0; extra == "hdl"
Requires-Dist: cocotbext-axi>=0.1.26; extra == "hdl"
Provides-Extra: litex
Requires-Dist: litex; extra == "litex"
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn[standard]>=0.27; extra == "web"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/lcapossio/fpgacapZero/main/docs/assets/fcapz-logo.png" alt="fpgacapZero logo" width="180">
</p>

# fpgacapZero (fcapz)

[![CI](https://github.com/lcapossio/fpgacapZero/actions/workflows/ci.yml/badge.svg)](https://github.com/lcapossio/fpgacapZero/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/lcapossio/fpgacapZero/blob/main/LICENSE)
[![Sponsor](https://img.shields.io/github/sponsors/lcapossio?logo=githubsponsors&label=Sponsor)](https://github.com/sponsors/lcapossio)

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](https://github.com/lcapossio/fpgacapZero/blob/main/docs/README.md)** — especially
> **[First capture in 10 minutes](https://github.com/lcapossio/fpgacapZero/blob/main/docs/03_first_capture.md)**. 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 FTDI
adapter), 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](https://github.com/lcapossio/fpgacapZero/blob/main/docs/04_rtl_integration.md); see also
[Support status](#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](https://github.com/lcapossio/fpgacapZero/blob/main/docs/02_install.md).

```bash
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](https://github.com/lcapossio/fpgacapZero/blob/main/docs/18_web_interface.md)**.

<p align="center">
  <img src="https://raw.githubusercontent.com/lcapossio/fpgacapZero/main/docs/assets/fcapz-web-demo.png" alt="fcapz-web browser interface showing connection, ELA capture controls, and the embedded Surfer waveform viewer" width="900">
</p>

Prefer a native desktop app? A PySide6 GUI with a built-in waveform preview
ships alongside it:

```bash
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](#build-from-source) — or use your own), then capture:

```bash
fcapz --backend hw_server --port 3121 \
  --program examples/arty_a7/arty_a7_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](https://github.com/lcapossio/fpgacapZero/blob/main/docs/03_first_capture.md)**. For every command
and flag, see the [CLI reference](https://github.com/lcapossio/fpgacapZero/blob/main/docs/10_cli_reference.md); for scripting, the
[Python API](https://github.com/lcapossio/fpgacapZero/blob/main/docs/09_python_api.md) and [JSON-RPC server](https://github.com/lcapossio/fpgacapZero/blob/main/docs/11_rpc_server.md).

## Add it to your design

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

```verilog
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](https://github.com/lcapossio/fpgacapZero/blob/main/docs/04_rtl_integration.md)**.
The canonical register / shift maps live in
[`docs/specs/register_map.md`](https://github.com/lcapossio/fpgacapZero/blob/main/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](https://github.com/lcapossio/fpgacapZero/blob/main/docs/01_overview.md) and
[RTL integration](https://github.com/lcapossio/fpgacapZero/blob/main/docs/04_rtl_integration.md).

## Build from source

```bash
# 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](https://github.com/lcapossio/fpgacapZero/blob/main/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](https://github.com/lcapossio/fpgacapZero/blob/main/docs/README.md)** — the complete guide
- 📝 **[CHANGELOG](https://github.com/lcapossio/fpgacapZero/blob/main/CHANGELOG.md)** — releases, with breaking changes called out
- 🤝 **[CONTRIBUTING](https://github.com/lcapossio/fpgacapZero/blob/main/CONTRIBUTING.md)** — dev setup, testing, adding a board
- 🐛 **[Troubleshooting](https://github.com/lcapossio/fpgacapZero/blob/main/docs/17_troubleshooting.md)** — common errors and fixes

## Author

Leonardo Capossio — [bard0 design](https://www.bard0.com) — <hello@bard0.com>

## Contributors

- [Brisbane Silicon](https://github.com/BrisbaneSilicon)

## Sponsoring

If fpgacapZero helps your FPGA debug flow, you can support continued
development through [GitHub Sponsors](https://github.com/sponsors/lcapossio).

## License

Apache License 2.0 — see [LICENSE](https://github.com/lcapossio/fpgacapZero/blob/main/LICENSE) for details.
