# Vivado Debug MCP

Vivado Debug MCP is a low-token hardware debug evidence layer for AI agents
working with Vivado Hardware Manager, ILA, and VIO.

It is not an autonomous FPGA debugger. It is a bridge that turns board-level
debug state, trigger plans, captures, and debug history into compact structured
evidence that an AI agent can inspect and reuse.

## Current MVP

The MVP is offline-first with a live batch bridge:

- parse a compact debug inventory text format
- expose ILA/VIO cores and probes as structured JSON
- search probes by debug intent
- generate trigger-plan templates for a selected ILA
- summarize compact capture samples into low-token debug evidence
- compare two captures to highlight changed signals and event deltas
- write debug session evidence into `.vivado_ai_mcp/debug/`
- run live inventory and capture through a fresh `vivado -mode batch` session
  (see "Live Hardware Manager" below)
- provide tests without requiring a board or Vivado Hardware Manager

## Install

Vivado Debug MCP is built into `repokey.exe`; no `pip install` and no separate
Python runtime are required. Use the CLI via `repokey-client.cmd debug ...`
and the MCP server via `repokey-client.cmd debug serve`.

## CLI

```bash
vivado-debug inventory tests/fixtures/debug_inventory.txt
vivado-debug probe-search tests/fixtures/debug_inventory.txt reset
vivado-debug probe-search tests/fixtures/debug_inventory.txt valid ready
vivado-debug trigger-plan-template tests/fixtures/debug_inventory.txt tx_issue u_ila_0 s_axis_valid s_axis_ready
vivado-debug capture-summary tests/fixtures/capture_ok.json --name capture_ok --trigger-index 2
vivado-debug capture-compare tests/fixtures/capture_ok.json tests/fixtures/capture_fault.json
vivado-debug write-session . tests/fixtures/debug_inventory.txt tx_issue --core u_ila_0 --probe s_axis_valid --probe error_flag
```

## Live ILA Display Helper

Vivado Hardware Manager can keep a Logic Analyzer tab on an empty/no-content
view after data is uploaded. Source the live helper and use
`upload_display_write_ila_data` so each capture is uploaded, displayed in the
GUI, and exported to CSV in one step:

```tcl
source <REPOKEY_HOME>/tools/ai_vitis_vivado_stack/vivado_debug_mcp/tcl/ila_capture_helpers.tcl
upload_display_write_ila_data hw_ila_1 D:/tmp/ila1.csv
upload_display_write_ila_data hw_ila_2 D:/tmp/ila2.csv
```

Replace `<REPOKEY_HOME>` with the installed package root.

For already-uploaded data objects, use:

```tcl
display_existing_ila_data hw_ila_data_1
display_existing_ila_data hw_ila_data_2
```

## Live Hardware Manager

The `live-inventory` and `live-capture` commands run a fresh Vivado batch
session against a connected hw_server/board. They generate a small,
reviewable Tcl script (temp file unless `--keep-tcl` is given) and parse the
marker-delimited stdout back into the offline models.

```bash
vivado-debug live-inventory --vivado D:/Xilinx/vivado2020.2/Vivado/2020.2/bin/vivado.bat
vivado-debug capture-tcl --ila hw_ila_1 --out-csv D:/tmp/ila1.csv --out-tcl D:/tmp/capture_ila1.tcl
vivado-debug live-capture --vivado D:/Xilinx/vivado2020.2/Vivado/2020.2/bin/vivado.bat --ila hw_ila_1 --out-csv D:/tmp/ila1.csv --ltx D:/probe/top.ltx
```

`capture-tcl` only writes the Tcl; use it for review before running. Optional
capture controls: `--trigger-probe`, `--trigger-value` (default `eq1'b1`),
`--target-glob` (default `*`), `--device-filter` (default `*`), and `--ltx`.

For repeated captures, prefer a persistent Vivado/hw_server session; each
capture then costs a trigger + upload + export instead of a ~30-40 s Vivado
startup. Project-local persistent-session helpers, if present, are optional
reference — not a required RepoKey path.

