# Verilator-Compatible Testbench for the HPDcache

This is a Verilator-compatible (with SystemC) testbench for the HPDcache block.

It is a standalone testbench where the HPDcache is not connected to a processor
core. Requests are generated by agents using a sequence defined by the user.
Some sequences are already provided in the sequence_lib subdirectory.

The testbench also implements a memory response model that acts as the main
memory of the system.

All the requests and responses to/from the HPDcache are validated automatically
by the testbench scoreboard.

## Prerequisites

This testbench requires the following tools and libraries pre-installed:

- [Verilator](https://verilator.org/guide/latest/install.html) - Version 5.018 or newer
- [SystemC Library](https://www.accellera.org/downloads/standards/systemc) - Version 2.3.4 or newer
- [SystemC Verification Library (SCV)](https://www.accellera.org/downloads/standards/systemc) - Version 2.0.1 or newer
- Perl - Version 5

Please follow the corresponding installation instructions for those packages to
install them in your system prior to the execution of this testbench.
Alternatively, you can also follow the instructions in the
[CONTRIBUTING.md](https://github.com/openhwgroup/cv-hpdcache/blob/master/CONTRIBUTING.md)
file to install these tools and libraries with the provided scripts.

You need to set the following environment variables (bash: `$ export`, csh: `$ setenv`):

- Set the SYSTEMC_LIBDIR to the libdir directory of the SystemC library installation
  (e.g. `$ export SYSTEMC_LIBDIR=<systemc-install-dir>/lib-linux64`)
- Add the bin/ subdirectory of the Verilator installation into your PATH
  (e.g. `$ export PATH=<verilator-install-dir>/bin:${PATH}`)

If you installed the tools using the instructions in
[CONTRIBUTING.md](https://github.com/openhwgroup/cv-hpdcache/blob/master/CONTRIBUTING.md),
then you can set above environment variables by sourcing the
[.github/scripts/env.sh](https://github.com/openhwgroup/cv-hpdcache/blob/master/.github/scripts/env.sh)
file.

In addition to above packages, the C++ code of this testbench is and shall be
formatted using the clang-format tool. The .clang-format file contains the
configuration.

- [ClangFormat](https://clang.llvm.org/docs/ClangFormat.html)

## Usage

Show the help message of the testbench:

```bash
$ make help
```

### The basic usage of the testbench is to execute the following sequence of commands

1. Verilate the RTL (convert to C++) and build the testbench:

Both stages with a single command:

```bash
$ make build -j<parallel_jobs>
```

Or both stages separately:

```bash
$ make verilate
$ make build -j<parallel_jobs>
```

If you have any errors or warnings, you can look into them in more detail on
their corresponding log files:

- build/verilate.log
- build/build.log

2. Run a simulation choosing one sequence. It can be for example the random
sequence (defined in the file sequence_lib/hpdcache_test_random_seq.h):

```bash
$ make run SEQUENCE=random LOG_LEVEL=1 NTRANSACTIONS=10000 SEED=42
```

If you need to debug the simulation waveforms, you can generate them in VCD
format using passing the TRACE=1 argument to the run command of the makefile:

```bash
$ make run SEQUENCE=random LOG_LEVEL=1 NTRANSACTIONS=10000 SEED=42 TRACE=1
```

Then to save some disk space, you can convert the VCD file to the FST format
using the vcd2fst script. For example, to convert the VCD file generated by the
previous command, you can use the following command:

```bash
$ ./scripts/vcd2fst.sh logs/run_random_42.vcd
```

This will replace the `logs/run_random_42.vcd` by the `logs/run_random_42.vcd.fst`.

### Non-regression suite

First build the testbench as explained above.

Then, the following example command will run 32 tests (with 32 different seeds)
using the random sequence:

```bash
$ make nonregression SEQUENCE=random LOG_LEVEL=1 NTRANSACTIONS=10000 NTESTS=32
```

### Fault-Injection

You can enable the injection of soft-errors in HPDcache's SRAMs during the
simulation.

To do so, when compiling the platform you can pass the following options:
```bash
make build CONF_HPDCACHE_TEST_FAULT_INJ=1
```

By default, the testbench only inject faults into SRAMs storing the cache data.
To also inject faults in the cache directory:
```bash
make build CONF_HPDCACHE_TEST_FAULT_INJ=1 \
           CONF_HPDCACHE_TEST_FAULT_INJ_DIR=1
```

Finally, if you want to enable double faults (by default only single errors are
enabled), do as follows:
```bash
make build CONF_HPDCACHE_TEST_DOUBLE_FAULT_INJ=1 \
           CONF_HPDCACHE_TEST_FAULT_INJ_DIR=1
```

Both ```CONF_HPDCACHE_TEST_FAULT_INJ_DIR``` and
```CONF_HPDCACHE_TEST_DOUBLE_FAULT_INJ``` can be enabled together or
separately.

These options can also be passed to the nonregression target:
```bash
make nonregression <other nonreg options> \
                   CONF_HPDCACHE_TEST_FAULT_INJ=1 \
                   CONF_HPDCACHE_TEST_FAULT_INJ_DIR=1
```

### Logs

The build logs are written in the `build/` subdirectory. The simulation logs
are written in the `logs/` subdirectory.
