General Grievous :)
An EDA simulator wrapper script of Cadence Xcelium, Synopsys VCS, etc.
Use one line command to call different digital simulators in short.
An example is to start a simulation with a command like 'python3 grievous.py -t test0'.
Follow MIT license.
Nowadays, in digital design and verification team of an integrated circuit (IC) company,
a common script of invoking different simulators is used normally.
The script is based on perl, python or makefile in different companies.
The scirpt in this repo is programmed by python3.
With the help of some configuration text files and global variables,
the script creates simulation folders, compile scripts, and simulate scripts,
then runs them automatically.
Different engineers are easily to share and debug simulation results in the team,
and easily to reproduce a failed simulation if they are using the same script.
Both single simulation and regression are supported.
Coverage is also collected in need,
and the curve of coverage percentage of daily regression is generated by calling gnuplot.
Support to sumbit jobs to LSF system or current host.
Support UVM testbench and verilog-only testbench.
For verification engineers, an UVM based simulation environment is easily to be build.
For design engineers who are not familiar with UVM,
a verilog or systemverilog based simulation environment is also supported.
TBA
| Argument | Description |
|---|---|
| --debug | Print more message. For debug only. |
| -h | Print help message of the script. Without start a simulation. |
| -t [test_name] | Specify the name of a test. It's used to find a file which name is [test_name].sv, and the [test_name] is passed to simulatior as +UVM_TESTNAME=[test_name]. So, make sure the file name and uvm_test name are same with [test_name]. Specify more than one test will start a regression. For example, '-t test0 -t test1' is workable. |
| -r [regression_list_file] | Sepcify a file of regression test list. See an example file in below. |
| -g [regression_group_name] | Sepcify a group name in regression list file. More than one group can be selected. For example, using '-g A -g B' in the same command line will select two groups in the list. |
| -uvm | Enable the compilation of UVM packages. By default, UVM packages are compiled. |
| -nouvm | Disable the compilation of UVM packages. |
| -c | Clean existing simulation folder. Without this arguments, the compile stage keeps incremental compilation if simulation folder is reused. |
| -s [seed] | Specify the seed of a simulation. The seed will passed to simulators. If seed isn't specified, the script generates a random seed in background. |
| -w [wave_type] | Dump signals to waveform files. [wave_type] can be ommitted, the default waveform type of Cadence Xceilum is .shm, and the default type of Synopsys VCS is fsdb. Wave type can also be specified in command line, it supports [-w shm, -w vcd, -w fsdb, -w vpd] for now. The signals and hierachies are specified in a user-defined file. |
| -wall [wave_type] | Dump all signals in all hierachy into waveform files. |
| -atm | Print extra message in simulation. Extra message includs folder name, command and system time. It's useful infomation when the simulation runs for days, weeks, or even months. |
| -noatm | Disable extra message printed. Note that the extra message is enabled by default in a single simulation. |
| -input [tcl_file] | Specify a tcl file and pass it to simulator. Pass to Cadence Xcelium: 'xrun -input [tcl_file] ...' |
| -b [block_name] | Specify block name for block level verification. Do NOT use this argument if it's a TOP level verification. The [block_name] should be the folder name of a block level design. |
| -dv[\d*] | Means -dv, -dv0, -dv1, or -dv2..., specify another dv folder as default. If the dv folder name is 'dv', -dv can be ommitted. |
| -localdv[\d*] | Means -localdv, -localdv0, -localdv1, or -localdv2..., specify another dv folder as default. LocalDV is a temprary DV environment, which is assumed to be a non-UVM environment which is used by design engineers. |
| -rtl | Pre simulation with RTL only. By default, it's a pre simulation. |
| -gate | Post simulation with gate level netlist. |
| -fpga | Simualtion for FPGA use. |
| -cosim | Not support yet. |
| -fault | Not support yet. |
| -tfile [tfile] | Specify timing file '.tfile'. Multiple tfile files can be specified by calling '-tfile [tfile]' multiple times. |
| -lsf | Calling 'bsub'. By default, bsub is called. But if LSF is not installed, use '-nolsf' in command line. |
| -nolsf | Do not call 'bsub'. |
| -interactivelsf | Calling 'bsub -I' for interactive mode of LSF. |
| -nointeractivelsf | Do not use '-I' of bsub command. By default, a single simulation use 'bsub -I ...' to submit job to LSF. |
| -jname [job_queue_name] | Specify job queue name of bjobs. |
| -rcn [number] | Specify compile repeat times. If compile fails, the script re-compiles database, by default, by 3 times. |
| -sim_root [folder_path] | Specify a folder that all the simulation folders are created under that folder. By default, the folder is defined in global variable 'SIM_ROOT'. |
| -d [folder_path] | Specify a folder to run simulation, instead of creating one automatically. |
| -repeat [number] | Run a simulation or regression for [number] times. For example, to run a test for 10 times, use 'python3 grievous.py -t test0 -repeat 10'. |
| -append [string] | For generated folder, its name is the test name. In order to distinguish the test from another run, append something to the folder name. For example: [test_name]_[string] is the new name of simulation folder. |
| -setup [another_config_file] | Specify another configuration file, instead of using the default one 'sim.setup'. |
| -max [number] | Specify the maxium number of parallel running jobs in regression. By default, the max number is 10. It's useful in regression when computer resoure is limited. |
| -qc [number] | Simulation quits when the count of error is larger than [number]. |
| -m [host_name] | Specify the host or hosts where the jobs are submitted in LSF. |
| -inf | Not support yet. |
| -ext_lsf_opt "string" | Pass some options to bsub from command line. Users can also specify options to bsub from configuration files. |
| -ext_comp_opt "string" | Pass some options to simulator at compilation stage. Users can also specify options to bsub from configuration files. |
| -ext_sim_opt "string" | Pass some options to simulator at simulation stage. Users can also specify options to bsub from configuration files. |
| -ext_dbg_opt "string" | Pass some options to Cadence Simvision, Synopsys Verdi. Users can also specify options to bsub from configuration files. |
| -ext_opt "string" | Pass some options to simulators, at both compilation and simulation stages. Users can also specify options to bsub from configuration files. |
| -co | Compile but not simulate. |
| -gs | Generate simulation folder and scripts, but do NOT start compile and simulate. |
| -cov | Enable coverage collection. |
| -cm | For regression, merge the coverage of every tests together. |
| -nocov | Disable coverage collection, higher priority than '-cov'. |
| -refine [refine_file_name] | Specify refine file used in coverage collection and merge. |
| -gui | Run simulation in gui mode. |
| -nc | Use Cadence Xcelium as the simulator. The default simulator is set to Xcelium. |
| -vcs | Use Synopsys VCS as the simulator. |
| -simtmp | For Cadence Xcelium, a user-defined folder can be set as simulation intermedia folder. See more details in user guide of Xcelium. |
| +[options] | Any options with leading '+' will be passed to simulator directly. |
| -[custom_switch] [value] | Enable a custom switch, and give a value of it. [value] is not necessary. |
| --[custom_switch] | Disable a custom switch. If a custom swithc is default on in configuration file. It's also can be disabled from command line. |
TBA
# project.cshrc
setenv PRJ_NAME [project_name]
setenv PRJ_ROOT `realpath $argv[1]`
setenv DV_ROOT $PRJ_ROOT/dv
setenv SIM_ROOT $PRJ_ROOT/sim
The default name of configuration file is 'sim.setup'.
For block level or top level verification, a default 'sim.setup' should be created by user:
$DESIGN_ROOT/[block_name]/dv/sim.setup
$DV_ROOT/sim.setup
In configuration files, each line is a key-value pair,
which guides the script to run simulation.
For example, 'DESIGN_TOP: example' is used to tell the script the top module name.
| KeyWord | Value |
|---|---|
| SOURCE_CFG | Specify a child configuration file. In order to reuse some common settings. |
| CUSTOM_SWITCH | Add a new custom switch which can be used in command line to enable to disable something. See relate chapter in this README file. |
| DESIGN_TOP | Specify the module name of top design. Which is the DUT in the context. |
| TB_TOP | Specify the module name of testbench. |
| INC_DIR | Include folders. Pass to simulator '+incdir+[path]' |
| DESIGN_FILES | Specify the file-list file or design file. |
| DV_FILES | Specify the file-list file or dv file. |
| LIB_FILES | Specify library file-list file or single files. |
| MODEL_FILES | Specify models or modle list. |
| TIME_SCALE | Specify time-scale of simulation. |
| UVM_TIMEOUT | Set uvm_timeout time. |
| MAX_QUIT_COUNT | Set max_quit_count in simulation. |
| COMPILE_REPEAT_NUMBERS | Repeat times when compile fails. |
| BLK_ROOT | Root folder of block. Useful in block level verification only. |
| BLK_DESIGN_ROOT | Root folder of block design. Useful in block level verification only. |
| BLK_DV_ROOT | Root foloder of block DV environment. Useful in block level verification only. |
| TCL_FILES | Pass tcl files to simulator using '-input' option of simulator. |
| TFILES | Pass tfiles to simulator in gate level simulation. |
| BSUB_OPT | Options passed to 'bsub' command. |
| EXT_COMP_OPT | Options passed to simulator in compilation stage. |
| EXT_SIM_OPT | Options passed to simulator in simulation stage. |
| EXT_OPT | Options passed to simulator in both compilation and simulation stages. |
| EXT_DBG_OPT | Options passed to Cadence Simvision and Synopsys Verdi. |
| PRE_COMP_CMD | Some commands executed before compilation starts. |
| POST_COMP_CMD | Some commands executed after compilation is done, but before simulation starts. |
| PRE_SIM_CMD | Some commands executed before simulation starts, but after compilation is done. Such like to move data file to simulation folder. |
| POST_SIM_CMD | Some commands executed after simulation is done. Such like some post text file processing. |
| COV_TYPE | Coverage type for coverage collection. |
| COV_FILES | Specify setting files for coverage collection. |
| COV_DUT | Specify one or more DUTs for collecting coverage. |
| COV_REFINE_FILES | Specify refine files for coverage collections and merge. |
| WARN_STR | User-define string which is used to parse log files to treated as warning message. |
| IGNORE_WARN_STR | User-define string which is used to parse log files to treated as NOT warning message. |
| ERR_STR | User-define string which is used to parse log files to treated as error message. |
| IGNORE_ERR_STR | User-define string which is used to parse log files to treated as NOT error message. |
| OTHER_SIM_LOG_FILES | Sepcify some other log files which will be parsed by the scripts. |
DESIGN_TOP: example
TB_TOP: tb_top
DESIGN_FILES: -f design.f
DV_FILES: -f dv.f
CUSTOM_SWITCH: cs0, default:ON, append:ON
CUSTOM_SWITCH: cs1, default:ON, append:OFF
cs0_PRE_COMP_CMD: echo "cs0_pre_comp_cmd"
!cs0_PRE_COMP_CMD: echo "not cs0_pre_comp_cmd"
cs0_POST_COMP_CMD: echo "cs0_pre_comp_cmd"
!cs0_POST_COMP_CMD: echo "not cs0_pre_comp_cmd"
cs0_PRE_COMP_CMD: echo "cs0_pre_comp_cmd 1"
!cs0_PRE_COMP_CMD: echo "not cs0_pre_comp_cmd 1"
cs0_POST_COMP_CMD: echo "cs0_pre_comp_cmd 1"
!cs0_POST_COMP_CMD: echo "not cs0_pre_comp_cmd 1"
cs0_PRE_SIM_CMD: echo "cs0_pre_sim_cmd"
!cs0_PRE_SIM_CMD: echo "not cs0_pre_sim_cmd"
cs0_POST_SIM_CMD: echo "cs0_pre_sim_cmd"
!cs0_POST_SIM_CMD: echo "not cs0_pre_sim_cmd"
cs0_cs1_PRE_COMP_CMD: echo "cs0_cs1_PRE_COMP_CMD"
cs0_!cs1_PRE_COMP_CMD: echo "cs0_!cs1_PRE_COMP_CMD"
!cs0_!cs1_PRE_COMP_CMD: echo "!cs0_!cs1_PRE_COMP_CMD"
!cs0_cs1_PRE_COMP_CMD: echo "!cs0_cs1_PRE_COMP_CMD"
To make the script more robust,
users can define new switches which can be used in command line.
Custom switch is added in configuration files as the value of 'CUSTOM_SWITCH' keyword.
The line
CUSTOM_SWITCH: cs0, default:ON, append:ON
means, a custom switch 'cs0' is added, it's enabled by default,
and it will append '_cs0' to the simulation folder name.
Use regexp to have more flexbility to keywords in configuration files.
For example, refer to the above example of configuration file,
cs0 and cs1 are user added custom switches.
cs0_ and cs1_ are added to ANY keywords in configuration files,
some have '!' in front of custom switch which means negtive selections.
To enable cs0 custom swith in command line, use '-cs0'
> python3 grievous.py -t test0 -cs0
as cs0 is enabled by default in configuration file, -cs0 can be ommitted.
To disable cs0 custom switch in command line, use '--cs0'
> python3 grievous.py -t test0 --cs0
To enable cs0, but disable cs1 in command line
> python3 grievous.py -t test0 -cs0 --cs1
To disable cs0, but enable cs1 in command line
> python3 grievous.py -t test0 --cs0 -cs1
The line
cs0_!cs1_PRE_COMP_CMD: echo "cs0_!cs1_PRE_COMP_CMD"
is only functional when cs0 is enable and cs1 is disable,
aka 'python3 grievous.py -cs0 --cs1 ...' or 'python3 grievous.py --cs1 ...'.
Note: cs0 is default on, so -cs0 is not necessary in this context.
# full.lst
test0 : A=1 B=2 GroupX=3
test1 -seed 2 : A=1
test3 -nocov : B=2
Group name can be any character or word.
'-seed 2' and '-nocov' are options for test1 and test3, respectively, not affect test0.
'python3 grievous.py -r full.lst -g A -g B -cov -cm' will run a regression, in which, test0 run 3 times,
test1 run once but with 2 as seed,
and test3 run twice.
Only collect the coverage of test0 and test1, as '-nocov' is used in the line of test3.
Note: Failed tests will not be collected coverage.
Note: For daily regression, gnuplot is invoked to plot curve of coverage info.
TBA
xeroncn+validfox.python3 [email protected]