# Quick setup
The following instructions will allow you to compile and run a Verilator model of the CVA6 APU (which instantiates the CVA6 core) within the CVA6 APU testbench (corev_apu/tb).
Throughout all build and simulations scripts executions, you can use the environment variable `NUM_JOBS` to set the number of concurrent jobs launched by `make`:
- if left undefined, `NUM_JOBS` will default to 1, resulting in a sequential execution
of `make` jobs;
- when setting `NUM_JOBS` to an explicit value, it is recommended not to exceed 2/3 of
the total number of virtual cores available on your system.
1. Checkout the repository and initialize all submodules.
```sh
git clone https://github.com/openhwgroup/cva6.git
cd cva6
git submodule update --init --recursive
```
2. Install the GCC Toolchain [build prerequisites](util/toolchain-builder/README.md#Prerequisites) then [the toolchain itself](util/toolchain-builder/README.md#Getting-started).
:warning: It is **strongly recommended** to use the toolchain built with the provided scripts.
3. Install `cmake`, version 3.14 or higher.
4. Set the RISCV environment variable.
```sh
export RISCV=/path/to/toolchain/installation/directory
```
5. Install `help2man` and `device-tree-compiler` packages.
For Debian-based Linux distributions, run :
```sh
sudo apt-get install help2man device-tree-compiler
```
6. Install the riscv-dv requirements:
```sh
pip3 install -r verif/sim/dv/requirements.txt
```
7. Run these commands to install a custom Spike and Verilator (i.e. these versions must be used to simulate the CVA6) and [these](#running-regression-tests-simulations) tests suites.
```sh
# DV_SIMULATORS is detailed in the next section
export DV_SIMULATORS=veri-testharness,spike
bash verif/regress/smoke-tests.sh
```
# Running standalone simulations
Simulating the CVA6 is done by using `verif/sim/cva6.py`.
The environment variable `DV_SIMULATORS` allows you to specify which simulator to use.
Four simulation types are supported:
- **veri-testharness**: verilator with corev_apu/testharness testbench
- **vcs-testharness**: vcs with corev_apu/testharness testbench
- **vcs-uvm**: vcs with UVM testbench
- **Spike** ISS
You can set several simulators, such as :
```sh
export DV_SIMULATORS=veri-testharness,vcs-testharness,vcs_uvm
```
If exactly 2 simulators are given, their trace is compared ([see the Regression tests section](#running-regression-tests-simulations)).
Here is how you can run the hello world C program with the Verilator model:
```sh
# Make sure to source this script from the root directory
# to correctly set the environment variables related to the tools
source verif/sim/setup-env.sh
# Set the NUM_JOBS variable to increase the number of parallel make jobs
# export NUM_JOBS=
export DV_SIMULATORS=veri-testharness
cd ./verif/sim
python3 cva6.py --target cv32a60x --iss=$DV_SIMULATORS --iss_yaml=cva6.yaml \
--c_tests ../tests/custom/hello_world/hello_world.c \
--linker=../../config/gen_from_riscv_config/linker/link.ld \
--gcc_opts="-static -mcmodel=medany -fvisibility=hidden -nostdlib \
-nostartfiles -g ../tests/custom/common/syscalls.c \
../tests/custom/common/crt.S -lgcc \
-I../tests/custom/env -I../tests/custom/common"
```
You can run either assembly programs (check `verif/test/custom/hello_world/custom_test_template.S`) or C programs. Run `python3 cva6.py --help` to have more informations on the available parameters.
## Simulating with VCS and Verdi
You can set the environment variable `VERDI` as such if you want to launch Verdi while simulating with VCS:
```sh
export VERDI=1
```
# Running regression tests simulations
The smoke-tests script installs a random instruction generator and several tests suites:
- [riscv-dv](https://github.com/chipsalliance/riscv-dv)
- [riscv-compliance](https://github.com/lowRISC/riscv-compliance)
- [riscv-tests](https://github.com/riscv-software-src/riscv-tests)
- [riscv-arch-test](https://github.com/riscv-non-isa/riscv-arch-test)
The regression tests are done by comparing a model simulation trace with the Spike trace.
Several tests scripts can be found in `./verif/regress`
For example, here is how would run the riscv-arch-test regression test suite with the Verilator model:
```sh
export DV_SIMULATORS=veri-testharness,spike
bash verif/regress/dv-riscv-arch-test.sh
```
# Logs
The logs from cva6.py are located in `./verif/sim/out_YEAR-MONTH-DAY`.
Assuming you ran the smoke-tests scripts in the previous step, here is the log directory hierarchy:
- **directed_asm_tests/**: The compiled (to .o then .bin) assembly tests
- **directed_c_tests/**: The compiled (to .o then .bin) c tests
- **spike_sim/**: Spike simulation log and trace files
- **veri_testharness_sim**: Verilator simulation log and trace files
- **iss_regr.log**: The regression test log
The regression test log summarizes the comparison between the simulator trace and the Spike trace. Beware that a if a test fails before the comparison step, it will not appear in this log, check the output of cva6.py and the logs of the simulation instead.
# Waveform generation
Waveform generation is currently supported for Verilator (`veri-testharness`)
and VCS with full UVM testbench (`vcs-uvm`) simulation types. It is disabled
by default to save simulation time and storage space.
To enable waveform generation for a supported simulation mode, set either
of the two shell variables that control tracing before running any of the
test scripts under `verif/regress`:
- `export TRACE_FAST=1` enables "fast" waveform generation (keep simulation
time low at the expense of space). This will produce VCD files when using
Verilator, and VPD files when using Synopsys VCS with UVM testbench (`vcs-uvm`).
- `export TRACE_COMPACT=1` enables "compact" waveform generation (keep waveform
files smaller at the expense of increased simulation time). This will
produce FST files when using Verilator, and FSDB files when using Synopsys
VCS with UVM testbench (`vcs-uvm`).
To generate VCD waveforms of the `smoke-tests` regression suite using Verilator, use:
```sh
export DV_SIMULATORS=veri-testharness,spike
export TRACE_FAST=1
bash verif/regress/smoke-tests-``` @article{zaruba2019cost, author={F. {Zaruba} and L. {Benini}}, journal={IEEE Transactions on Very Large Scale Integration (VLSI) Systems}, title={The Cost of Application-Class Processing: Energy and Performance Analysis of a Linux-Ready 1.7-GHz 64-Bit RISC-V Core in 22-nm FDSOI Technology}, year={2019}, volume={27}, number={11}, pages={2629-2640}, doi={10.1109/TVLSI.2019.2926114}, ISSN={1557-9999}, month={Nov}, } ```