gwaihir 🦅

gwaihir is an open-source research platform focusing on AI and Machine Learning acceleration.

gwaihir is developed as part of the PULP (Parallel Ultra-Low Power) project, a joint effort between ETH Zurich and the University of Bologna. gwaihir is also supported by the EUPilot project, under the name MLS.

⚡ Getting started

Environment setup for IIS-members

For IIS-members, the environment can be set up by sourcing the iis-env.sh script:

source iis-env.sh

This will set up all environment variables, and install the virtual python environment, which is needed to generate the RTL and SW sources.

Environment setup for non-IIS members

For non-IIS members, there is some additional setup required to get the environment up and running.

Bender

The first requirement you need to install is bender. Check the installation page on how to set it up.

Python environment

To generate certain source files with python you need to have uv installed, which will create the virtual environment and install the required dependencies. To set up the environment, run:

uv sync --locked
source .venv/bin/activate

Toolchains

Gwaihir requires two different toolchains at the moment:

• Snitch software tests require the Clang compiler extended with Snitch-specific instructions. There are some precompiled releases available on the PULP Platform LLVM Project fork that are ready to be downloaded and unzipped.
• Cheshire requires a 64-bit GCC toolchain that can be installed from the riscv-gnu-toolchain git following the Installation (Newlib) instructions.

Once LLVM and GCC are obtained, export a LLVM_BINROOT environment variable to the binary folder of the LLVM toolchain installation. Then, add the GCC binary folder to your $PATH:

export LLVM_BINROOT=/path/to/llvm/bin
export PATH=$PATH:/path/to/gcc/bin

Git hooks

Commits are checked by pre-commit hooks, run with prek. They verify the SPDX license headers, format and lint the SystemVerilog sources with verible, and apply a few general hygiene checks. CI runs the very same hooks, so having them installed locally avoids the most common CI failures.

Sourcing iis-env.sh installs them for you. Otherwise, install them once after setting up the Python environment:

prek install

prek comes from the Python environment, and each hook fetches its own pinned tools on first run, so nothing needs to be installed by hand. To run every hook manually, without committing:

prek run --all-files

RTL code generation

After setting up the environment, you can generate all the RTL code for Cheshire, FlooNoC, and Snitch by running:

make all

or more selectively:

make floo-hw-all
make chs-hw-all
make sn-hw-all

Compile software tests

To compile the software for Cheshire and the snitch cluster, you can run the following commands:

make sw

or more selectively:

make chs-sw-tests
make sn-tests

Simulation

Gwaihir supports two simulation flows: QuestaSim and Synopsys VCS. Tests can be executed by setting the required command-line variables for Cheshire — see the Cheshire Docs for more details.

Use the PRELMODE=3 flag to enable fast preload of the Snitch binary and speed up simulation.

QuestaSim

To compile the RTL:

make vsim-compile

To run a simple Cheshire helloworld in Gwaihir:

make vsim-run CHS_BINARY=sw/cheshire/tests/helloworld.spm.elf

To run an offloading example test for Snitch:

make vsim-run CHS_BINARY=sw/cheshire/tests/simple_offload.spm.elf SN_BINARY=sw/snitch/tests/build/simple.elf

Use vsim-run-batch to run in batch mode with RTL optimizations to reduce runtime.

Some applications produce a lot of output data that is time-consuming to check in simulation. These applications usually come with a Python verification script that checks results from a memory dump at the end of simulation. For example, to run and verify the GEMM kernel:

make vsim-run-batch-verify VERIFY_PY=$(bender path snitch_cluster)/sw/blas/gemm/scripts/verify.py PRELMODE=3 CHS_BINARY=sw/cheshire/tests/simple_offload.spm.elf SN_BINARY=sw/snitch/apps/blas/gemm/build/gemm.elf

VCS

Gwaihir provides two VCS run modes: batch (no debug overhead, faster) and GUI (full signal visibility for Verdi). Compilation is handled automatically by the run targets.

To run in batch mode:

make vcs-run-batch CHS_BINARY=sw/cheshire/tests/helloworld.spm.elf

To run an offloading example test for Snitch:

make vcs-run-batch CHS_BINARY=sw/cheshire/tests/simple_offload.spm.elf SN_BINARY=sw/snitch/tests/build/simple.elf

To open the simulation in the Verdi GUI (compiled with full debug access):

make vcs-run CHS_BINARY=sw/cheshire/tests/helloworld.spm.elf

Use vcs-clean to remove all VCS build artifacts and force a full recompilation.

Additional help

Additionally, you can run the following command to get a list of all available commands:

make help

🔐 License

Unless specified otherwise in the respective file headers, all code checked into this repository is made available under a permissive license. All hardware sources are licensed under the Solderpad Hardware License 0.51 (see LICENSE), and all software sources are licensed under the Apache License 2.0.