## XSCT PL Register Probe

The XSCT bridge generates a reviewable connect -> stop -> memmap -> mrd/mwr
sequence. Generation is always safe; execution requires an explicit `--xsct`
path, and writes are only generated on explicit request.

```bash
vivado-debug xsct-reg-read --addr 0x4000200c --count 4
vivado-debug xsct-reg-read --addr 0x4000200c --xsct D:/Xilinx/vivado2020.2/Vitis/2020.2/bin/xsct.bat
vivado-debug xsct-reg-write --addr 0x4000200c --value 0x1 --xsct D:/Xilinx/vivado2020.2/Vitis/2020.2/bin/xsct.bat
```

Without `--xsct` only the script is printed (or written with `--out-tcl`).
Readback lines are parsed into `{address, value}` pairs.

## MCP Server

`vivado-debug-mcp` is a FastMCP (stdio) server exposing the same service layer
as the CLI: inventory parse/search, trigger-plan templates, capture summary and
compare, ILA CSV summary, session evidence writing, live inventory/capture,
capture Tcl generation, and XSCT register probe generation/read.

```bash
repokey-client.cmd debug serve
```

Debug MCP is built into `repokey.exe`. Register it in the AI client the same way as
other MCP servers (see `MCP_REGISTRATION_TEMPLATE.json`). Live tools
(`live_inventory_tool`, `live_capture_tool`, `live_reg_read_tool`) run only when
invoked and still require a connected board, Vivado/XSCT paths, and human
intent; generation tools (`capture_tcl`, `reg_read_tcl`, `reg_write_tcl`) are
offline-safe.

Captures and session evidence live under the project's `.vivado_ai_mcp`:

```text
.vivado_ai_mcp/
  debug/
    sessions/
      <timestamp>_<issue_name>/
  evidence/
    index.json
    latest.json
```

Keep ILA CSV exports in the same project so `ila-csv-summary` /
`capture-summary` can reuse them without re-capturing.

## Debug Inventory Text Format

The parser accepts a simple line-oriented format:

```text
TARGET|name=localhost:3121|state=connected
DEVICE|target=localhost:3121|name=xc7a35t_0|part=xc7a35t
ILA|device=xc7a35t_0|name=u_ila_0|clock=clk|depth=4096
PROBE|core=u_ila_0|name=s_axis_valid|width=1|index=0
VIO|device=xc7a35t_0|name=u_vio_0|clock=clk
PROBE|core=u_vio_0|name=reset_n|width=1|direction=out
```

Later Tcl templates can emit this format, and the parser can stay independent
from Vivado execution.

## Capture Sample Format

Offline capture summaries accept a compact JSON list **or** a Vivado ILA CSV
from `live-capture`:

```json
[
  {"sys_rst_n": "1", "s_axis_valid": "0", "s_axis_ready": "1"},
  {"sys_rst_n": "1", "s_axis_valid": "1", "s_axis_ready": "1"},
  {"sys_rst_n": "1", "s_axis_valid": "1", "s_axis_ready": "0"}
]
```

ILA CSV from `live-capture` is also accepted (header + radix + samples;
`TRIGGER` plus shortened signal names). `capture-summary` / `capture-compare`
use the same loader, so a live CSV does not need a JSON conversion step.

## Evidence Store

Future live debug sessions should write:

```text
.vivado_ai_mcp/
  debug/
    sessions/
      <timestamp>_<issue_name>/
        session.json
        inventory.json
        trigger_plan.json
        capture_001_summary.json
        capture_001_events.json
        raw/
  evidence/
    index.json
    latest.json
```

Agents should read compact summaries before raw captures.

Current session files:

- `session.json`: issue metadata and project linkage
- `inventory.json`: compact ILA/VIO inventory snapshot
- `trigger_plan.json`: optional trigger template with default conditions
- `evidence/index.json`: append-only evidence history
- `evidence/latest.json`: most recent session pointer
