core-v-wally

Wally is a 5-stage pipelined processor configurable to support all the standard RISC-V options, including RV32/64, A, B, C, D, F, M, Q, and Zk* extensions, virtual memory, PMP, and the various privileged modes and CSRs. It provides optional caches, branch prediction, and standard RISC-V peripherals (CLINT, PLIC, UART, GPIO). Wally is written in SystemVerilog. It passes the RISC-V Arch Tests and boots Linux on an FPGA. Configurations range from a minimal RV32E core to a fully featured RV64GC application processor with all of the RVA22S64 profile extensions. Wally is part of the OpenHWGroup family of robust open RISC-V cores.

Wally is described in an upcoming textbook, RISC-V System-on-Chip Design, by Harris, Stine, Thompson, and Harris. Users should follow the setup instructions below. A system administrator must install CAD tools using the directions further down.

Verification

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. See the Test Plan for details.

New User Setup

New users may wish to do the following setup to access the server via a GUI and use a text editor.

• Git started with Git configuration and authentication: C.1 (replace with your name and email)

  $ git config --global user.name "Ben Bitdiddle"
  $ git config --global user.email "ben_bitdiddle@wally.edu"
  $ git config --global pull.rebase false
  

• Optional: Download and install x2go - B.1.1
• Optional: Download and install VSCode - B.4.2
• Optional: Make sure you can log into your server via x2go and via a terminal
  • Terminal on Mac, cmd on Windows, xterm on Linux
  • See B.1 about ssh -Y login from a terminal

Then fork and clone the repo, source setup, make the tests and run regression

1. If you don't already have a Github account, create one
2. In a web browser, visit https://github.com/openhwgroup/cvw
3. In the upper right part of the screen, click on Fork
4. Create a fork, choosing the owner as your github account and the repository as cvw.
5. On the Linux computer where you will be working, log in.
6. Clone your fork of the repo. Change <yourgithubid> to your github id.

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

[!NOTE] If you are installing on a new system without any tools installed, please jump to the next section, Toolchain Installation, then come back here.

7. Run the setup script to update your PATH and activate the python virtual environment.

$ source ./setup.sh

8. Add the following lines to your .bashrc or .bash_profile to run the setup script each time you log in.

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

9. Try compiling the HelloWally program and simulating it on the SystemVerilog with Verilator and on the Spike simulator.

$ 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

10. Build the tests from the cvw directory and run a regression simulation to prove everything is installed. Building tests may take a while.

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

Toolchain Installation and Configuration (Sys Admin)

This section describes the open source toolchain installation.

Compatibility

The current version of the toolchain has been tested on Ubuntu (versions 20.04 LTS, 22.04 LTS, and 24.04 LTS), Debian (versions 11, 12, and 13), Red Hat/Rocky/AlmaLinux (versions 8, 9, and 10), and SUSE version 15.6. Only the latest minor release of each major version is tested.

[!WARNING]

• Ubuntu 22.04LTS is incompatible with Synopsys Design Compiler.
• Verilator currently fails to simulate correctly on Ubuntu 20.04 LTS and Red Hat/Rocky/AlmaLinux 8.
• Whisper is not installed on Ubuntu 20.04 LTS or Debian 11 due to issues compiling the boost libraries.

Overview

The toolchain installation script installs the following tools:

• RISC-V GNU Toolchain: GCC and accompanying compiler tools
• elf2hex: executable file to hexadecimal converter
• QEMU: emulator
• Spike: functional RISC-V model
• Whisper: RISC-V instruction set simulator (ISS)
• Verilator: open-source Verilog simulator
• RISC-V Sail Model: golden reference model for RISC-V
• OSU Skywater 130 cell library: standard cell library
• uv: Python package manager and virtual environment tool
• mise: development environment setup tool for managing tool versions and environment variables
• RISCOF: RISC-V compliance test framework

Additionally, Buildroot Linux is built for Wally and linux test-vectors are generated for simulation. See the Linux README for more details. This can be skipped using the --no-buildroot flag.

Installation

The tools can be installed by running

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

If this script is run as root or using sudo, it will also install all of the prerequisite packages using the system package manager. The default installation directory when run in this manner is /opt/riscv.

If a user-level installation is desired, the script can instead be run by any user without sudo and the installation directory will be ~/riscv. In this case, the prerequisite packages must first be installed by running

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

In either case, the installation directory can be overridden by passing the desired directory as an argument to the installation script. For example,

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

See wally-tool-chain-install.sh and the scripts in the $WALLY/bin/installation directory for a detailed description of each component, or to issue the commands one at a time to install on the command line.

[!NOTE] The complete installation process requires ~55 GB of free space. If the --clean flag is passed to the installation script then the final consumed space is only ~26 GB. The --clean flag removes source files and build directories.

Configuration

$WALLY/setup.sh sources $RISCV/site-setup.sh. If the toolchain was installed in either of the default locations (/opt/riscv or ~/riscv), $RISCV will automatically be set to the correct path when setup.sh is run. If a custom installation directory was used, then $WALLY/setup.sh must be modified to set the correct path.

$RISCV/site-setup.sh allows for customization of the site specific information such as commercial licenses and PATH variables. It is automatically copied into your $RISCV folder when the installation script is run.

Change the following lines to point to the path and license server for your Siemens Questa and Synopsys Design Compiler and VCS installations and license servers. If you only have Questa or VCS, you can still simulate but cannot run logic synthesis. If Questa, VSC, or Design Compiler are already setup on this system then don't set these variables.

export MGLS_LICENSE_FILE=..         # Change this to your Siemens license server
export SNPSLMD_LICENSE_FILE=..      # Change this to your Synopsys license server
export QUESTA_HOME=..               # Change this for your path to Questa
export DC_HOME=..                   # Change this for your path to Synopsys Design Compiler
export VCS_HOME=..                  # Change this for your path to Synopsys VCS

Installing EDA Tools

Electronic Design Automation (EDA) tools are vital to implementations of System on Chip architectures as well as validating different designs. Open-source and commercial tools exist for multiple strategies and although the one can spend a lifetime using combinations of different tools, only a small subset of tools is utilized for this text. The tools are chosen because of their ease in access as well as their repeatability for accomplishing many of the tasks utilized to design Wally. It is anticipated that additional tools may be documented later after this is text is published to improve use and access.

Verilator is an open-source Verilog simulator. It is fast and free. Run Wally on the riscv-arch-test suite using Verilator with:

regression-wally

Running code or functional coverage simulations or lock-step presently require commercial tools. Siemens Questa is the primary tool utilized for simulating and validating Wally. Synopsys VCS also can run regression-wally and lock-step simulation. For logic synthesis, you will need Synopsys Design Compiler. Questa and Design Compiler are commercial tools that require an educational or commercial license.

Note: Some EDA tools utilize LM_LICENSE_FILE for their environmental variable to point to their license server. Some operating systems may also utilize MGLS_LICENSE_FILE instead, therefore, it is important to read the user manual on the preferred environmental variable required to point to a user’s license f