Debugging RTL
======================

While the packaged Chipyard configs and RTL have been tested to work,
users will typically want to build custom chips by adding their own
IP, or by modifying existing Chisel generators. Such changes might introduce
bugs. This section aims to run through a typical debugging flow
using Chipyard. We assume the user has a custom SoC configuration,
and is trying to verify functionality by running some software test.
We also assume the software has already been verified on a functional
simulator, such as Spike or QEMU. This section will focus on debugging
hardware.

Waveforms
---------------------------

The default software RTL simulators do not dump waveforms during execution.
To build simulators with wave dump capabilities use must use the ``debug``
make target. For example:

.. code-block:: shell

   make CONFIG=CustomConfig debug

The ``run-binary-debug`` rule will also automatically build a simulator,
run it on a custom binary, and generate a waveform. For example, to run a
test on ``helloworld.riscv``, use

.. code-block:: shell

   make CONFIG=CustomConfig run-binary-debug BINARY=helloworld.riscv

VCS and Verilator also support many additional flags. For example, specifying
the ``+vpdfilesize`` flag in VCS will treat the output file as a circular
buffer, saving disk space for long-running simulations. Refer to the VCS
and Verilator manuals for more information You may use the ``SIM_FLAGS``
make variable to set additional simulator flags:

.. code-block:: shell

   make CONFIG=CustomConfig run-binary-debug BINARY=linux.riscv SIM_FLAGS=+vpdfilesize=1024

Print Output
---------------------------

Both Rocket and BOOM can be configured with varying levels of print output.
For information see the Rocket core source code, or the BOOM `documentation 
<https://docs.boom-core.org/en/latest/>`__ .website. In addition, developers
may insert arbitrary printfs at arbitrary conditions within the Chisel g
enerators. See the Chisel documentation for information on this.

Once the cores have been configured with the desired print statements, the
``+verbose`` flag will cause the simulator to print the statements. The following
commands will all generate desired print statements:

.. code-block:: shell

   make CONFIG=CustomConfig run-binary-debug BINARY=helloworld.riscv
   # The below command does the same thing
   ./simv-CustomConfig-debug +verbose helloworld.riscv

Both cores can be configured to print out commit logs, which can then be compared
against a Spike commit log to verify correctness.

Basic tests
---------------------------
``riscv-tests`` includes basic ISA-level tests and basic benchmarks. These
are used in Chipyard CI, and should be the first step in verifying a chip's
functionality. The make rule is

.. code-block:: shell

   make CONFIG=CustomConfig run-asm-tests run-bmark-tests


Torture tests
---------------------------
The RISC-V torture utility generates random RISC-V assembly streams, compiles them,
runs them on both the Spike functional model and the SW simulator, and verifies
identical program behavior. The torture utility can also be configured to run
continuously for stress-testing. The torture utility exists within the ``utilities``
directory.

Firesim Debugging
---------------------------
Chisel printfs, asserts, and waveform generation are also available in FireSim
FPGA-accelerated simulation. See the FireSim
`documentation <https://docs.fires.im/en/latest/>`__ for more detail.