All commands are in the namespace psi::sim, so either a fully qualified name (psi::sim::) must be used to access them or the namespace psi::sim must be imported (see example in README).
Beroe using the commands, type the following line in modelsim to import the commands into the golbal workspace:
namespace import psi::sim::*
- General Commands
- Configuration Commands
- Run Commands
Usage
init [-ghdl|-vivado]
Description
This command clears the PSI simulation environment. This means all libraries,
testbenches and files added are removed. As a result this command should be called
once in every script before using any other commands.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| -ghdl | Yes | Use GHDL instead of Modelsim (if the parameter is not given, Modelsim is used). For Modelsim, all commands must be executed in the Modelsim TCL shell. For GHDL, a standalone TCL shell (e.g. Active TCL) must be used |
| -vivado | Yes | Use Vivado Simulator instead of Modelsim (if the parameter is not given, Modelsim is used). All commands must be executed in the Vivado TCL shell. |
Usage
add_library <lib>
Description
Adds a library to the simultion project. At least one library must be specified
since there is no library to compile files into otherwise.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| lib | No | Name of the library to create |
Usage
add_sources <directory> <file> [-lib <lib>] [-tag <tag>] [-language <lang>] [-version <ver>] [-options <cmd>]
Description
Adds one or more source files. All source files added are compiled outomatically
in the order they are added (i.e. files must be added in compile order). Files
are not compiled when they are added but when the psi::sim::compile command is called.
Multiple files from the same directory can be added with one call of the command. This is also shown in the example code in the main README.md.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| directory | No | Directory the file(s) to add is/are in |
| file | No | Name of one or more files to add |
| lib | Yes | Library to compile the file into. If no library is given, the file is compiled into the last library added using the add_library command |
| tag | Yes | Tags are optional and can be use to selectively only compile files with the same tag. |
| lang | Yes | By default VHDL is assumed as language. By passing -lang verilog, verilog files can be integrated. However, the verilog support is only roughly tested. |
| ver | Yes | By default VHDL files are compiled with version 2008. If any other version is desired pass it as argument. 2008|2002|93|87| |
| cmd | Yes | Additional Modelsim commands can be passed as a string with the options switch. E.g. a macro for a Verilog manufacturer model -options +define+MacroName |
Usage
create_tb_run <tb> [<lib>]
Description
Create a testbench run. A testbench run consists of the testbench to execute (mandatory) and optionally
different arguments to pass to the simulation as well as scripts to execute before and after the run. If different
arguments are passed to the simulation, the scripts are ran only once befor/after all simulations with different arguments
and not before/after each simulation.
Note that the TB-run is only added to the project with the add_tb_run command.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| tb | No | Name of the testbench to execute |
| lib | Yes | Library the testbench is in. If no library is given, the last library added using the add_library is used. |
Usage
add_tb_run
Description
Add the last TB-run created using create_tb_run to the project. Optionally the TB run can be configured
between these two commands (e.g. using tb_run_add_arguments).
Note that it is possible to add multiple runs for the same testbench (e.g. with different pre- and post-scripts).
Parameters
Nonte
Usage
tb_run_add_arguments <arguments>
Description
This command allows defining additional arguments to pass to the vsim command of modelsim. Details can be found
in the modelsim documentation but one useful argument is the -gMyGeneric=MyValue option to set generics. If a list
of strings is passed, the simulation is executed once for each argument string. So this command is ideal to run a
testbench with different sets of generics.
The command must be called between the create_tb_run and the add_tb_run commands.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| arguments | No | String or list of strings to be passed to the simulation run(s) |
Usage
tb_run_add_time_limit <limit>
Description
Specify an end-time for a tb-run. Usually testbenches should stop on their own but in some cases (e.g. if Xilinx primitives do keep the simulation running and run -all is not workgin), it may be required to limit the runtime.
The command must be called between the create_tb_run and the add_tb_run commands.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| limit | No | Timelimit in the form "100 us" (the double-quotes are important) |
Usage
tb_run_add_pre_script <cmd> [<args>] [<path>]
Description
This command allows defining a script to be executed at the beginning of the TB-run.
The command must be called between the create_tb_run and the add_tb_run commands.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| cmd | No | Command to execute |
| args | Yes | Arguments to pass to the command (by default no arguments are passed) |
| path | Yes | Working directory to call the command from (by default the simulation directory is used) |
This command is equal to tb_run_add_pre_script but the script is executed after the simulations.
Usage
tb_run_skip [<simulator>]
Description
This command allows skipping the testbench for all simulators or only for one simulator. This can be used if bugs in a simulator tool lead to crashes.
The command must be called between the create_tb_run and the add_tb_run commands.
For skipping a run for multiple simulators, use teh form tb_run_skip "Vivado Ghdl".
Parameters
| Parameter | Optional | Description |
|---|---|---|
| simulator | Yes | Simulator to skip simulation for. Use **all**, **Modelsim** or **GHDL** |
Usage
compile_suppress <msgNos>
Description
This command allows to suppress one or more warning messages during compilation. For suppression of warning messages
during simulations, use run_suppress.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| msgNos | No | One or more message numbers to suppress. Multiple message numbers must be delimited using a comma. |
This command is equal to compile_suppress but the messages are suppressed during simulations instead of compilation.
Usage
clean_libraries [-all] [-lib <lib>]
Description
This command cleans either one specific libraries or all libraries. Cleaning means all contents are deleted,
so entities compiled earlier are no more visible.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| -all | Yes | All libraries in the project are cleaned. |
| lib | Yes | Name of one specific library to clean. Passing no library has the same effect as using -all (i.e. all libraries are cleaned). |
Usage
compile_files [-all] [-lib <lib>] [-tag <tag>] [-contains <str>] [-clean]
Description
This command compiles source files. Depending on the arguments, either all files or only a selection of
themare compiled. Optionally the All libraries can be cleaned prior to compilation.
Note that the command is also available as psi::sim::compile but this name is not exported to prevent name clashes with the compile command of modelsim. It is therefore recommended to only use compile_files.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| -all | Yes | Compile all source files. |
| -lib | Yes | Only compile files that belong to a given library. |
| -tag | Yes | Only compile files that have a given tag. This option can for example be used to only re-compile files that are related to a certain part of the project. |
| -contains | Yes | Only compile files if their path contains a given string |
| -clean | Yes | Clean all libraries before compiling. Note that this option should only be used together with the -all switch. |
Usage
run_tb [-all] [-lib <lib>] [-name <name>] [-contains <str>]
Description
This command executes the specified testbench runs.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| -all | Yes | Run all TB runs in the projet. |
| -lib | Yes | Only run TB runs for testbenches in a given library. |
| -name | Yes | Only execute TB runs for a testbench with a given name. |
| -contains | Yes | Only execute testbenches that contain a given string in their name |
Usage
run_check_errors <string>
Description
This command checks whether a given error string occurs in the transcript. If yes, simulations are regarded
as failed. If the string does not occur, simulations are regarded as successul.
It is recommended to use a very distinctive error pattern (e.g. "###ERROR###"). If a less distinctive pattern such as "Error" is used, there is a probability that the pattern occurs in messages that are not errors (e.g. "Checking Correct Operation for zero Position Error").
Note that all libraries use the error pattern ###ERROR###.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| str | No | Error string to search for |
Usage
launch_tb -contains <str> [-argidx <index>] [-wave [<file>]] [-show]
Description This command launches the specified TB run but it does not execute it (without the -wave and -show options used). Instead it stops after launching, so the user can execute the simulation interactively and view the waveform. So this command is intended for interactive debugging.
The user can optionally choose to use a specific set of testbench arguments (see tb_run_add_arguments) by using the -argidx option. If the option is not used, the testbench is started with the default generics from the source code.
Parameters
| Parameter | Optional | Description |
|---|---|---|
| -contains | No | Execute only the first testbench that contains the given string in its name |
| -argidx | Yes | Index of the TB arguments to use (see [tb_run_add_arguments](#tb_run_add_arguments)). Index is zero based (i.e. passing 0 leads to the first argument set being used). If this option is omitted, the testbench is started with its default arguments as given in the source code. |
| -wave | Yes | Modelsim: Optionally a do-file can be passed for a desired waveform view. In case -wave is passed without argument, all signals are added to the waveform, the simulation is run and the zoom is set to the complete run. GHDL: When executing this option in GHDL, a vcd file is generated with the naming pattern .vcd. The parameter is not implemented in GHDL. |
| -show | Yes | GTKwave is opened (forked) with the generated vcd file. Only implemented in GHDL. |
GHDL/GTK Workflow
- Execute the first run with -wave and -show options
- A gtkwave window opens -> forked to keep tclsh interaction active
- Rerun the testbench in the tclsh without the -show option
- Reload the waveform in the gtkwave menu: File -> Reload Waveform
- Optional: Run with different -argidx to compare different waveforms