.. ECE 574
.. attention::
This document was last updated |today|
.. _03simulation:
Simulation
==========
.. important::
The purpose of this lecture is as follows.
* To review basic principle of event-driven HDL simulation
* To review and use the Xcelium simulator of Cadence (handson)
* To review and use the Verilator Open-Source Simulator (handson)
.. attention::
The following references are relevant background to this lecture.
* `Verilator Homepage `_
* `IBEX RISC-V Core Homepage `_
HDL Simulation
--------------
Please refer to the slide deck :download:`PDF `
Cadence Xcelium
---------------
Please refer to the Cadence Course Materials on Canvas
Verilator
---------
Introduction
^^^^^^^^^^^^
- Please refer to the slide deck on Verilator Roadmap :download:`PDF `
- Please refer to the slide deck on Verilator 10 Creative Uses :download:`PDF `
Handson
^^^^^^^
This section provides background to set up the simulation experiments using Verilator.
You have to run this on the class design server. Furthermore, during the experiments, you must use to the most recent C++ toolset with the following command.
.. code::
scl enable devtoolset-9 bash
This command opens a new shell which switches the C compiler (temporarily) to a more up-to-date version as needed to work with Verilator and the IBEX core.
The purpose of the Verilator handson is to show you a non-trivial application of system simulation.
We will use the IBEX RISC-V core, an open-source 32-bit RISC-V core written in SystemVerilog.
Simulating a microprocessor system in HDL is a sophisticated operation because of the multiple layers of design abstraction involved in the simulation
1. First, you have to compile the software application into an binary image with RISC-V instructions
2. Next, you have to build a system simulation that includes the core, the program memory and related periphers
The following sequence of steps walks you through the simulation setup. However, you will see that the out-of-the-box instructions (taken from the GitHub repository) create simulation errors, which you have to resolve. The writeup below suggest possible resolutions but does not directly give the full solution.
To complete this assignment, the design server has several tools installed. Make sure to update your ``~/.bashrc`` as explained on the Canvas Course Homepage. The tools installed include:
* /opt/riscv: RiscV Compiler Toolchain
* C compiler (toolchain 7 and toolchain 9)
* Verilator: Compiler Simulator
* GTKWave: Waveform Viewer
We start by downloading the IBEX core from github.
.. code::
git clone https://github.com/lowRISC/ibex.git
cd ibex
pip3 install -U -r python-requirements.txt
IBEX comes with extensive documentation, both in README form on GitHub, as well as using a `User Manual `_ in markdown format. Our objective is to simulate the Simple
System as described in the `documentation online `_
However, make sure you take a good look at the IBEX source tree before starting with the handson.
Building the Simulator
""""""""""""""""""""""
Inspect the ``Makefile`` in the IBEX main directory. Note the different targets, which will be used in commands below.
Build the simulator in the ibex main directory with the following command.
.. code::
make build-simple-system
This command runs Verilator in the IBEX SystemVerilog code. However, you will see several warning/errors appear such as:
.. code::
ERROR: %Warning-MULTIDRIVEN: ../src/lowrisc_ibex_ibex_tracer_0.1/rtl/ibex_tracer.sv:762:5: Variable written to in always_comb also written by other process (IEEE 1800-2017 9.2.2.2): 'decoded_str'
%Warning-MULTIDRIVEN: ../src/lowrisc_ibex_ibex_tracer_0.1/rtl/ibex_tracer.sv:763:5: Variable written to in always_comb also written by other process (IEEE 1800-2017 9.2.2.2): 'data_accessed'
%Warning-BLKSEQ: ../src/lowrisc_ibex_ibex_tracer_0.1/rtl/ibex_tracer.sv:119:19: Blocking assignment '=' in sequential logic process
By default, Verilator enables strict checking on the input code. By adding waivers, these warnings can be suppressed and the simulator build can succeed. Study the list of waivers in ``lint/verilator_waiver.vlt`` and add new waivers to get rid of these warnings.
Building the test software
""""""""""""""""""""""""""
The sample program to run on the IBEX simulation is stored in ``examples/sw/simple_system/hello_test/hello_test.c``. Take a close look at the program, as you will have to track its execution later in the Verilator simulation.
Compile the test software with the following command.
.. code::
make sw-simple-hello
This command uses the RISC-V cross compiler to create a memory image for the simulation. However, you will see the compilation crash. There are two problems with the default compilation instructions stored in ``examples/sw/simple_system/common/common.mk``:
1. The configuration calls the cross compiler as ``risc32-unknown-elf-gcc`` instead of ``risc64-unknown-elf-gcc`` (the cross compiler available on the design server).
2. The configuration compiles the RISCV software for a ``rv32imc`` architecture instead of a ``rv32imc_zicsr``
Make both of these changes in ``common.mk`` and build ``sw-simple-hello``
Run the simulator
"""""""""""""""""
You can run the Verilator simulation with the following command.
.. code::
make run-simple-system
By default, the simulation will print out only a view diagnostics:
.. code::
Simulation statistics
=====================
Executed cycles: 13138
Wallclock time: 0.045 s
Simulation speed: 291956 cycles/s (291.956 kHz)
Trace file size: 532836 B
You can view the simulation traces by calling
$ gtkwave sim.fst
Performance Counters
====================
Cycles: 475
NONE: 0
Instructions Retired: 261
LSU Busy: 0
Fetch Wait: 0
Loads: 0
Stores: 0
Jumps: 0
Conditional Branches: 0
Taken Conditional Branches: 0
Compressed Instructions: 0
Multiply Wait: 0
Divide Wait: 0
As a hardware simulation, we would like to see the actual waveform diagrams of intermediate signals. This can be done by adding the -t (trace) flag to the simulation. You have to add this flag by editing the ``run-simple-system`` target in the main makefile. When you run the simulation with the trace flag present, you will find a file ``sim.fst`` being produced. This is the waveform trace file.
View the simulation waveform
""""""""""""""""""""""""""""
Use GTKWave to inspect the IBEX waveform diagram.
.. code::
gtkwave sim.fst
You should be able to demonstrate a periodically executing timer interrupt. The questions of the Quiz related to the software source code ``examples/sw/simple_system/hello_test/hello_test.c`` on the one hand, and the waveform diagram on the other hand.
.. figure:: images/ibexwave.png
:figwidth: 600px
:align: center