Development environment setup

There are multiple ways of working with RISC-V repo:

1. Using WSL (Windows Subsystem for Linux) on Windows
2. Using a Linux distro
3. Using a devcontainer

While its also possible to use Quartus ecosystem on Windows to build the project, it is currently not officially suported.

Prerequisites

WSL

For setup instructions, see WSL Onboarding

Linux

Devcontainer

Installing dependencies

This subsection applies to those using WSL or Linux to interact with the RISC-V repo. Those using devcontainer already have everything setup.

This doc assumes you are using a recent Ubuntu (e.g. 22.04); if you are using another distro you can probably figure out how to modify the instructions accordingly.

1. Update your system

   sudo apt update
   sudo apt upgrade -y

2. Install some essentials

   sudo apt update
   sudo apt install -y \
     man make build-essential git zsh vim curl wget procps gnupg gnupg2 ca-certificates zip \
     software-properties-common autoconf gperf gcc g++ bison flex \
     python3 python3-pip python3-venv libpython3-dev unzip

3. (optional) Set up oh-my-zsh
4. Build Icarus Verilog

   ICARUS_SRC_TAR="v12_0.tar.gz"
   ICARUS_SRC_URL="https://github.com/steveicarus/iverilog/archive/refs/tags/${ICARUS_SRC_TAR}"
   ICARUS_SRC_HASH='a68cb1ef7c017ef090ebedb2bc3e39ef90ecc70a3400afb4aa94303bc3beaa7d  v12_0.tar.gz'
   
   cd /tmp
   wget "${ICARUS_SRC_URL}"
   echo "${ICARUS_SRC_HASH}" | sha256sum -c
   tar -xzf "${ICARUS_SRC_TAR}"
   cd iverilog-*
   sh autoconf.sh
   ./configure
   make -j"$(nproc)"
   make check
   sudo make install
   cd ..
   rm -rf iverilog-* "${ICARUS_SRC_TAR}"
   
   # quick sanity check
   iverilog -V

5. Install Docker for Windows; make sure to check the "Use WSL 2 instead of Hyper-V" checkbox during installation. On Ubuntu, you can install Docker Desktop or get it your package manager.
6. Get yourself a GitHub access token:

   1. On GitHub, go to Settings:

      

   2. Navigate to Developer Settings in the panel on the left:

      

   3. Navigate to Personal access tokens > Tokens (classic):

      

   4. Click Generate new token > Generate new token (classic):

      

   5. Call it whatever you want, set expiry to 7 days and pick write:pacakges scope:

      

   6. Copy the new personal access token:

      
7. Login into GHCR (GitHub Container Registry) via docker using the token you just created:

   export GHCR_TOKEN="<paste token here>"
   echo $GHCR_TOKEN | docker login ghcr.io -u <your github username> --password-stdin

   Make sure you see Login Succeeded
8. Get RISC-V toolchain from our Docker image. Toolchain is a collection of binraires needed to run programs on a specific architecture (in this case RISC-V), these include assemblers, compilers, linkers and debuggers. Since it takes quite a bit of time to build it from source -- we uploaded a docker contianer with the binaries, compiled to run on x86 architecutres. Essentially this means that the toolchain can be used to cross-compile programs for RISC-V on an x86-based computer. Perform the following commands in a shell in WSL.
   1. Set up some variables in shell:

      DOCKER_IMAGE="ghcr.io/utoss/risc-v-toolchain:latest"
      INSTALL_DIR="/opt/riscv"
      TEMP_CONTAINER="riscv-toolchain-temp"

   2. Start the toolchain container so that we can copy the binaries from it:

      sudo docker create --name ${TEMP_CONTAINER} ${DOCKER_IMAGE}

      (by default, docker command will only work with sudo); this will also download the image from GHCR, which you just looged into through Docker client
   3. Copy the toolchain files from the container to WSL:

      docker cp ${TEMP_CONTAINER}:/opt/riscv/. ${INSTALL_DIR}/

   4. Make sure you own them:

      sudo chown -R $(id -u):$(id -g) ${INSTALL_DIR}

   5. Get rid of the temporary docker container:

      docker rm ${TEMP_CONTAINER}

   6. Add RISC-V toolchain to your PATH, i.e. so that you can run the executables without specifying complete path to their location:

      BASHRC_LINE='export PATH="/opt/riscv/bin:$PATH"'
      echo "${BASHRC_LINE}" >> ~/.bashrc
      source ~/.bashrc # this line will make sure the PATH variable is also update for your current shell sesison

   7. Do a quick test by running

      riscv32-unknown-elf-gcc --version

      If this does list the version of the compiler, things are set up correctly.
9. Instal SAIL simulator. This is a reference model for us to test our implementation of RISC-V against.

   SAIL_RISCV_VERSION=0.7
   SAIL_RISCV_ZIP_NAME=sail_riscv-Linux-x86_64.tar.gz
   SAIL_RISCV_ZIP_URL=https://github.com/riscv/sail-riscv/releases/download/${SAIL_RISCV_VERSION}/${SAIL_RISCV_ZIP_NAME}
   SAIL_RISCV_ZIP_HASH="6b8c3abc3126ce14911a3dec46ff540a60841ef090898f72c4c6f9b0b825efab  ${SAIL_RISCV_ZIP_NAME}"
   
   mkdir -p /tmp/sail-riscv
   cd /tmp/sail-riscv
   wget ${SAIL_RISCV_ZIP_URL}
   echo ${SAIL_RISCV_ZIP_HASH} | sha256sum -c
   tar -xzf ${SAIL_RISCV_ZIP_NAME}
   sudo mv sail_riscv-Linux-x86_64/bin/* /usr/local/bin/
   cd ..
   sudo rm -r /tmp/sail-riscv
   cd /usr/local/bin
   sudo mv riscv_sim_rv32d riscv_sim_RV32
   sudo mv riscv_sim_rv64d riscv_sim_RV64

10. Install RISCOF:

    sudo apt update
    sudo apt install -y python3 python3-pip
    pip3 install riscof

Smoke test

Run the following command while in the RISC-V repo and make sure that you don't see any errors:

make run_tb

Follow the instructions in Running RISCOF to make sure RISCOF dependencies are installed correctly.