How to run Shakti C-Class on Verilator with GDB?

Verilator is a free, open-source software tool which converts Verilog (a hardware description language) to a cycle-accurate behavioral model in C++ or SystemC. It is widely used in academic and open-source projects. In this article, we are going to discuss the steps to run SHAKTI C Class on Verilator.

Requirements,

Bluespec Compiler
Verilator
Shakti tools and Shakti SDK.
Python & pip
Device tree compiler (DTC)

Step 1: Installation of Bluespec Compiler

1.1 Prerequisites

Open a new terminal and move to the “Home” folder. Run the following commands in the terminal, one by one.

sudo apt install ghc libghc-regex-compat-dev libghc-syb-dev iverilog
sudo apt install libghc-old-time-dev libfontconfig1-dev libx11-dev
sudo apt install libghc-split-dev libxft-dev flex bison libxft-dev
sudo apt install tcl-dev tk-dev libfontconfig1-dev libx11-dev gperf
sudo apt install itcl3-dev itk3-dev autoconf git

1.2 Download the repository

git clone --recursive https://github.com/B-Lang-org/bsc
cd bsc

Within the bsc folder,

make all
make check

After you have done the above steps, add the path you have installed the bsc compiler to your $PATH variable to .bashrc in home folder,

export PATH=$PATH:/path/to/bsc/bin

For instance,

export PATH=$PATH:/home/username/bsc/bin

1.3 Verification

Check if the bsc is added to the PATH correctly. Open a new terminal and print the path. You can see the PATH to bsc folder is listed.

echo $PATH
/home/akshaya/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/akshaya/bluespec/bin

Check if the bluespec compiler bsc is successfully installed, Type the following command and it will list the help commands to get you started.

bsc -help

Step 2: Installation of Verilator

2.1 Installation of verilator

Open a terminal, go to the “Home” folder. Run the following commands in the terminal, one by one.

sudo apt-get install verilator #Using a distribution’s package manager

2.2 Git Quick Install

Note: Packages are unlikely to have the most recent version, so Git Quick Install, might be a better alternative.

Prerequisites,

sudo apt-get install git make autoconf g++ flex bison
sudo apt-get install libfl2 # Ubuntu only #ignore if gives error
sudo apt-get install libfl-dev # Ubuntu only #ignore if gives error

Clone the verilator repository,

git clone https://github.com/verilator/verilator # Only first time

Every time you need to build, execute the following steps.

unset VERILATOR_ROOT
cd verilator
git checkout master
git pull
autoconf
./configure
make -j
sudo su
make test
make install
cd examples/make_hello_c
make

Step 3: Installing shakti-tools and shakti-sdk

The shakti-tools folder has “ready to use” RISC-V tools. It has a RISC-V GNU toolchain, RISC-V instruction set simulator, OpenOCD (debugger) and RISC-V spike simulator. These tools can be downloaded, along with the SHAKTI-SDK.

Open a terminal, go to the “Home” folder. Run the following commands in the terminal, one by one to clone both shakti-sdk and shakti-tools.

git clone https://gitlab.com/shaktiproject/software/shakti-sdk.git
git clone --recursive https://gitlab.com/shaktiproject/software/shakti-tools.git

Add the following export commands to .bashrc, save and close the file.

SHAKTITOOLS=/path/to/shakti-tools # Add the PATH from your system eg: /home/user/bsc
export PATH=$PATH:$SHAKTITOOLS/bin

export PATH=$PATH:$SHAKTITOOLS/riscv64/bin
export PATH=$PATH:$SHAKTITOOLS/riscv64/riscv64-unknown-elf/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SHAKTITOOLS/riscv64/lib

export PATH=$PATH:$SHAKTITOOLS/riscv32/bin
export PATH=$PATH:$SHAKTITOOLS/riscv32/riscv32-unknown-elf/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SHAKTITOOLS/riscv32/lib

To check if and where ‘shakti-tools‘ is installed, in a new terminal type the following command. You should get an output similar to the following.

which riscv64-unknown-elf-gcc
/home/user/shakti-tools/riscv64/bin/riscv64-unknown-elf-gcc

Step 4: Installing Python and pip

The core generator requires pip and python (>=3.7) to be available on your system. Goto the “Home” folder on your terminal,

Follow this link to install python 3.7 on your system. To install pip, use the following command.

pip3 install --upgrade pip

Check your python version and pip version,

python3 --version
pip3 --version

If you have issues installing, either of these, directly on your system we suggest using a virtual environment like pyenv to make things easy.

Firstly, install the required libraries or dependencies,

sudo apt-get install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python-openssl git

Next, install pyenv

