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

8.3.1. 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:

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

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:

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


In some cases where there is multiple simulator flags, you can write the SIM_FLAGS like the following: SIM_FLAGS="+vpdfilesize=XYZ +some_other_flag=ABC".

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

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

8.3.4. 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 tools directory. To run torture tests, run make in the simulation directories:

make CONFIG=CustomConfig torture

To run overnight tests (repeated random tests), run

make CONFIG=CustomConfig TORTURE_ONIGHT_OPTIONS=<overnight options> torture-overnight

You can find the overnight options in overnight/src/main/scala/main.scala in the torture repo.

8.3.5. Firesim Debugging

Chisel printfs, asserts, Cospike co-simulation, and waveform generation are also available in FireSim FPGA-accelerated simulation. See the FireSim documentation for more detail.