Configuration file and wizard script
In order to facilitate the usage of Verisocks with Verilator, a command line
wizard script vsl-wizard is provided with the verisocks
python package. This script generates automatically a Makefile, a C++ top
testbench source file and a Verilator configuration file to declare the
necessary public variables for using Verilator while integrating Verisocks. The
files are generated based on entries which have to be provided by the user in a
YAML configuration file.
Typically, the vsl-wizard command can simply be called with a YAML
configuration file as argument and then running make shall verilate the
source code and build the executable model:
vsl-wizard config.yaml
make
The generated Makefile considers the files generated by the scripts as targets
which depend on the configuration file (including the Makefile itself) such
that, if generated once, modifying the configuration file is automatically
detected and handled when running make.
Wizard-script usage
If properly installed with pip, an entry point is added in the path such that the wizard script can simply be evoked as follows:
usage: vsl-wizard [-h] [--build-dir BUILD_DIR]
[--templates-dir TEMPLATES_DIR] [--makefile-top MAKEFILE_TOP]
[--makefile MAKEFILE] [--testbench-file TESTBENCH_FILE]
[--variables-file VARIABLES_FILE] [--makefile-only] [--tb-only]
[--vlt-only] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] config
- config
Path to YAML configuration file
The content and structure of the YAML configuration file shall be as described below.
Important
All items in the configuration files which are not specifically indicated
as optional in the description above are mandatory! For items indicated
as (optional, ***), the *** stands for the equivalent value or
equivalent behavior if the item is not defined.
Note
All relative paths defined in the configuration file are considered to be relative to the location of the configuration file itself.
config:
prefix: <text> # Prefix name to be used for Verilator (will
# become the name of the executable)
top: <text> # Name of top module
verilog_src_files: # List of Verilog source files
- <path> # If required, this shall also comprise files
# with verilator configuration statements
verilog_inc_dirs: # (optional) List of Verilog include paths
- <path> # (to be processed with -I option by verilator)
verilator_arg_files: # (optional) List of Verilator arguments files
- <path> # (to be processed with -F option by verilator)
cpp_src_files: # (optional) List of C++ extra files
- <path> #
verisocks_root: <path> # Path to Verisocks root directory
verilator_path: <path> # Path to the verilator binary
verilator_root: <path> # Path to Verilator root
build_dir: <path> # (optional, .) Build directory. Default is the
# current working directory. This value can be
# overriden by the --build-dir command line
# option
use_tracing: <bool> # (optional, false) Enable tracing if true.
use_fst: <bool> # (optional, true) Use FST format for the traces file
use_timing: <bool> # (optional, true) If true, the sources are
# verilated with the timing option
log_level: <text> # (optional, info) Logging level
# [info, debug, warning, error, critical]
user_sim_info: <text> # (optional) User sim info
exec_version: <text> # (optional) Version of generated executable
exec_doc: <text> # (optional) Doc for generated executable help
bug_address: <text> # (optional) Address for bugs for generated
# executable help
sub_files: # (optional) List of other YAML files that will
- <path> # be merged (on one hierarchical level only!)
# with this file. For example, all variables
# could be listed in a separate YAML file that
# is shared by several possible configurations.
variables: # (optional) Public variables
clocks: # (optional) List of clock variables
- path: <text> # Clock path
name: <text> # (optional, path) Name/alias to be used for the variable
module: <text> # Name of the module in which is the variable
period: <number> # Clock period
unit: <text> # Time unit used for clock period [fs, ps, ns, us, ms, s]
duty_cycle: <number> # (optional, 0.5) Clock duty cycle, in ]0,1[
enable: <bool> # (optional, false) Clock is enabled
scalars: # (optional) List of scalar variables
- path: <text> # Variable path
name: <text> # (optional) Name/alias to be used for the variable
module: <text> # Name of the module in which is the variable
type: <text> # (optional, int) Variable type [int (integral type), real]
width: <number> # Width of the variable (optional if type: real)
arrays: # (optional) List of array variables
- path: <text> # Variable path
name: <text> # (optional, path) Name/alias to be used for the variable
module: <text> # Name of the module in which is the variable
type: <text> # (optional, int) Variable type [int (integral type), real]
width: <number> # Width of the variable
depth: <number> # Depth of the array
params: # (optional) List of parameter variables
- path: <text> # Parameter path
name: <text> # (optional, path) Name/alias to be used for the variable
module: <text> # Name of the module in which is the variable
type: <text> # (optional, int) Variable type [int (integral type), real]
width: <number> # Width of the variable
events: # (optional) List of events
- path: <text> # Event path
name: <text> # (optional, path) Name/alias to be used for the event
module: <text> # Name of the module in which is the event
Attention
From version 1.6.0, the type argument for variables in the YAML
configuration file needs only to be defined as either integral (int)
or real (real), int being the default if not defined. The
previous values uint8, uint16, uint32 and uint64 are still
supported but should be considered as deprecated.
Optional arguments
- -h, --help
Displays help content
- --build-dir <BUILD_DIR>, -b <BUILD_DIR>
Path to build directory (default: path provided in the config YAML file or current directory if not defined). If a different folder than the current working directory is defined, a folder <BUILD_DIR> is created with a Makefile <MAKEFILE> inside. Another “top-level” Makefile <MAKEFILE_TOP> is created in the current directory that will launch the one in the <BUILD_DIR> folder. This option can be typically useful to help avoid having a clutter of built object files in the current working directory, or to allow having different build directories for different config YAML files.
- --templates-dir <TEMPLATES_DIR>, -t <TEMPLATES_DIR>
Path to templates directory if alternatives templates shall be used instead of the default ones
- --makefile-top <MAKEFILE_TOP>
Rendered “top-level” makefile name (default:
Makefile). See description for--build-diroption.
- --makefile <MAKEFILE>
Rendered makefile name (default:
Makefile). This file will be rendered in <BUILD_DIR>.
- --testbench-file <TESTBENCH_FILE>
Rendered C++ testbench file (default:
test_main.cpp). This file will be rendered in <BUILD_DIR>.
- --variables-file <VARIABLES_FILE>
Rendered Verilator configuration file for public variables (default:
variables.vlt). This file will be rendered in <BUILD_DIR>.
- --makefile-only
Render makefile only (unless any other *-only option is being used). Depending on the configuration, both <MAKEFILE> and <MAKEFILE_TOP> shall be rendered.
- --tb-only
Render testbench file only (unless any other *-only option is being used)
- --vlt-only
Render variables file only (unless any other *-only option is being used)