feat(skills): Vivado/Kria/Zynq/PYNQ skills + governance gap fixes#164
Merged
Conversation
…to vivado
Adds two critical Vivado workflow improvements to the hardware skills:
1. Extended existing �ivado skill with:
- Nuclear rebuild rule (CRITICAL): delete .work/vivado/ after ANY RTL change;
incremental builds silently produce stale netlists -- #1 source of 'my
code changes aren't in hardware' bugs
- Working directory discipline: always run vivado from .work/vivado/, never
from repo root (prevents vivado.log/.jou/.Xil/ pollution of git)
- Vivado detection on Windows (C:\\Xilinx\\Vivado and C:\\AMDDesignTools paths)
2. New �ivado-kria-zynq skill covering:
- Target HW reference table (KV260 xck26-sfvc784-1-e, KR260 -2LV-c, ZCU106)
- PS + Clocking Wizard block design Tcl (100 MHz -> 400 MHz PL)
- AXI4-Lite SmartConnect register map pattern (address assignment)
- Bitstream generation: write_cfgmem -format BIN for fpgautil .bit.bin
- fpgautil loading via SSH (scp + sudo fpgautil -b) and sysfs fallback
- MMIO / AXI register access from Python (/dev/mem mmap pattern)
- Kria UltraScale+ XDC: PS clock auto-constraint, async clock groups,
LVCMOS18/LVCMOS33 bank standards
- XSDB JTAG programming script (PSU + A53 target pattern)
- 8 Kria-specific common pitfalls (fpgautil format, MMIO sudo, CDC, etc.)
Derived from battle-tested patterns in cpsc-engine-rtl (Layer1Labs WARP.md
and KV260_BITSTREAM_WORKFLOW.md), validated on xck26 SOM in production.
Co-Authored-By: Oz <oz-agent@warp.dev>
governance_logic.py (port 7700 — used by kairos): - Add /api/audit alias for /api/governance/audit; normalise response to include ok, fixable, name fields (matching AuditStatusResponse) - Add GET /api/session/context-seed via build_context_seed() - Add POST /api/session/clear — wipes session-state + history files - Add GET /api/dispatch/list via EventEmitter.list_runs() - Update startup banner to list all extended endpoints eval/runner.py: - Replace EventEmitter(stream=None) crash with io.StringIO() sink - Add run_case_real to __all__ cli.py (eval run): - Add --real flag to specsmith eval run with SPECSMITH_EVAL_PROJECT env injection and per-result error display serve.py: - Add GET /api/audit to module docstring endpoint list Co-Authored-By: Oz <oz-agent@warp.dev>
- Rename vivado-kria-zynq → vivado-zynq-ps-pl (generic, no cpsc refs)
Covers all Zynq boards: PYNQ-Z1/Z2, ZedBoard, Ultra96, KV260, KR260, ZCU106.
Separate PS7 (Zynq-7000) and zynq_ultra_ps_e (UltraScale+) Tcl sections.
Platform-aware deploy: fpgautil (Kria/UltraScale+), PYNQ Overlay, XSCT JTAG.
Generic MMIO /dev/mem helper. Hardware handoff (.xsa/.hwh) for Vitis/PYNQ.
- Expand vivado skill (generic) with:
- Platform table: Windows=primary, Linux=supported, macOS=NOT SUPPORTED
- Windows detection: C:\\Xilinx\\Vivado + C:\\AMDDesignTools + XILINX_VIVADO env
- Linux detection: /tools/Xilinx and /opt/Xilinx, settings64.sh, PATH setup
- Vivado toolchain ecosystem diagram (Vivado, xsim, ILA, HW Manager,
write_cfgmem, updatemem, Vitis, Vitis HLS, XSCT, XSDB)
- Common proven targets table (12 boards: Arty A7-35/100, Basys3, Nexys A7,
PYNQ-Z1/Z2, ZedBoard, Ultra96-v2, KV260, KR260, ZCU106 with part numbers)
- Board files install (xhub auto-install + manual Digilent procedure)
- Tcl project/build template with proper repo_root detection
- XDC: clock, false path, multicycle path, physical pins
- Timing report reading (WNS/TNS/WHS interpretation guide)
- IP Integrator with PS7 block design + wrapper generation
- ILA: mark_debug RTL attribute + post-synth + probes.ltx
- xsim: xvlog/xelab/xsim CLI + Tcl launch_simulation
- XSCT: generic Zynq/UltraScale+ program_device.tcl
- Hardware handoff write_hw_platform + Vitis BSP note
- IP packaging ipx::package_project workflow
- Nuclear rebuild: Windows (PowerShell) + Linux (bash) variants
- Working directory discipline (CRITICAL)
- Complete .gitignore for Vivado projects
- macOS not supported note in common pitfalls
- New pynq skill (slug: pynq):
- PYNQ-Z1 vs Z2 specs (part, LUTs, RAM, board files)
- Board access: SSH, Jupyter browser, USB UART serial
- Core Python APIs: Overlay, MMIO, GPIO/AxiGPIO, DMA, Clocks, allocate
- Loading overlay (.bit + .hwh requirement)
- MMIO: base address, word read/write, byte array
- GPIO AxiGPIO channel API
- DMA: allocate() contiguous buffers, sendchannel/recvchannel
- Clocks.fclk0_mhz/fclk1_mhz
- Custom overlay dev workflow (5-step: Vivado → .xsa → .hwh → deploy → load)
- Jupyter inline plot tips + timing measurement
- 8 common pitfalls (hwh missing, addr mismatch, USB RNDIS Windows driver,
PYNQ 2.x vs 3.x, DMA HP port, Z1 vs Z2 fabric size, default password,
board file install)
Co-Authored-By: Oz <oz-agent@warp.dev>
…iple-quote docstring Two issues in new Vivado skill bodies broke Python 3.12 compilation: 1. vivado body: Windows path backslashes (invalid escape \.) -> use forward slashes in Nuclear rebuild PowerShell examples 2. vivado-zynq-ps-pl body: triple-quoted docstring inside code example prematurely closed outer body string -> changed to single-quote style Both caused SyntaxError preventing skills module from loading. 791 tests pass. Co-Authored-By: Oz <oz-agent@warp.dev>
- eval/runner.py: case.input -> case.prompt (EvalCase has .prompt not .input) - cli.py L8833: wrap console.print() call to stay under 100-char limit - hardware.py L227: shorten macOS table row from 123->91 chars All CI checks should now pass: lint, typecheck, test. Co-Authored-By: Oz <oz-agent@warp.dev>
The CRLF line ending added an extra byte making ruff see 104 not 103. Shortened macOS table row to 64 chars (well under 100 limit). Co-Authored-By: Oz <oz-agent@warp.dev>
Co-Authored-By: Oz <oz-agent@warp.dev>
- hardware.py: add '## HDL — Verilog vs VHDL' section to vivado skill explaining that devs typically pick one primary HDL; mixed environments arise when vendor/IP cores arrive in the other language - vivado tags: add systemverilog, sv - vivado body: update xsim section to show xvlog (Verilog/SV) and xvhdl (VHDL); update ILA debug comment to cover all HDLs; add VHDL glob comments in TCL - vivado-zynq-ps-pl: add verilog/systemverilog/vhdl tags; add PL HDL note - quartus-prime: add VHDL_FILE example; add HDL choice section - pynq: add verilog/vhdl tags - dev-release.yml: add rolling GitHub pre-release (latest-dev) for dev builds; channel stays on 'latest' not 'stable'; mark as --no-latest - release.yml: use --no-latest during dev phase; add first-stable-release note (TODO: flip to --latest when first official stable ships) Co-Authored-By: Oz <oz-agent@warp.dev>
- docs/site/kairos-terminal.md: installation, architecture, settings, AI provider config, context window, update channels, pitfalls - mkdocs.yml: promote 'Kairos Terminal' to a first-class nav section with Overview+Install page + dispatch sub-page Note: kairos uses specsmith's RTD site (no separate RTD project needed) since both are tightly coupled (kairos requires specsmith to run). Co-Authored-By: Oz <oz-agent@warp.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
New Vivado/FPGA Skills (hardware.py)
Governance Gap Fixes
un_case_real\ now uses \io.StringIO()\ sink; exported in _all_\
Bug Fixes
Tests
791/791 passing, 0 warnings
Co-authored-by: Oz oz-agent@warp.dev