curl -L https://raw.githubusercontent.com/yyuu/pyenv-installer/master/bin/pyenv-installer | bash

Then add the following to your .bashrc with appropriate changes to username

export PATH="/home/<username>/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Open a new terminal and create a new python virtual environment:

pyenv install 3.7.0
pyenv virtualenv 3.7.0 myenv

In case pyenv is not found, the system will prompt you to install. Please proceed to install it.

sudo apt install python3-venv

Now you can activate this environment in any other terminal using the following command.

pyenv activate myenv

Also, check pip version. Upgrade if necessary.

python --version
pip install --upgrade pip

Step 5: Install DTC

Open a terminal, go to the “Home” folder. Run the following commands in the terminal, one by one

sudo wget https://git.kernel.org/pub/scm/utils/dtc/dtc.git/snapshot/dtc-1.4.7.tar.gz
sudo tar -xvzf dtc-1.4.7.tar.gz
cd dtc-1.4.7/
sudo make NO_PYTHON=1 PREFIX=/usr/
sudo make install NO_PYTHON=1 PREFIX=/usr/

Step 6: Building the Core and running it on the Verilator

Open a terminal, go to the “Home” folder. Run the following commands in the terminal, one by one.

git clone https://gitlab.com/shaktiproject/cores/c-class.git
cd c-class/
pyenv activate myenv    # In case the python environment is used
pip install -U -r requirements.txt
python -m configure.main -ispec sample_config/default.yaml

Build core and connect GDB in simulation

Enable GDB for use in simulation. Modify default.yaml within sample_config folder (/c-class/sample_config/default.yaml) to enable debugger_support and open_ocd.

debugger_support: true
open_ocd: True

Modify verilator_config.vlt file to run make gdb command smoothly,

Move to folder /c-class/devices/jtagdtm/
In file verilator_config.vlt, in all columns modify
- lint_off -msg to lint_off -rule

Now, build Core and enable GDB,

python -m configure.main -ispec sample_config/default.yaml
make gdb

If you encounter the following error when executing out within /c-class/bin

%Error: boot.LSB:8192: $readmem file address beyond bounds of array
Aborting...
Aborted (core dumped)

Follow the steps below to enable ./out to function

Open boot.LSB, find the number of columns occupied
1. Example: if the number = 8200
Subtract the number shown in the error from the number of columns in the file
1. Num = 8200 – 8192 = 8
Do the following to remove the extra lines
1. head -n -8 boot.LSB > temp.LSB where 8 = Num
Move temp.LSB contents to boot.LSB
1. mv temp.LSB boot.LSB

Note: Follow the same steps if error occurs with boot.MSB

Now Connect to GDB,

Open a new terminal to simulate the RTL, do the following:

 cd c-class/bin/
./out > /dev/null

Output:

Open another terminal, connect to OpenOCD

cd c-class/test_soc/gdb_setup
openocd -f shakti_ocd.cfg

Open another terminal, connect to GDB

cd c-class/test_soc/gdb_setup
riscv64-unknown-elf-gdb -x gdb.script

(gdb) file example.elf
(gdb) load
(gdb) si
(gdb) i r

Step 7: Running simple RISC-V Assembly and C programs on GDB

Assembly Program: Adding an immediate value to a value stored in a register and storing the result in another register. Save the program as name_of_program.S

mv x5, 0    #Clear register x5
mv x6, 0    #Clear register x6
li x5, 1      # x5 ←1
addi x6, x5, 5    #x6 ← x5 + 5

Now proceed to compile the program.You can follow the steps given in “Compile and Build” of ASM program.

Then follow the steps given in “Connect to GDB” section in this file to load the program.

Note: Move the compiled binary within spiking folder to either /c-class/test_soc/gdb_setup (OR) provide file path in (gdb) before loading the file.

C Program

Open terminal, GoTo /path/to/c-class/benchmarks
Run to compile Hello World program:
- make hello
Compiled binaries generated files will be available in `output` folder
Follow the steps given in “Connect to GDB” section in this file to load the program

Move the compiled binary within spiking folder to either /c-class/test_soc/gdb_setup (OR) provide file path in (gdb) before loading the file

In (gdb) terminal type

(gdb) c #To continue through the program

Output “Hello World!” will be printed in app_log file within “bin” folder of c-class folder

References for Frequently Faced Issues

Please refer to the following websites if you face any issues while installing the verilator,

https://shakti.org.in/learn_with_shakti/FAQ.html
https://shakti.org.in/sp2020-shakti.html
- Refer to FAQ section

Akshaya B

Akshaya currently works at the RISE labs. Her favorite subjects are Web designing and Microprocessors. She loves learning about new things and writing about them!