Claude Skill

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

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download al-nafisah-fpga-project-analyzer-skills_fpga-project-analyzer-e5b0d0a.zip · 566 KB

Install

skills CLI npx skills add https://github.com/al-nafisah/fpga-project-analyzer/tree/main/skills/fpga-project-analyzer
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install al-nafisah-fpga-project-analyzer@llmmart
Git 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

  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)

{"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.

No comments yet.

Reviews (0)

No reviews yet.