CORE-V Wally: a configurable RISC-V core built to be read

A core whose purpose is to be taught, not benchmarked

Wally is described in the README as a 5-stage pipelined processor configurable to support up through the RVA22 profile, including virtual memory, PMP and the various privileged modes and CSRs. It is written in SystemVerilog, and the README states that it passes the RISC-V Arch Tests and boots Linux on an FPGA.

The framing matters more than the feature list. The project is associated with a textbook, RISC-V System-on-Chip Design by Harris, Stine, Thompson and Harris, and the README says users should follow the setup instructions. The core is part of the OpenHW Foundation family of open RISC-V cores.

So the audience is a learner and the people who teach them. The design goal is not a fast processor, it is a processor whose every stage can be read, modified and re-verified by someone working through the book alongside it. That is a different objective from a competitive core, and it explains the emphasis on configuration and testing rather than on performance.

The verification status is stated precisely. Wally is presently at Technology Readiness Level 4, passing the RISC-V compatibility test suite and custom tests, and booting Linux in simulation and on an FPGA, with a Test Plan document linked for details.

The last push to the repository was on 2026-10-19 and the repository is not archived, so the tree is current. The single release tag is CVW_v0.9, titled for Arty A7 board support and ImperasDV Linux boot, from 2023-04-27, and the package version in the project metadata is 0.9.0 with Apache-2.0 recorded in the pyproject and a separate LICENSE file at the root.

One core, many configurations, including a minimal RV32E

The configuration system is the heart of the project. The rv64gc configuration supports a long extension list, and the README enumerates it.

On the base and privileged side there is RV64IMAFDCB with M, S and U modes, and the Zicsr, Zifencei, Zicntr, Zihpm, Zicond and Zicclsm extensions, plus Zbc, Zcb, Zfh and Zfa, and Sstc for timer interrupts.

On crypto there is Zkn scalar crypto, listed as Zbkb, Zbkc, Zbkx, Zknd, Zkne and Zknh.

On cache management there is Zicbom, Zicboz and Zicbop, and the vector cryptography work sits alongside the Zkn group.

On virtual memory the configuration supports Sv39, Sv48 and Sv57 with Svpbmt, Svnapot, Svinval and Svadu, and it has 16 PMP entries.

Then the README says other configurations range down to a minimal RV32E core, and derivative configurations add the Q extension. That sentence is the practical guidance: the same source tree produces a small teaching core and a large Linux-capable one, and the choice is a configuration file rather than a fork.

Around the core, Wally provides optional caches, branch prediction, and standard RISC-V peripherals, which it names: CLINT, PLIC, UART and GPIO. A block diagram of the whole design is in the repository as wallyriscvTopAll.png, and the src directory holds the RTL while the config directory holds the per-configuration definitions.

Getting a first simulation running: clone, setup, wsim, spike

The New User Setup section is unusually complete, and it assumes you are going to work through the book rather than just build one thing.

The first step is Git configuration, and the README gives the exact commands with a placeholder name and email, plus a line disabling pull rebase:

  $ git config --global user.name "Ben Bitdiddle"
  $ git config --global user.email "[email protected]"
  $ git config --global pull.rebase false

The README also lists optional steps: downloading and installing x2go, downloading and installing VSCode, and making sure you can log into your server via x2go and via a terminal, with a note to see B.1 about ssh -Y login from a terminal. Those are chapter references, which tells you the setup is a reading path rather than a standalone guide.

Then you fork and clone. You create a GitHub account, visit the repository in a browser, click Fork in the upper right, create the fork with your account as owner and cvw as the repository, log into the Linux machine where you will work, and clone your fork, changing the placeholder to your own id:

  $ git clone --recurse-submodules https://github.com/<yourgithubid>/cvw
  $ cd cvw
  $ git remote add upstream https://github.com/openhwfoundation/cvw

The submodules flag and the upstream remote are the two details that matter, since the design is split across them.

Next you run the setup script, which updates your PATH and activates the Python virtual environment:

  $ source ./setup.sh

And you add lines to your .bashrc or .bash_profile so it runs at every login:

  if [ -f ~/cvw/setup.sh ]; then
    source ~/cvw/setup.sh
  fi

The final check compiles a program and runs it on two simulators, which is the moment you know the toolchain is right:

  $ cd examples/C/hello
  $ make
  $ wsim --sim verilator rv64gc --elf hello
  Hello Wally!
  0 1 2 3 4 5 6 7 8 9
  $ spike hello
  Hello Wally!
  0 1 2 3 4 5 6 7 8 9

Two simulators, the same output. wsim is the wrapper that drives Verilator for the rv64gc configuration, and spike is the RISC-V ISA simulator, and seeing identical results from a cycle-accurate-ish Verilog simulation and a functional reference is the signal that your setup is sound.

The toolchain is the real prerequisite, and it wants about 55 GB

The toolchain installation section is where a newcomer discovers what this project really costs in disk and time.

The script installs a long list of tools: the RISC-V GNU Toolchain for GCC and the compiler tools, QEMU as the emulator, Spike as the functional RISC-V model, Whisper as the RISC-V instruction set simulator, Verilator as the open-source Verilog simulator, the RISC-V Sail Model as the golden reference, the OSU Skywater 130 cell library as the standard cell library, uv as the Python package and virtual environment manager, and mise for managing tool versions and environment variables.

