R4VES: RISC-V Environment 4 Simulations

R4VES is a modular environment based on commercial EDA tools for fault and logic simulation of RISC-V cores. The tools are:

• Siemens QuestaSim: Questa Advanced Simulator for logic simulation
• Synopsys Z01X: Z01X Functional Safety Assurance for fault simulation

This simulation environment has been created to generalize test bench code. Many RTL designs typically are acompanied by their respective test benches which are very specific and in certain cases solid knowledge about the architecture specifics must be known to the test engineer in order to perform even a simple logic simulation. The goal of this environment is to abstract from the specifics of the architecture to ease the execution of logic and fault simulations and obtain resulting data from it (e.g., a value change dump (.vcd) file, or a test report (.rpt)). For fault simulation using the Z01X simulator a strobe file (strobe.sv) is provided that evaluates the SBST result at the end of the simulation.

Directory structure

• configurations: Configuration files to compile the SBST and do fault / logic simulations for processors
• sources: Test bench and source files for processor cores
  • gate_level: Gate level source files for the processor cores (synthesized for a technology library)
  • sbst: SBST programs in assembly for the processor cores
  • tech_libs: NanGate technology library etc. for synthesis
  • testbench: The main test bench (described below) that is used to simulate the processor cores
  • wave_config: Configurations for the wave window for ModelSim / QuestaSim for the processor cores
  • zoix: Z01X Configuration files and templates for logic and fault simulation
