GarageWorks

Status: beta release. APIs, directory layout, and build flow may change.

GarageWorks is a lightweight FPGA testing framework that lets the same cocotb testbench run on both software RTL simulation and FPGA hardware. See docs/garageworks.md for more, and docs/ for tutorials and development notes.

Setup

1. Python environment

Use conda or a venv; either works.

conda:

conda create -n garage python=3.11 pip
conda activate garage

venv:

python3 -m venv .venv
source .venv/bin/activate

Then install GarageWorks (see docs/garageworks.md for why the version is left unpinned):

pip install garageworks

To work on GarageWorks itself instead, clone this repo and install it in editable mode: pip install -e python/.

2. Other tools

• SBT for Chisel RTL generation (pinned version in project/build.properties)
• Verilator for cocotb simulation (sh misc/build_verilator.sh INSTDIR, then add INSTDIR/bin to PATH)
• FPGA tests additionally need Vivado/Vitis and an AMD Alveo V80 + AVED board; see docs/development-notes.md for versions and setup.

Try it: the SRV32I example

SRV32I is a small RISC-V core that demonstrates the full GarageWorks workflow, from RTL generation and cocotb simulation through FPGA testing.

git clone https://github.com/hwspec/SRV32I
cd SRV32I

Run the cocotb simulation test:

gwscript

Run the FPGA test (after sourcing your Vitis/Vivado environment):

gwscript --fpga

Run only specific test targets, or list them:

gwscript cocotb base      # cocotb test target(s); default: tests= in .gwconfig
gwscript cocotb -l        # list available test targets (same for testhw)

gwscript options go before the stage name (gwscript --fpga testhw base).

See gwscript --help and SRV32I's README for more (FPGA env variables, etc.). To drive gwscript from Claude Code or another MCP client, see docs/mcp-claudecode-example.md.

gws is installed as a shorter alias for gwscript.

Test your own design

docs/tutorial-chisel-dut.md walks through taking a plain Chisel module, generating its GarageWorks Command Dispatcher (AXI4-Lite wrapper + test spec) with gwscript --gwcd (uses an Anthropic or OpenAI API key; pip install "garageworks[gwcd]"), and running it in simulation and on FPGA.

gwtests/ file naming

The test directory (testdir= in .gwconfig, gwtests/ by default) uses these names:

File	Role
tb_<name>.py	A GarageWorks testbench (cocotb). Must start with tb_; <name> is the test target name used in tests=, TARGETS, and gwscript cocotb <name>
fpga_tb_<name>.py	Hardware version of tb_<name>.py, generated by conv_cocotb_to_fpga when running hw_<name> / testhw. Temporary: don't edit or commit it; make clean removes it
<pkg>.mk	Project settings for Makefile.gw (TARGETS, module name, bridge). <pkg> is the package in chiseltop=. Keep only one *.mk here, since Makefile.gw includes them all
<pkg>_bridge.py	Project-specific bridge used by the testbenches
Makefile.gw	Common Makefile: make -f Makefile.gw <name> (simulation), hw_<name> (FPGA), list

License

BSD. See LICENSE.

Contact

For questions, bug reports, or feature requests, please open an issue on GitHub. For general discussion, please use GitHub Discussions.