⇡ lowRISC tagged memory tutorial

A guide to setting up the development environment

File structure of the repository

Our tagged memory tutorial builds upon a forked version of the original Rocket chip repository. Its contents are described here and summarised below for convenience:

  • chisel: The Chisel compiler used for compiling the rocket system.
  • rocket: The source code for the Rocket core.
  • uncore: The source code for the memory subsystem.
  • hardfloat: The IEEE 754-2008 compliant floating-point unit.
  • dramsim2: The simulation model for the DRAM memory system.
  • fpga-zynq: FPGA related infrastructure
  • riscv-tools: The cross-compilation and simulation tool chain.

In addition, makefiles for Chisel, Verilog and FPGA simulation can be found in:

  • emulator: Chisel simulation scripts
  • vsim: RTL/VLSI RTL simulation scripts
  • fsim: FPGA simulation scripts

Cross-compilation tools and the Spike simulator are also provided:

  • riscv-gnu-toolchain: The GNU GCC cross-compiler for RISC-V ISA
  • riscv-opcodes: The enumeration of all RISC-V opcodes executable by the Spike simulator.
  • riscv-isa-sim: The RISC-V ISA simulator Spike
  • riscv-fesvr: The front-end server that serves system calls on the host machine
  • riscv-pk: The proxy kernel that serves system calls on the target machine when the executes are compiled against the newlib C library
  • riscv-tests: Tests for the Rocket core
  • lowrisc-tag-tests: Tagged memory tests

Note: load tag and store tag (ltag and stag) are not supported by the Spike simulator. We plan to release an update soon.

Downloading the lowRISC chip repository

We recommend you work with a 64-bit Ubuntu (14.04 LTS) system with GNU GCC 4.8 installed. If necessary, create such a setup using VMware player or VirtualBox.

The lowRISC chip git repository is hosted by the GitHub website. Instead of cloning individual sub-modules, we recommend cloning the entire repository to ensure all the sub-modules you acquire are compatible. Different versions of the sub-modules are not guaranteed to work.

To clone the whole lowRISC chip git repository (around 2.1 GB):

# clone the repository to your home directory:
cd ~/lowRISC/DIR
git clone -b tagged-memory-v0.1 --recursive https://github.com/lowrisc/lowrisc-chip.git
cd lowrisc-chip

Ensure you have all the necessary packages installed before attempting to build the RISC-V tools:

   sudo apt-get install autoconf automake autotools-dev curl \
     libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison \
     flex texinfo gperf libncurses5-dev gcc-multilib u-boot-tools \
     openjdk-7-jre

Environment variables

To setup the necessary environment variables use the setup script found at lowrisc-chip/set_riscv_env.sh:

# source this file
echo "Setting up RISC-V environment..."
# Variables for RISC-V
export TOP=$PWD 
export RISCV=$TOP/riscv
export PATH=$PATH:$RISCV/bin

You can simply source this script. However, if you need to have your own environment settings, you can set $RISCV to any location you prefer.

Xilinx Vivado 2014.4 is needed if you would like to recompile the FPGA images of the Zedboard. A voucher is provided along with the Zedboard which allows you to apply a device locked license from Xilinx running the Vivado tool. To acquire the Xilinx Vivado 2014.4, you need to download it from the Xilinx official website. For the 64-bit Ubuntu 14.04 LTS system, please download “the Vivado 2014.4 Full Image for Linux with SDK” and install the “Vivado Design Edition”.

Running RTL (VLSI/FPGA) simulations requires the Synopsys Verilog Compiler Simulator (VCS). Unfortunately this is a commercial tool which is not freely available. For the users who do not have an access to VCS, it is still possible to use the cycle accurate C++ simulator (emulator) generated by Chisel.

Simulation waveforms can also be generated using the emulator Waveforms of the lowRISC chip can be generated using the emulator in VCD format. GTKWave is a free tool that can be used to view these files.

Building the RISC-V tools

To build the Spike simulator and the version of GCC required to produce code for use with the proxy kernel and newlib, run the following script:

# set up the RISCV environment variables
cd $TOP/riscv-tools
./build.sh

After the compilation, the Spike and GCC binaries should be available:

which spike
which riscv64-unknown-elf-gcc

The RISC-V GCC/Newlib Toolchain Installation Manual can be found here.

Building GCC for RISC-V

riscv-gcc is a compiler based on GNU GCC 4.6.1. This particular compiler version is required to compile the RISC-V Linux kernel and any programs that will be launched from within it.

To build the cross-compiler:

# set up the RISCV environment variables
cd $TOP/riscv-tools
git clone https://github.com/lowrisc/riscv-gcc-tagged-memory-v0.1.git riscv-gcc
cd riscv-gcc
mkdir build
cd build
../configure --prefix=$RISCV
make -j$(nproc) linux

After the compilation, the compiler should be available:

riscv-linux-gcc -v

Building the RISC-V Linux Kernel

Requirements: riscv-gcc must be available

The Linux kernel can be simulated using Spike or booted on an FPGA. To compile your own Linux kernel, using the following script (more instructions can be found here:

# set up the RISCV environment variables
cd $TOP/riscv-tools
curl https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.14.13.tar.xz \
  | tar -xJ
cd linux-3.14.13
git init
git remote add origin https://github.com/riscv/riscv-linux.git
git fetch
# currently we use an old version of riscv-linux
git checkout -f 989153f
make ARCH=riscv defconfig
make ARCH=riscv -j vmlinux

After the compilation, you should be able to find the following files:

./vmlinux

Build the root image (root.bin) for the Linux kernel

Requirements: riscv-gcc must be available

BusyBox is used in the root image to provide the basic shell environment. To build your own root image, the BusyBox binary must be generated at first:

# set up the RISCV environment variables
cd $TOP/riscv-tools
curl -L http://busybox.net/downloads/busybox-1.21.1.tar.bz2 | tar -xj
cd busybox-1.21.1
cp $TOP/riscv-tools/busybox_config .config
make -j$(nproc)

If the compilation finishes successful, the BusyBox binary is generated in the same directory.

ls -l busybox

After the BusyBox binary is ready, the root image (root.bin) can be built using the following script:

$TOP/riscv-tools/make_root.sh

More details can be found here.

  Previous
  Tagged memory tests