fpga-project-analyzer
Analyze and explain existing AMD/Xilinx FPGA projects visually - Vivado block designs (.xpr, .bd, .hwh, .xsa, BD Tcl), Verilog/SystemVerilog/VHDL, PYNQ overlays and notebooks, HLS/bare-metal C, device trees, timing/DRC reports and build logs. Builds a drill-down Vivado-style diag
Install
npx skills add https://github.com/al-nafisah/fpga-project-analyzer/tree/main/skills/fpga-project-analyzer
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install al-nafisah-fpga-project-analyzer@llmmart
git clone https://github.com/al-nafisah/fpga-project-analyzer.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole al-nafisah/fpga-project-analyzer collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
FPGA Project Analyzer
Scripts read the project; you read their compact output. Do not open .bd/.hwh/.xpr/report files directly.
FPA below stands for python3 <this skill's directory>/scripts/fpa.py; type the full command each time
(a shell variable does not word-split in zsh). Outputs go to <project>/.fpa/.
Workflow
FPA build <project>- extracts everything, runs the checks, prints a ~40-line summary (blocks, clock domains, streams, AXI-MM, IRQ -> GIC/DT numbers, address map, software refs, reports, findings). Repo with several boards/builds or a Makefile flow: point it at the build's own lists instead of scanning, e.g.--src sim/plps.d --src sim/psbd.d(make .d / .f / .lst files, dirs or globs; repeatable).- Drill into what matters, never the whole tree:
FPA show <project> <block>one block (/= top,/stream_proc/scaler_0= nested): pins, peers, net names, clock domains, address, registers, software refs, src file:line; add--netsto list the nets inside the block aslevel|netkeysFPA findings <project>all findings with detail and fixFPA logs <file>failed build: grouped errors (Vivado, HLS, PetaLinux/Yocto task logs, gcc)FPA reports <dir>timing / utilization / DRC / methodology facts from existing .rpt files
- Open source files only at the file:line that
showgives, only to confirm a finding or a block's role. - Write
<project>/.fpa/overlay.json(schema below): a role note for each key block, 1-2 flows, and review findings. FPA view <project>->.fpa/design.html(offline, single file); it warns about overlay paths or nets that do not resolve. Deep links:design.html#/hier/block,?issues=1(issue list),?sel=/hier/block(block panel),?theme=dark. The viewer's Export menu saves the current level as SVG/PNG.- For documentation requests:
FPA doc <project>->.fpa/design.mdwith SVG diagrams and tables.
How to answer
- Visual first: give the file:// link and deep links, then at most 6 short bullets. No pasted reports or long prose.
- "Explain the design" = overlay notes (3-8 words per block) + flows, so the diagram carries the explanation.
- Each finding: what, where (path, file:line), why it breaks hardware, the fix (exact code/Tcl/XDC when short).
- Lint findings (
"by":"lint") are candidates; confirm withshowand the source before calling them bugs. Lint is structural; it cannot see functional bugs such as pipeline misalignment or protocol violations. - For any "what's wrong" or review request, read
references/review.mdonce and check the RTL it points to.
Overlay schema (.fpa/overlay.json)
{"notes": {"/axi_dma_0": "DDR <-> stream mover"},
"flows": [{"name": "sample path", "nets": ["|axi_dma_0_M_AXIS_MM2S", "/stream_proc|S_AXIS_1"]}],
"findings": [{"sev": "high|med|low|info", "path": "/stream_proc/stream_scaler_0", "title": "...",
"detail": "...", "fix": "...", "src": {"file": "rtl/x.v", "line": 19},
"net": "gain_q", "level": "/stream_proc/stream_scaler_0"}]}
Flow nets are <level path>|<net name> exactly as show <project> <level> --nets prints them; the top level is
the empty path (|net). net + level on a finding draws that wire red.
Vivado (optional, auto-detected)
FPA deep <project> --top <module>: Vivado-elaborated netlist (RTL_REG, RTL_MUX, operators) for the lowest level; merged on the next build. Use when the user wants gate/RTL-cell detail.FPA vivado-reports <run.dcp|project.xpr>: runs report_cdc, clock interaction, timing, DRC, methodology.FPA build <project> --vivado on: sources the project's BD Tcl in Vivado for exact pins. This executes project code - ask the user before using it on a repository they did not write.
Limits
Light RTL parsing (no Vivado) evaluates VHDL generics and if/case ... generate conditions (a
condition it cannot evaluate keeps its branch), draws a for ... generate once, and does not evaluate
Verilog generates; when hierarchy looks wrong, say so and offer deep. BD Tcl that relies on apply_bd_automation is only partly readable
without Vivado (the summary says so).
Files (fpga-project-analyzer)
-
references
-
review.md 5.2 KB
Loading…
-
-
scripts
-
fpalib
-
assets
-
vendor
-
ELK-LICENSE.md 14.1 KB
Loading… -
elk.bundled.js 1.5 MB
Loading…
-
-
viewer.html 51.3 KB · in bundle
-
-
vivado
-
clock_map.tcl 1.5 KB · in bundle
-
export_bd.tcl 2.2 KB · in bundle
-
reports.tcl 670 B · in bundle
-
rtl_netlist.tcl 2.3 KB · in bundle
-
-
bdjson.py 8.2 KB
Loading… -
bdtcl.py 20.2 KB
Loading… -
build.py 22.3 KB
Loading… -
cli.py 6 KB
Loading… -
doc.py 7.1 KB
Loading… -
hdl.py 73.5 KB
Loading… -
hwh.py 12.3 KB
Loading… -
lint.py 28.1 KB
Loading… -
mcp.py 8.3 KB
Loading… -
model.py 4.4 KB
Loading… -
refs.py 8 KB
Loading… -
reports.py 11.5 KB
Loading… -
summary.py 12.2 KB
Loading… -
viewer.py 3 KB
Loading… -
vivado.py 11 KB
Loading… -
xdc.py 3.9 KB
Loading… -
__init__.py 81 B
Loading…
-
-
fpa.py 276 B
Loading…
-
-
SKILL.md 4.7 KB
--- name: fpga-project-analyzer description: Analyze and explain existing AMD/Xilinx FPGA projects visually - Vivado block designs (.xpr, .bd, .hwh, .xsa, BD Tcl), Verilog/SystemVerilog/VHDL, PYNQ overlays and notebooks, HLS/bare-metal C, device trees, timing/DRC reports and build logs. Builds a drill-down Vivado-style diagram (block design -> IP -> RTL -> registers) and finds bugs - clock-domain crossings, unconstrained I/O, reset polarity, address map, interrupts, PYNQ overlay mistakes. Use when asked to understand, review, document or debug an FPGA, Zynq, MPSoC or PYNQ project, or a failed Vivado build. --- # FPGA Project Analyzer Scripts read the project; you read their compact output. Do not open .bd/.hwh/.xpr/report files directly. `FPA` below stands for `python3 <this skill's directory>/scripts/fpa.py`; type the full command each time (a shell variable does not word-split in zsh). Outputs go to `<project>/.fpa/`. ## Workflow 1. `FPA build <project>` - extracts everything, runs the checks, prints a ~40-line summary (blocks, clock domains, streams, AXI-MM, IRQ -> GIC/DT numbers, address map, software refs, reports, findings). Repo with several boards/builds or a Makefile flow: point it at the build's own lists instead of scanning, e.g. `--src sim/plps.d --src sim/psbd.d` (make .d / .f / .lst files, dirs or globs; repeatable). 2. Drill into what matters, never the whole tree: - `FPA show <project> <block>` one block (`/` = top, `/stream_proc/scaler_0` = nested): pins, peers, net names, clock domains, address, registers, software refs, src file:line; add `--nets` to list the nets inside the block as `level|net` keys - `FPA findings <project>` all findings with detail and fix - `FPA logs <file>` failed build: grouped errors (Vivado, HLS, PetaLinux/Yocto task logs, gcc) - `FPA reports <dir>` timing / utilization / DRC / methodology facts from existing .rpt files 3. Open source files only at the file:line that `show` gives, only to confirm a finding or a block's role. 4. Write `<project>/.fpa/overlay.json` (schema below): a role note for each key block, 1-2 flows, and review findings. 5. `FPA view <project>` -> `.fpa/design.html` (offline, single file); it warns about overlay paths or nets that do not resolve. Deep links: `design.html#/hier/block`, `?issues=1` (issue list), `?sel=/hier/block` (block panel), `?theme=dark`. The viewer's Export menu saves the current level as SVG/PNG. 6. For documentation requests: `FPA doc <project>` -> `.fpa/design.md` with SVG diagrams and tables. ## How to answer - Visual first: give the file:// link and deep links, then at most 6 short bullets. No pasted reports or long prose. - "Explain the design" = overlay notes (3-8 words per block) + flows, so the diagram carries the explanation. - Each finding: what, where (path, file:line), why it breaks hardware, the fix (exact code/Tcl/XDC when short). - Lint findings (`"by":"lint"`) are candidates; confirm with `show` and the source before calling them bugs. Lint is structural; it cannot see functional bugs such as pipeline misalignment or protocol violations. - For any "what's wrong" or review request, read `references/review.md` once and check the RTL it points to. ## Overlay schema (.fpa/overlay.json) ```json {"notes": {"/axi_dma_0": "DDR <-> stream mover"}, "flows": [{"name": "sample path", "nets": ["|axi_dma_0_M_AXIS_MM2S", "/stream_proc|S_AXIS_1"]}], "findings": [{"sev": "high|med|low|info", "path": "/stream_proc/stream_scaler_0", "title": "...", "detail": "...", "fix": "...", "src": {"file": "rtl/x.v", "line": 19}, "net": "gain_q", "level": "/stream_proc/stream_scaler_0"}]} ``` Flow nets are `<level path>|<net name>` exactly as `show <project> <level> --nets` prints them; the top level is the empty path (`|net`). `net` + `level` on a finding draws that wire red. ## Vivado (optional, auto-detected) - `FPA deep <project> --top <module>`: Vivado-elaborated netlist (RTL_REG, RTL_MUX, operators) for the lowest level; merged on the next build. Use when the user wants gate/RTL-cell detail. - `FPA vivado-reports <run.dcp|project.xpr>`: runs report_cdc, clock interaction, timing, DRC, methodology. - `FPA build <project> --vivado on`: sources the project's BD Tcl in Vivado for exact pins. This executes project code - ask the user before using it on a repository they did not write. ## Limits Light RTL parsing (no Vivado) evaluates VHDL generics and `if`/`case ... generate` conditions (a condition it cannot evaluate keeps its branch), draws a `for ... generate` once, and does not evaluate Verilog generates; when hierarchy looks wrong, say so and offer `deep`. BD Tcl that relies on apply_bd_automation is only partly readable without Vivado (the summary says so).
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.