• execute.py: The main R4VES run script that parses the simulation configuration and launches the required tools
• Makefile: Runs the execute.py script for predefined processor configurations (for lazy people that don't want to type long commands - like me)

Using the tool

The tool has only a few configuration options:

• --config: Specifies the configuration that contains source and task configurations (located in the configurations directory).
• --tools: Specified the configuration that contains tool definitions (located in the tools directory).
• --force: Force overwriting generated files.
• --tasks: Specifies the task(s) that are executed.

To list all available tasks leave out the tasks option (configuration file is required).

Configuration files

The FSIM environment is configured via a JSON configuration file. This file is used to automatically adjust all necessary parts to the processor core at hand.

The configuration file is split into two main sections. As shown below one section is the sources section that defines the source files, environment variables, parameters, plusargs, commands and defines that are passed during compilation and execution. Every configuration option except sources can be left out if not required. The define, parameter, plusargs and environment settings can alternatively or additionally be indirectly specified via the _file options which contain =-separated key and value pairs.

• environment: Environment variables for the tools which can also be accessed via ::env(NAME) in TCL source files
• defines: Preprocessor macro definitions which can be accessed via #ifdef or `ifdef in C / Verilog / VHDL source files
• plusargs: Additional arguments which can be accessed via $value$plusargs("NAME=%d", TARGET) in Verilog / VHDL source files
• parameters: Instantiation parameters (param, localparam) which are used for the top level module in Verilog / VHDL source files
• commands: Additional command line parameters that are passed to the tools in ModelSim tasks

The second section is the task section. It contains the tasks that can be run via this tool. Each tasks is allowed to have defines, parameters, plusargs and environment settings exactly like in the sources section. A configuration section specifies

{
  "name": "my-processor",
  "sources": {
    "rtl": {
      "defines": {
        "MY_CONFIG": "42"
      },
      "defines_file": "my-processor.defines",
      "plusargs": [
        { "name": "my_config", "type": "value", "value": "42" },
        { "name": "my_file", "type": "file", "file": "my-processor.data" }
      ],
      "plusargs_file": "my-processor.plusargs",
      "parameters": {
        "processor.my_config": "32'h 42"
      },
      "parameters_file": "my-processor.parameters",
      "environment": [
        { "name": "MY_CONFIG", "type": "value", "value": "42" }
        { "name": "MY_FILE", "type": "file", "value": "my-processor.data" }
      ],
      "environment_file": "my-processor.environment",
      "sources": [
        { "type": "verilog", "file": "rtl-core.v" },
        { "type": "system-verilog", "file": "rtl-memory.sv" },
        { "type": "vhdl", "file": "rtl-bus.vhd" }
      ]
    },
    "testbench": {
      // More source definitions ...
    },
    "sbst-program": {
      "sources": [
        { "type": "assembly", "file": "sbst.asm" },
        { "type": "linker", "file": "sbst.ld" }
      ],
    },
    // More implementation sources here ...
  },
  "tasks": {
    "compile-sbst": {
      "description": "Cross-compiles the SBST program for RISC-V",
      "target": "gcc-compile",
      "sources": [ "sbst-program" ],
      "configuration": {
        // Task specific options here
      },
      "defines": { },
      "defines_file": "",
      "plusargs": [ ],
      "plusargs_file": "",
      "parameters": { },
      "parameters_file": "",
      "environment": [ ],
      "environment_file": ""
    },
    "logic-simulation-rtl-gui": {
      "description": "Run the logic simulation (RTL-level)",
      "target": "modelsim-logic-simulation",
      "sources": [ "rtl", "testbench" ],
      "configuration": {
        // Task specific options here
      },
      "defines": { },
      "defines_file": "",
      "plusargs": [ ],
      "plusargs_file": "",
      "parameters": { },
      "parameters_file": "",
      "environment": [ ],
      "environment_file": "",
      "commands": [
        // Or often called DO-file (my-processor.do)
        { "type": "file", "path": "my-processor.tcl" },
        { "type": "command", "command": "run -all" }
      ]
    },
    // More task definitions here ...
  }
}

Targets and Target Parameters

Each configuration task specifies a target which contains steps that are run consecutively. Each target and its parameters are listed in the following:

• Target gcc-compile: Compiles source code with GCC
  • Parameter machine-architecture: The RISC-V machine architecture -march flag (values: rv32e, rv32i, rv64e, rv64i)
  • Parameter machine-abi: The RISC-V ABI -mabi flag (values: ilp32e, lp32, lp32f, lp64, lp64f, lp64d)
  • Parameter elf-file: Output file for the generated program
  • Parameter hex-file: Output file for the generated memory image
  • Parameter map-file: Output file for the generated listing of the program
  • Parameter addresses-file: Output file that contains the addresses (hex) of _start and _sbst* labels
• Target modelsim-logic-simulation: Runs a logic simulation with ModelSim / QuestaSim
  • Parameter optimize-testbench: Enable optimization of the testbench via the vopt command (requires QuestaSim)
• Target zoix-logic-simulation: Runs a logic simulation with Z01X
  • Parameter faults_file: A Z01X fault definition file (SFF)
  • Parameter strobe_file: A Z01X strobe file that will be used for untestability analysis on fault list creation
  • Parameter init_script: A script to initialize the testbench (used for loading memories)
  • Parameter memory_file: A HEX memory image that is used to initialize the memory by the init script
• Target zoix-fault-simulation: Runs a fault simulation with Z01X
  • Parameter faults_file: A Z01X fault definition file (SFF)
  • Parameter strobe_file: A Z01X strobe file that will be used for untestability analysis on fault list creation
  • Parameter init_script: A script to initialize the testbench (used for loading memories)
  • Parameter memory_file: A HEX memory image that is used to initialize the memory by the init script
  • Parameter fsim_script: A fault simulation script to run the fault injection campaign
  • Parameter coverage_file: Output file for the generated fault coverage
  • Parameter summary_file: Output file for the generated fault summary

Test Bench

The test bench is configurable in the form of defines (in compilation time) and plusargs (in run-time). Define names are using capital case while plusarg names are all in lower case. Often a define is used to enable a feature and additional plusarg are used to configure it. These configuration options are:

Argument	Required	Depends on	Description
TESTBENCH_CLOCK_PERIOD_NS	Yes		Period of the CLK signal in nanoseconds.
TESTBENCH_RESET_CYCLES	Yes		Number of clock cycles for the RST signal to be active.
TESTBENCH_EXIT_ON_EXCEPTION	No		Exits the test bench if the processor signals an exception / trap.
TESTBENCH_SBST_OBSERVE	No	sbst_program_start, sbst_program_end	Prints the time when the SBST reaches the start and end markers.
TESTBENCH_VCD_DUMP	No	dump_vcd	Enables dumping the testbench trace as VCD.
TESTBENCH_PROBES_DUMP	No	dump_signals	Enables dumping signals that are selected by the signal list.
TESTBENCH_PROBES_DUMP_TRIGGER	No	TESTBENCH_PROBES_DUMP, dump_at, dump_trigger_console, dump_trigger_file	Dumps the specified signal list when the specific time point is reached.
TESTBENCH_PROBES_DUMP_SBST_START	No	TESTBENCH_PROBES_DUMP, sbst_program_start, dump_sbst_start_console, dump_sbst_start_file	Dumps the specified signal list when the start of the SBST is reached.
TESTBENCH_PROBES_DUMP_SBST_END	No	TESTBENCH_PROBES_DUMP, sbst_program_end, dump_sbst_end_console, dump_sbst_end_file	Dumps the specified signal list when the end of the SBST is reached.
TESTBENCH_TIMEOUT	No	timeout	Exits the test bench if the specified number of clock cycles has been reached.
TESTBENCH_SBST_AUTO_EXIT	No	sbst_program_end	Exits the test bench if the end of the SBST program has been reached.
TESTBENCH_TARGET_PICORV32	No		Enables the PicoRV32 processor in the test bench.
TESTBENCH_TARGET_DARKRISCV	No		Enables the DarkRISCV processor in the test bench.
TESTBENCH_TARGET_CV32E4OP	No		Enables the CV32E40P processor in the test bench.
log_debug	No		Enables debug level output to the console during simulation.
timeout	No		Timeout of the test bench in nanoseconds.
dump_vcd	No		Output filename for the VCD file.
dump_signals	No		Input filename of signals to dump.
dump_at	No		Time in nanoseconds when to dump the signals.
dump_trigger_console	No		Enable (1) or disable (0) dump of the signals to the console.
dump_trigger_file	No		Output filename to dump the signals to. Leave empty to disable.
dump_sbst_start_console	No		Enable (1) or disable (0) dump of the signals to the console.
dump_sbst_start_file	No		Output filename to dump the signals to. Leave empty to disable.
dump_sbst_end_console	No		Enable (1) or disable (0) dump of the signals to the console.
dump_sbst_end_file	No		Output filename to dump the signals to. Leave empty to disable.
sbst_program_start	No		Start address of the SBST program in bytes (HEX).
sbst_program_end	No		End address of the SBST program in bytes (HEX).
----------------------------------	--------	------------------------------------------------------------------------------------------------	-----------------------------------------------------------------------------------
MEMORY_ADDRESS_BITS	Yes		Specifies the number of bytes of the memory (in 2^MEMORY_ADDRESS_BITS).
MEMORY_DUAL_PORT	No		Enables the memory dual port access of the memory.
MEMORY_ENABLE_DEBUG	No	memory_debug	Enable debugging facility of memory transactions.
MEMORY_ENABLE_LOAD	No	memory_image	Enables loading a memory image on test bench start.
memory_debug	No	log_debug	Print the memory transactions to the console.
memory_image	No		The memory image file (HEX) to initialize the memory with on test bench startup.
----------------------------------	--------	--------------------------------------------------------------------------------------------	-----------------------------------------------------------------------------------
STROBE_SBST_OBSERVE	No	sbst_program_start, sbst_program_end	Prints the time when the SBST reaches the start and end markers.
STROBE_TIMEOUT	No	timeout	Terminates the simulation if the specified number of clock cycles has been reached.
STROBE_SBST_TYPE1	No	sbst_program_end, sbst_end_timeout	Enables fault evaluation for SBST type 1.
STROBE_TARGET_PICORV32	No		Enables the SBST evaluation for the PicoRV32 processor.
STROBE_TARGET_DARKRISCV	No		Enables the SBST evaluation for the DarkRISCV processor.
STROBE_TARGET_CV32E4OP	No		Enables the SBST evaluation for the CV32E40P processor.

Firmware compilation

Running a logic simulation of any of the RISC-V cores requries an SBST firmware memory image in the form of a .hex file. The firmware is loaded into the memory via the $readmemh command before the simulation starts.

The compilation process consists of:

1. Compiling sources .asm to intermediate object .o files via the compiler.
2. Linking the object files via the linker script .ld into a RISC-V executable .elf file using the linker.
3. Conversion of the executable to a memory image .hex file with the help of the objdump tool.
4. Creation of an address listing .addresses file via the objdump tool.

Citations

You can reference the R4VES framework by using the following @misc entry in Bibtex

@misc{misc:r4ves,
    author       = "{CAD Group, Politecnico di Torino \& University of Freiburg}",
    title        = "{R4VES: RISC-V Environment For Simulations}",
    howpublished = "\url{https://github.com/cad-polito-it/r4ves}",
    year         = "2023"
}

Contact Information

• Nick Deligiannis
• Tobias Faller