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

  • Post author:
  • Reading time:16 mins read
  • Post category:Tutorials
You are currently viewing 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.


  • 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
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
  • 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.


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 # Only first time

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

cd verilator
git checkout master
git pull
make -j
sudo su
make test
make install
cd examples/make_hello_c

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
git clone --recursive

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/riscv64/bin
export PATH=$PATH:$SHAKTITOOLS/riscv64/riscv64-unknown-elf/bin

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

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

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 | 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
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
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
Aborted (core dumped)

Follow the steps below to enable ./out to function

  1. Open boot.LSB, find the number of columns occupied
    1. Example: if the number = 8200 
  2. Subtract the number shown in the error from the number of columns in the file
    1. Num = 8200 – 8192 = 8
  3. Do the following to remove the extra lines
    1. head -n -8 boot.LSB > temp.LSB where 8 = Num
  4. 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


  • 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,