This project has the full solution for the course exercises. It is able to simulate the Decoder or CPU as DUTs (device under tests). The simulation executes a SW test from a designated Hex file on the DUT.

In this README you will learn about ...

what prerequisites you need to get this project running
how the project is organised
how to run simulations

Background

This course is a part of the initiative Bavarian Chip Design Center (BCDC), which aims to develop and improve the IC-Design workforce in Bavaria.

This course is an adaptation of the code-base developed at Lund University by Per Andersson as part of the effort to develop and improve education in Digital System Design. You can find the original source-code under this repository.

Prerequisites

Bash Shell Terminal

Windows: you need to install gitbash or use something similar
MacOS/Linux: bash is preinstalled

GCC Compiler

Installation details here

Verilator

If not installed, you can find the installation here. It is highly recommended to install through a package manager for all operating systems.
- For Linux use apt package manager. Info under verilator install guide.
- For MacOS the package manager is homebrew.
- For Windows an package manager option is pacman (untested).
Export the VERILATOR environment variable. Make sure to use your Verilator install directory -> export VERILATOR=</path/to/verilator>/bin/verilator

Surfer Waveform Viewer

If not installed, you can find the installation here
Export the WAVE_VIEWER environment variables. Make sure to use your Surfer install directory -> export WAVE_VIEWER=</path/to/surfer>/surfer

IDE (optional)

Any IDE of your choosing will make it easy to view and manage the files

Project Organisation

Resources

Path: doc

Module diagrams
RISC-V Cards
RISC-V ISM
RISC-V ASM

RTL source code

Path: hw/rtl

File lists of SV code

Path: hw/file_lists

RTL file list
Testbench file list

Verification source code

SV testbenches used in EDA playground

Path: hw/dv/rtl

Verilator environment

Path: hw/dv/verilator/

SV Toplevel harnesses
- Decoder
- CPU
C++ testbenches
- Decoder
- CPU
Makefile

Software and Hex programs used for testing

Path: sw/risc-v

Main Memory: Hex code
Decoder:
- Assembly code
- Hex code from assembeled assembly code
Fibonacci Series/Hello World/Prime Factors:
- C Code
- Assembly code from compiled C code
- Simplified assembly code from assembly code (not available for Fibonacci Series)
- Hex code from assembeled assembly or simplified assembly code

Running Simulations

Quick start

Run the two commands below

cd hw/dv/verilator

make clean all run wave

This will convert the RTL into C++, compile the model, create the simulation binary, run the simulation, and start the waveform viewer. The output of the simulation should be the following:

*** Running simulation...

Creating model...
Registered DPI-C functions:
  scopesDump:
    SCOPE 0x55616d28b940: TOP.cpu_harness
       DPI-EXPORT 0x556136cc8f77: enable
       DPI-EXPORT 0x556136cc8f89: getLed
       DPI-EXPORT 0x556136cc8fda: getMem
       DPI-EXPORT 0x556136cc9006: getReg
       DPI-EXPORT 0x556136cc9242: loadRAM
       DPI-EXPORT 0x556136cdcc19: printMem
       DPI-EXPORT 0x556136cdcd88: printReg
       DPI-EXPORT 0x556136cc8fab: setBtn
       DPI-EXPORT 0x556136cc8f68: setClk
       DPI-EXPORT 0x556136cc8f78: setInitial
       DPI-EXPORT 0x556136cc8fea: setMem
       DPI-EXPORT 0x556136cc8fc9: setReset

Initializing SRAM memory from ../../../sw/risc-v/hello_world/helloWorld.hex
program set to helloWorld

Starting model...

Resetting...
Starting CPU...
Running for 500 clock cycles...

Printing evaluation for helloWorld program!

T=3960:                Hex          ASCII
Value at RAM[1024]: 0x68000000 : h
Value at RAM[1025]: 0x00000000 :
Value at RAM[1026]: 0x00000000 :
Value at RAM[1027]: 0x00000000 :


T=6840:                Hex          ASCII
Value at RAM[1024]: 0x68650000 : he
Value at RAM[1025]: 0x00000000 :
Value at RAM[1026]: 0x00000000 :
Value at RAM[1027]: 0x00000000 :


T=9720:                Hex          ASCII
Value at RAM[1024]: 0x68656c00 : hel
Value at RAM[1025]: 0x00000000 :
Value at RAM[1026]: 0x00000000 :
Value at RAM[1027]: 0x00000000 :


