Skip to content

Latest commit

 

History

History
331 lines (277 loc) · 12.8 KB

vcode-rocc-chipyard-setup.org

File metadata and controls

331 lines (277 loc) · 12.8 KB

VCODE RoCC Accelerator & Chipyard Setup

Dependencies

If you are on a system where Nix is available, all of these dependencies are provided for you in flake.nix. You must still build the toolchain and Chipyard manually, but you will not need to install any of the third-party dependencies.

Verilator

Verilator is needed by Chipyard to compile software simulations.

Verilator must end up in $PATH for Chipyard to use it. So, if you do not have superuser permissions, or only want a user-local install, use the --prefix flag in the Configure step.

Dependencies

  1. GCC
  2. flex
  3. bison
  4. Make
  5. autoconf

On Ubuntu:

$ sudo apt-get install -y build-essential flex bison autoconf

Verilator Repository

$ git clone http://git.veripool.org/git/verilator
$ cd verilator

Configure

The Chipyard documentation says you should use v4.034 of Verilator. However, I have encountered issues with it, like a missing verilator.h header. This newer version appears to be compatible, but it does throw extra warnings about the inference of certain edge-triggered flip-flops.

$ git checkout v5.010
$ autoconf
$ ./configure --prefix=<binary-install-directory>
# My preference is --prefix="$HOME/verilator-v5.010-install"

Build

Building verilator is fairly fast. You can parallelize the compilation by using -j$(nproc). However, I have encountered strange compilation issues on very parallel compilations.

$ make -j$(nproc)

# You can skip testing the binaries if you want.
$ make test # You can parallelize this with -j as well

Install

If you used the --prefix flag in the Configure step, then you probably will not need sudo permissions.

$ make install # If you install to a root-owned directory, you will need sudo

Make Available

Chipyard requires that the binaries created by verilator be in $PATH. I prefer to just export the directory in my .bashrc. I usually prepend my verilator install to the front of $PATH to ensure I use my install first.

export PATH="$HOME/verilator-v5.010-install/bin":"$PATH"

You can check that you are using the right Verilator with the commands below:

$ which verilator # Should return the path to your install of verilator
$ verilator --version # Should return the version & build date

RISC-V GNU Toolchain

As of 2024-07-29, Constellation’s fork of Chipyard is up-to-date with UC-Berkeley’s version. This means that conda is the preferred “out-of-the-box” environment. However, you are not required to use conda.

If you do not want to use conda, then you must clone the toolchain and build it yourself. You can then skip Chipyard’s step where conda is used to download the toolchain.

The toolchain is a large install, approaching 10 GB.

Dependencies

sudo apt install build-essential autoconf automake autotools-dev \
                 curl python3 python3-pip \
                 libmpc-dev libmpfr-dev libgmp-dev \
                 gawk bison flex \
                 texinfo gperf \
                 libtool patchutils \
                 bc zlib1g-dev libexpat-dev ninja-build \
                 git cmake libglib2.0-dev libslirp-dev \
                 python3-pyelftools # Only needed for testing

Environment Variables

You must set the RISCV environment variable to the install path of the toolchain.

$ export RISCV="$(realpath path/to/desired/toolchain/install/location)"

The toolchain expects that --prefix be an absolute path, which is the reason I used realpath. realpath produces an absolute path from a relative path, and is a no-op on an absolute path.

Clone

$ git clone https://github.com/riscv-collab/riscv-gnu-toolchain.git
$ cd riscv-gnu-toolchain

Note that as of 2024-08-05, you will need to use tag 2024.08.03 for Chipyard to finish building its toolchain collateral (ISA simulator in particular). This is because GNU Binutils 2.43 dropped support for RISC-V Privileged Instruction Set v1.9 in GAS, while Chipyard collateral still uses CSRs defined in that standard.

$ git checkout 2024.08.03 --

This should be fixed in the near future, but I am documenting this now because it took a long time to track down.

Configure

