7. DUT Plugins¶
7.1. Chromite DUT¶
Chromite Core Generator plugin is based on the Chromite core generator developed by Incore Semiconductors. The core generator emits synthesizable, production quality RTL of processors based on the open RISC-V ISA. This guide will explain the steps to install all dependencies to run this plugin.
7.1.1. Pre-requisites¶
You will need to install the following before using this plugin:
The riscv-gnu-toolchain for compiling the tests
The elf2hex utility required for converting the elf’s to hex files for simulation.
The open-source bluespec compiler
Verilator needs to exist on your $path
Warning
Only Mod-spike should be used as a reference for the current version of chromite.
7.1.2. Setting up the DUT¶
To setup Chromite as a DUT model for RiVer Core you will need to generate the verilog for your choice of configuration and provide the paths to the verilog to the plugin.
To generate verilog of the default Chromite configuration:
$ cd ~/myquickstart
$ git clone https://gitlab.com/incoresemi/core-generators/chromite.git
$ cd chromite
$ pip install -r requirements.txt
$ python -m configure.main
$ make -j<jobs> generate_verilog
The Chromite test-soc expects all tests to be loaded at address 0x80000000
. The tests are loaded
using the regular “readmemh” command in verilog. Thus each test is converted to hex files using the
elf2hex command that comes with spike.
Chromite test-soc used for simulation also requires a simple boot-code. This is checked in to the
boot
directory inside the plugin. Currently this boot-code includes a basic dts file and
indirection to address 0x80000000
at the beginning itself. The Makefile in the boot
directory
is used to create the required boot hex files.
7.1.3. Plugin Flow¶
There are multiple plugin variants available. Based on the simulator of choice, each plugin will first compile the verilog and generate an executable. The compilation can account for the fact of whether coverage is enabled or not. This is done as part of the init stage. The init stage will also build all the collateral like boot.hex files that will be required for simulation.
The build stage will parse through the test-list provided and create a makefile. For each test a
target in the makefile is created. The the targets are defined such that they can all be run in
parallel with as many jobs as possible. This makefile will be written to the directory pointed by
the workdir
variable of the main config.ini
file.
The run stage simply passes on the make file command to the pytest environment for parallel execution and report generation.
For each test RiVer Core expects the generation of a dut.dump
which is the execution log of that
test to be present in the working-dir of that test as specified in the test-list. If coverage is
enabled then each test run will also generate the coverage database which can be merged/ranked
together. The dump format matches the dump created by mod-spike using the -c
option.
The post_run stage is used to clean up unwanted artifacts and files generated by each test. The
following set of files are no longer preserved if tests pass on the DUT. They are preserved only
when a test-fails for debugging purposes. This feature is enabled only when space_saver
flag in
the main config.ini
is set to True
.
app_log
code.mem
dut.disass
dut.dump
signature
7.1.4. Plugin Variants¶
The following variants of the chromite core are available. They each differ in based on the simulator of choice
7.1.4.1. Chromite_Cadence¶
For this plugin ensure you have setup Cadence in your path. Binaries used by this plugin:
ncvlog
ncelab
imc
Note
The user is advised to ensure all of the above binaries are accessible via the shell that will be running RiVer Core.
When the --coverage
argument is provided to the RiVer Core compile command, the chromite core is
compiled with coverage flags enabled. Depending on the settings of the functional
and code
respective coverage metrics are enabled during the simulation of each test.
The post_run hook will remove the following additional files:
imc.*
mdv.log
ncsim.log
The merge_db hook is used to merge the coverage databases of multiple tests and also provide a
ranking report. The tool used for coverage, merging and ranking is imc
.
To use this plugin, set the target
in the main config.ini
to chromite_cadence.
7.1.4.2. Chromite_Questa¶
For this plugin ensure you have setup Questa Tools in your path. Binaries used by this plugin:
vlib
vlvog
vsim
vcover
Note
The user is advised to ensure all of the above binaries are accessible via the shell that will be running RiVer Core.
When the --coverage
argument is provided to the RiVer Core compile command, the chromite core is
compiled with coverage flags enabled. Depending on the settings of the functional
and code
respective coverage metrics are enabled during the simulation of each test.
The post_run hook will remove all files in the coverage folder of that test that do not end with
.ucdb
The merge_db hook is used to merge the coverage databases of multiple tests and also provide a ranking report.
To use this plugin, set the target
in the main config.ini
to chromite_questa.
7.1.4.3. Chromite_Verilator¶
For this plugin ensure you have installed verilator and it is available in your path.
To use this plugin, set the target
in the main config.ini
to chromite_verilator.
7.1.5. Instance in config.ini
¶
For any of the above variants, only the target
setting needs to change in the following sample
instance code. The src_dir
should contain all paths which will contain the necessary verilog
files for compiling the core (in a comma separated fashion). The src_dir
should typically
include the following:
the build/hw/verilog directory of the chromite core
the common_log directory of the bsvwrappers repository
the Verilog directory of the bluespec compiler installation.
target = chromite_verilator
path_to_target = ~/river_core_plugins/dut_plugins
[chromite_verilator]
jobs = 8
# src dir: Verilog Dir, BSC Path, Wrapper path
src_dir = /scratch/git-repo/incoresemi/core-generators/chromite/build/hw/verilog/,/software/experimental/open-bsc//lib/Verilog,/scratch/git-repo/incoresemi/core-generators/chromite/bsvwrappers/common_lib
# Top Module for simulation
top_module = mkTbSoc
7.2. C-Class DUT¶
C-Class Core Generator plugin is a core generator developed by IIT Madras.
7.2.1. Pre-requisites¶
You will need to install the following before using this plugin:
The riscv-gnu-toolchain for compiling the tests
The elf2hex utility required for converting the elf’s to hex files for simulation.
The open-source bluespec compiler
Verilator needs to exist on your $path
7.2.2. Setting up the DUT¶
To setup C-Class as a DUT model for RiVer Core you will need to generate the verilog for your choice of configuration and provide the paths to the verilog to the plugin.
To generate verilog of the default C-Class configuration:
$ cd ~/myquickstart
$ git clone https://gitlab.com/incoresemi/core-generators/c-class.git
$ cd c-class
$ pip install -r requirements.txt
$ python -m configure.main
$ make -j<jobs> generate_verilog
The C-Class test-soc expects all tests to be loaded at address 0x80000000
. The tests are loaded
using the regular “readmemh” command in verilog. Thus each test is converted to hex files using the
elf2hex command that comes with spike.
C-Class test-soc used for simulation also requires a simple boot-code. This is checked in to the
boot
directory inside the plugin. Currently this boot-code includes a basic dts file and
indirection to address 0x80000000
at the beginning itself. The Makefile in the boot
directory
is used to create the required boot hex files.
7.2.3. Plugin Flow¶
There are multiple plugin variants available. Based on the simulator of choice, each plugin will first compile the verilog and generate an executable. The compilation can account for the fact of whether coverage is enabled or not. This is done as part of the init stage. The init stage will also build all the collateral like boot.hex files that will be required for simulation.
The build stage will parse through the test-list provided and create a makefile. For each test a
target in the makefile is created. The the targets are defined such that they can all be run in
parallel with as many jobs as possible. This makefile will be written to the directory pointed by
the workdir
variable of the main config.ini
file.
The run stage simply passes on the make file command to the pytest environment for parallel execution and report generation.
For each test RiVer Core expects the generation of a dut.dump
which is the execution log of that
test to be present in the working-dir of that test as specified in the test-list. If coverage is
enabled then each test run will also generate the coverage database which can be merged/ranked
together. The dump format matches the dump created by spike using the --log-commits
option.
The post_run stage is used to clean up unwanted artifacts and files generated by each test. The
following set of files are no longer preserved if tests pass on the DUT. They are preserved only
when a test-fails for debugging purposes. This feature is enabled only when space_saver
flag in
the main config.ini
is set to True
.
app_log
code.mem
dut.disass
dut.dump
signature
7.2.4. Plugin Variants¶
The following variants of the c-class core are available. They each differ in based on the simulator of choice
7.2.4.1. C-Class_Verilator¶
For this plugin ensure you have installed verilator and it is available in your path.
To use this plugin, set the target
in the main config.ini
to cclass_verilator.
7.2.5. Instance in config.ini
¶
For any of the above variants, only the target
setting needs to change in the following sample
instance code. The src_dir
should contain all paths which will contain the necessary verilog
files for compiling the core (in a comma separated fashion). The src_dir
should typically
include the following:
the build/hw/verilog directory of the c-class core
the common_log directory of the bsvwrappers repository
the Verilog directory of the bluespec compiler installation.
target = cclass_verilator
path_to_target = ~/river_core_plugins/dut_plugins
[cclass_verilator]
jobs = 8
# src dir: Verilog Dir, BSC Path, Wrapper path
src_dir = /scratch/git-repo/shaktiproject/cores/c-class/build/hw/verilog/,/software/open-bsc/lib/Verilog,/scratch/git-repo/shaktiproject/cores/c-class/common_verilog/
# Top Module for simulation
top_module = mkTbSoc