T=12600:               Hex          ASCII
Value at RAM[1024]: 0x68656c6c : hell
Value at RAM[1025]: 0x00000000 :
Value at RAM[1026]: 0x00000000 :
Value at RAM[1027]: 0x00000000 :


T=15480:               Hex          ASCII
Value at RAM[1024]: 0x68656c6c : hell
Value at RAM[1025]: 0x6f000000 : o
Value at RAM[1026]: 0x00000000 :
Value at RAM[1027]: 0x00000000 :


T=18360:               Hex          ASCII
Value at RAM[1024]: 0x68656c6c : hell
Value at RAM[1025]: 0x6f200000 : o
Value at RAM[1026]: 0x00000000 :
Value at RAM[1027]: 0x00000000 :


T=21240:               Hex          ASCII
Value at RAM[1024]: 0x68656c6c : hell
Value at RAM[1025]: 0x6f207700 : o w
Value at RAM[1026]: 0x00000000 :
Value at RAM[1027]: 0x00000000 :


T=24120:               Hex          ASCII
Value at RAM[1024]: 0x68656c6c : hell
Value at RAM[1025]: 0x6f20776f : o wo
Value at RAM[1026]: 0x00000000 :
Value at RAM[1027]: 0x00000000 :


T=27000:               Hex          ASCII
Value at RAM[1024]: 0x68656c6c : hell
Value at RAM[1025]: 0x6f20776f : o wo
Value at RAM[1026]: 0x72000000 : r
Value at RAM[1027]: 0x00000000 :


T=29880:               Hex          ASCII
Value at RAM[1024]: 0x68656c6c : hell
Value at RAM[1025]: 0x6f20776f : o wo
Value at RAM[1026]: 0x726c0000 : rl
Value at RAM[1027]: 0x00000000 :


T=32760:               Hex          ASCII
Value at RAM[1024]: 0x68656c6c : hell
Value at RAM[1025]: 0x6f20776f : o wo
Value at RAM[1026]: 0x726c6400 : rld
Value at RAM[1027]: 0x00000000 :


T=35640:               Hex          ASCII
Value at RAM[1024]: 0x68656c6c : hell
Value at RAM[1025]: 0x6f20776f : o wo
Value at RAM[1026]: 0x726c6421 : rld!
Value at RAM[1027]: 0x00000000 :


Done, closing simulation.

Important: The makefile reads the file lists hw/file_lists/rtl_flist.f and hw/file_lists/tb_flist.f. The make process does not recognize RTL or TB file changes, so it is required to run make clean after RTL or TB changes, otherwise the changed files will not be compiled.

Makefile details

By default, the hex-file sw/risc-v/hello_world.hex is loaded into the Main Memory before starting the simulation, and the simulation is run for 500 clock cycles. This behavior can by overriden by specifying PROG and NCYCLES environment variables, which will load the specified hex file and run for the specified number of clock cycles.

make run PROG=/path/to/myprog.hex NCYCLES=2000

You can also combine the different make targets.

make clean all run wave PROG=/path/to/myprog.hex NCYCLES=2000

Important: If the simulation is not showing the full expected result, make sure that the number of cycles are sufficient for the CPU to finish executing the program (check if the last instruction executed is the jump to halt instruction)

Available Make targets (commands)

make clean - remove old files
make - build and compile the RTL simulator using Verilator and GCC (alias for make all)
make run - run the simulation (requires built and compiled RTL)
make wave - show the waveform in Surfer
make clean all run wave - runs all the make targets (order is important)

It is not necessary to close the Surfer viewer if the simulation is run again. Just reload the Surfer window after the new run.

Things you need/can change

In the Makefile
- PROG - variable holding the hex file path of the program to be loaded
- NCYCLES - Variable for the number of cycles the CPU is going to run for
- TOPMODULE - Variable with the module name of the harness
Int the tb_flist.f
- Add new harnesses you have created

Things you can do

You can run the exact same tests you ran on EDA Playground and you should get the same results. However, the test here will be using verilator.
You can create your own harness and C++ testbenches for modules other than Decoder and CPU to get familiar with verilator testbenches
Compare Icarus and Verilator output (uninitialised memory locations are set to 'x' when using Icarus and '0' when using verilator)