$ ./configure --prefix="$RISCV" --with-arch=rv64gcv_zicsr --with-abi=lp64d --with-cmodel=medany
# If you want LLVM/Clang support
$ ./configure --prefix="$RISCV" --enable-llvm --disable-linux --with-arch=rv64gc --with-abi=lp64d

Build

Building will take quite some time. I recommend that you parallelize the compilation by exporting MAKEFLAGS.

$ export MAKEFLAGS='-j8' # Increase the number for more parallelism.

$ make clean && make && make clean && make linux

After building, if you run the following command, you should see the follwoing output:

$ riscv64-unknown-elf-gcc --print-multi-lib
.;

Chipyard

Chipyard is a very large install, approaching 30+ GB. Make sure you have enough space. All of the instructions below can also be found on Chipyard’s Setup Documentation.

Dependencies

There are lots of dependencies. Look at the Quick Setup scripts for what you will need.

Make sure you build the [[*\[\[https://github.com/riscv-collab/riscv-gnu-toolchain\]\[RISC-V GNU Toolchain\]\]][toolchain]] first!

NOTE: You should use openjdk 17! openJDK 18 has some known issues with Scala & SBT.

Repository

$ git clone https://github.com/Constellation-FPGA/chipyard.git
$ cd chipyard
$ git checkout vcode-rocc

Set Environment Variables

This can be turned into a script you source too.

$ export RISCV="$(realpath path/to/toolchain/install/location)"
$ export PATH="$RISCV/bin":$PATH

Setup

LLVM & CIRCT will be compiled for your work, and will be installed in $RISCV.

$ ./build-setup.sh --skip-conda --skip-precompile --build-circt --skip-firesim --skip-marshal

vcode-rocc

You only need to clone this repository if you are doing active development on the accelerator. If you just want to use the accelerator in a design, without developing it, then you just need to clone Chipyard and run its submodule-initialization step.

Repository

$ git clone https://github.com/Constellation-FPGA/vcode-rocc.git
$ cd vcode-rocc

Quick Setup

Ubuntu Script

This is taken directly from Chipyard’s Documentation. The script should work on any Ubuntu newer than 16.04 LTS.

#!/usr/bin/env bash

set -ex

sudo apt-get install -y build-essential bison flex software-properties-common curl
# Make sure default-jdk & default-jre are openjdk 17!
sudo apt-get install -y libgmp-dev libmpfr-dev libmpc-dev zlib1g-dev vim default-jdk default-jre
# install sbt: https://www.scala-sbt.org/release/docs/Installing-sbt-on-Linux.html#Ubuntu+and+other+Debian-based+distributions
echo "deb https://repo.scala-sbt.org/scalasbt/debian /" | sudo tee -a /etc/apt/sources.list.d/sbt.list
curl -sL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x2EE0EA64E40A89B84B2DF73499E82A75642AC823" | sudo apt-key add
sudo apt-get update
sudo apt-get install -y sbt
sudo apt-get install -y texinfo gengetopt
sudo apt-get install -y libexpat1-dev libusb-dev libncurses5-dev cmake
# deps for poky
sudo apt-get install -y python3.8 patch diffstat texi2html texinfo subversion chrpath wget
# deps for qemu
sudo apt-get install -y libgtk-3-dev gettext
# deps for firemarshal
sudo apt-get install -y python3-pip python3.8-dev rsync libguestfs-tools expat ctags
# install DTC
sudo apt-get install -y device-tree-compiler
sudo apt-get install -y python
# install git >= 2.17. Can skip if git already >= 2.17.
sudo add-apt-repository ppa:git-core/ppa -y
sudo apt-get update
sudo apt-get install git -y

# install verilator
git clone http://git.veripool.org/git/verilator
cd verilator
git checkout v4.224
autoconf && ./configure --prefix="$HOME/verilator-v4.224-install" && make -j$(nproc) && make install
echo "export PATH=$HOME/verilator-v4.224-install/bin:$PATH" >> "$HOME/.bashrc"

CentOS Script

This is taken directly from Chipyard’s Documentation.

#!/usr/bin/env bash

set -ex

sudo yum groupinstall -y "Development tools"
# Make sure java & java-devel are openjdk 17!
sudo yum install -y gmp-devel mpfr-devel libmpc-devel zlib-devel vim git java java-devel

# Install SBT https://www.scala-sbt.org/release/docs/Installing-sbt-on-Linux.html#Red+Hat+Enterprise+Linux+and+other+RPM-based+distributions
# sudo rm -f /etc/yum.repos.d/bintray-rpm.repo
# Use rm above if sbt installed from bintray before.
curl -L https://www.scala-sbt.org/sbt-rpm.repo > sbt-rpm.repo
sudo mv sbt-rpm.repo /etc/yum.repos.d/

sudo yum install -y sbt texinfo gengetopt
sudo yum install -y expat-devel libusb1-devel ncurses-devel cmake "perl(ExtUtils::MakeMaker)"
# deps for poky
sudo yum install -y python38 patch diffstat texi2html texinfo subversion chrpath git wget
# deps for qemu
sudo yum install -y gtk3-devel
# deps for firemarshal
sudo yum install -y python38-pip python38-devel rsync libguestfs-tools makeinfo expat ctags
# Install GNU make 4.x (needed to cross-compile glibc 2.28+)
sudo yum install -y centos-release-scl
sudo yum install -y devtoolset-8-make
# install DTC
sudo yum install -y dtc
sudo yum install -y python

# install verilator
git clone http://git.veripool.org/git/verilator
cd verilator
git checkout v4.224
autoconf && ./configure --prefix="$HOME/verilator-v4.224-install" && make -j$(nproc) && make install
echo "export PATH=$HOME/verilator-v4.224-install/bin:$PATH" >> "$HOME/.bashrc"

Usage

The commands from here on out expect you to have a working [[*\[\[https://github.com/riscv-collab/riscv-gnu-toolchain\]\[RISC-V GNU Toolchain\]\]][RISC-V toolchain]]. Make sure you:

$ source chipyard/env.sh

NOTE: You MUST have $RISCV set to the install path of the toolchain before executing any of these commands!

Building an SoC Design

Normally, I start by running software simulations using verilator, before moving on.

$ cd sims/verilator
# To build the vcode-rocc design, you must pass a CONFIG option
$ make CONFIG=VCodeRocketPrintfConfig # PrintfConfig will add printfs to synthesized design.

Active development of vcode-rocc Accelerator

For active development, it is a hassle to use git submodules like Chipyard does. What I prefer to do instead is to replace the submodule with a symlink to a separate clone of vcode-rocc.

$ cd generators
$ rm -rf vcode-rocc
$ ln -s <path-to-separate-vcode-rocc-clone>

The build system will not know the difference, and everything should work just as normal.

Building the Testing Binaries

Building the binaries requires a full RISC-V toolchain. The Chipyard one works perfectly fine (Build RISC-V Toolchain). Once the toolchain is built, source the env.sh file to set the $RISCV environment variable.

$ source chipyard/env.sh
$ cd vcode-rocc/test
$ make

Adding additional Program Tests

To add another program to test on the vcode-rocc Rocket design, you write a new C source file, add the new file to modules.mk, then build them. There are several examples of how to write a test in the test/src directory.

$ source chipyard/env.sh
$ cd vcode-rocc/test
$ pushd src
$ vim <test-name>.c # Write your test here.
# You could also copy an already-written test and replace what you need there.
$ vim modules.mk # Add the file name of your test to the list
$ popd
$ make

The build system should generate both a raw binary, test.riscv, and an ELF file, test, that could be run in an emulator like QEMU.

Running Binaries on the Simulated vcode-rocc Design

To run the binaries, you need to provide the path to the binary as the BINARY flag to make and then run the run-binary target.

$ cd chipyard/sims/verilator
$ make CONFIG=VCodeRocketPrintfConfig BINARY=vcode-rocc/tests/bin/<test>.riscv run-binary