Additionally, Buildroot Linux is built for Wally and Linux test-vectors are generated for simulation, with a note that this can be skipped with the --no-buildroot flag.

The installation itself is one script:

$ $WALLY/bin/wally-tool-chain-install.sh

Run as root or with sudo it also installs the prerequisite packages using the system package manager, and the default installation directory in that case is /opt/riscv. For a user-level install the script runs without sudo, the directory becomes ~/riscv, and the prerequisites are installed first with a separate command:

$ sudo $WALLY/bin/wally-package-install.sh

The directory can be overridden by passing it as an argument:

$ sudo $WALLY/bin/wally-tool-chain-install.sh /home/riscv

And the number to plan for is in a note at the end of the section: the complete installation process requires about 55 GB of free space, and there is a --clean flag to reduce what the finished installation consumes.

That figure is the honest cost of the project. Nine tools, two simulators, a golden reference model, a standard cell library, a buildroot Linux and a Python environment, all before you compile a single test.

Compatibility is tested on a wide set of distributions, including Ubuntu at versions 20.04, 22.04, 24.04 and 26.04 LTS, Debian 12 and 13, Red Hat, Rocky and AlmaLinux at 8, 9 and 10, SUSE 15.6 and 16.0, and Fedora 44, with only the latest minor release of each major version tested. Two warnings are given: Ubuntu 22.04 LTS is incompatible with Synopsys Design Compiler, and Whisper is not installed on Ubuntu 20.04 LTS because of issues compiling the boost libraries.

Regression as the proof, and the Makefile that runs it

The verification story is the reason to trust a teaching core, and the README gives you the command.

After the setup, you build the tests from the cvw directory and run a regression simulation, with a warning that building the tests may take a while:

  $ cd ~/cvw && make --jobs
  $ regression-wally

The Makefile at the repository root shows how much is behind that one command. The default target all runs act, periph, testfloat, zsbl, coverage, sim_bp and deriv, with a note that act builds the riscv-arch-test suite for every cvw configuration that has an ACT test-generation configuration, and that the ELFs are built in work subdirectories named after the configuration.

The periph target builds the self-checking peripheral tests, testfloat builds the floating-point vectors, zsbl builds the FPGA boot loader, and coverage has two variants, tests/coverage and tests/coverage32, for the 64-bit and 32-bit cores. There is also a deriv target that runs a Perl script to generate the derivative configurations, and a sim_bp target that builds a branch-predictor simulator in addins.

Two comments in the Makefile are worth reading as design notes rather than trivia. The first explains that ACT's incremental build never deletes ELFs, so ELFs of tests a changed configuration no longer supports would be left behind and still run, and the fix discards the ELFs when a configuration's files change so that ACT rebuilds exactly the current set. The second notes that the wheels the project would produce are broken on Windows because they install an incompatible entrypoint script, which is why the wheel build is commented out and the release path uses a source distribution instead.

The repository also has dedicated directories for the parts of the flow beyond simulation: fpga for the FPGA targets, synthDC for the synthesis flow, studies for design studies, benchmarks for performance work, and linux for the Linux bring-up, with a separate Linux README linked from the toolchain section.

Where Wally is the wrong tool

The first wrong-tool case is a product that needs performance. Wally is a 5-stage in-order pipeline with optional caches and branch prediction, and its stated purpose is education. There is a benchmarks directory in the repository, but the README says nothing about competitive results, and the design tradeoffs that make a core readable are the same ones that make it slow. If your requirement is throughput, this is the wrong core.

The second is a team that needs a current profile. The rv64gc configuration targets RVA22, which is a specific point in the RISC-V specification, and the extension list, while long, is fixed at a moment in time. A product needing a later ratified extension is looking at work rather than configuration.

The third is a team that cannot absorb the setup. Roughly 55 GB of tools, a Python environment, a standard cell library for synthesis, a buildroot Linux, and a per-configuration regression suite are a lot of infrastructure for what is conceptually a teaching example. The README's own structure, with x2go, VSCode, an ssh -Y login and chapter cross references, assumes a reader working through a course over weeks.

The fourth is a hardware team that needs production silicon. Technology Readiness Level 4 with a passing architecture test suite and a Linux boot is a solid research milestone, but it is not a sign-off for a tapeout, and the repository is a research artefact rather than a productised core.

The alternative to weigh is an existing open core, where the trade is between a core you can read end to end and a core with a performance profile, a verification record and a support community behind it. Wally's own README points at the RISC-V Arch Tests as its conformance reference, so choosing a different core means adopting a different conformance argument, and the decision is really about whether the education value, the ability to modify the pipeline, and the fact that Linux boots are worth the setup cost and the absence of a performance guarantee.

Editorial conclusion

Wally fits a student or engineer who wants to understand how a RISC-V core actually works by reading one, or a team that needs a small, modifiable core with a documented test plan and Linux boot as an end-to-end check. It is the wrong choice for a product that needs a high-performance core, for a team that cannot afford the roughly 55 GB toolchain install and the FPGA flow, and for anyone who needs a current RISC-V profile beyond the one Wally targets. Before starting, read the Test Plan document, decide whether you need the full extension set or the minimal RV32E core, and plan for the toolchain install rather than the clone alone, since the simulator and RISC-V toolchain are the actual prerequisites.

Frequently asked questions

Official sources

1. Issues
2. openhwfoundation/cvw on GitHub
3. README
4. Releases