xmodel: Simulation Launcher
Overview
The XMODEL Simulation Launcher provides a consistent user interface to launch XMODEL simulations, regardless of the underlying SystemVerilog simulator being used. It also provides the on-line documentation on the XMODEL primitives.
Basic Command
The minimal way of running an XMODEL simulation is to type the following command on the command-line prompt:
unix> xmodel <source_file1> <source_file2> … --top <top_module>
The xmodel utility expects a list of source files separated by spaces and the name of the top module name.
To specify the simulation time, use --simtime option. For instance, to run the simulation for 100ns:
unix> xmodel file1.sv file2.sv --top my_top --simtime 100ns
The xmodel utility provides the -f option, with which you can define the commands in a file and pass its filename to the utility:
unix> xmodel -f run.f
where the file named run.f may contain:
file1.sv file2.sv --top my_top --simtime 100ns
The next subsection describes a full list of available options.
Available Options
Typing the command xmodel -h on the UNIX command-line prompt displays all the available options for the xmodel utility.
unix> xmodel -h usage: xmodel [-h [TOPIC]] [--version] [--sim SIMULATOR] [--top TOPMODULE] [--time SIMTIME] [--define MACRO] [--timescale TIMESCALE/PRECISION] [--file FILENAME] [--logfile FILENAME] [--command] [--clean] [--force] [--elab-option OPTIONS [OPTIONS ...] --] [--sim-option OPTIONS [OPTIONS ...] --] [filename [filename ...]] XMODEL simulation launcher. …
Descriptions on the selected options are as follow:
Simulation control options:
--top TOPMODULE: specifies the name of the top-level module.--time SIMTIME,--simtime SIMTIME, or--runtime SIMTIME: specifies the simulation run time.--timescale TIMESCALE/PRECISION: specifies the simulation timescale and precision (e.g. 1ps/1ps).--sim SIMULATORor--simulator SIMULATOR: specifies the SystemVerilog simulator to be used. Possible values are vcs, modelsim, or ncverilog.--stat: enables statistical simulation.--force: forces simulation without recycling the previous simulation results.
Options common to most SystemVerilog simulators:
-D MACROor--define MACRO: defines macros.-f FILENAMEor--file FILENAME: specifies a file containing command-line arguments.-l FILENAMEor--logfile FILENAME: defines the name of the simulation log file.
SystemVerilog simulator-specific options:
--elab-option OPTION1 OPTION2 … --: defines the options passed to the SystemVerilog elaborator (e.g. vcs).--sim-option OPTION1 OPTION2 … --: defines the options passed to the SystemVerilog simulator (e.g. simv).--64bit: forces simulation in 64-bit mode.--32bit: forces simulation in 32-bit mode.
Miscellaneous options:
--help TOPIC: displays help messages on the topic.--version: shows version information.--command: shows the shell commands to launch the simulation.--clean: cleans up all the simulation result files.
Output Results
A typical XMODEL simulation generates a set of files as a result. First, it will generate files which are the results of running the underlying SystemVerilog simulator. For instance, using the Synopsys VCS simulator would create files and folders such as simv, simv.daidir, csrc, etc.
In addition, a typical XMODEL simulation generates a waveform file (e.g. xmodel.jez) and a log file (e.g. xmodel.log).
The waveform file in JEZ format can be viewed using the XWAVE Waveform Viewer. The log file is in the ASCII format, storing standard-output stream from the SystemVerilog simulator. Users may find it useful to open the log file in case the simulation has ended in error.
The xmodel simulator launcher provides a convenient option -clean to delete all the result files when necessary. Simply, type the command as below to clean up the result files:
unix> xmodel --clean
Recycling Output Results
The XMODEL Simulation Launcher recycles the previous simulation results whenever it is possible. In other words, the launcher application will quit immediately without running the simulation.
The XMODEL Simulation Launcher determines whether to run a new simulation or not by examining the log file (e.g. xmodel.log, if the log file’s name is not redefined using the -l option). If none of the source files and simulation parameter values has been changed since the last simulation, the XMODEL Simulation Launcher deems the simulation redundant and skips it.
This feature is convenient when running a long sweep of simulations. Even when the sweep halts in the middle, one can easily resume the sweep simply by re-running the sweeping script. The unit simulation runs that were already completed in the previous sweep will automatically be skipped.
However, there might be cases when this recycling behavior is undesired. In that case, use the -force option to force the simulation at all times.
Accessing On-line Documentation
All the available options of the XMODEL Simulation Launcher can be viewed on-line simply by using the -h option in the command-line:
unix> xmodel -h
Also, as explained in Section 3.3, one can access the on-line documentation on XMODEL primitives by giving a topic to the -h option:
unix> xmodel -h <TOPIC>
For instance, the following command gives a list of function primitives:
unix> xmodel -h function
And the following command gives a description on the filter primitive:
unix> xmodel -h filter
User Customization
The XMODEL Simulation Launcher issues the appropriate commands to run the simulation using the user-specified SystemVerilog simulator, such as Synopsys VCS, MentorGraphics ModelSim, or Cadence NC-Verilog.
However, it may be necessary to customize the behavior of xmodel. For instance, one may want to pass different options to the SystemVerilog simulators or change the default simulation time or timescale/precision values when they are not explicitly specified.
One can modify the default behavior of the XMODEL Simulation Launcher by defining his/her own configuration file. One may browse the available options and their default values from the default configuration file located in $XMODEL_HOME/etc/default_config.py.
It is recommended that the users do not edit this file directly, since all the customizations would be lost when a new version of XMODEL is installed. Instead, make a new configuration file that starts by importing the default_config.py and overrides the selected options only. For instance, the example below demonstrates how to override the command names for executing NC-Verilog simulations:
#!/usr/bin/env xmodelpy """ CONFIG my_config.py A custom configuration file for my own use. """ # inherit all the default settings in the default_config.py from default_config import * # override the command names for executing NC-Verilog sim_cmd['ncverilog']['ncverilog'] = 'ncverilog_bsub' sim_cmd['ncverilog']['ncelab'] = 'ncverilog_bsub' sim_cmd['ncverilog']['ncsim'] = 'ncverilog_bsub'
Once a custom configuration file is ready, one can tell xmodel its location by defining the $XMODEL_CONFIG environment variable, for instance:
unix> setenv XMODEL_CONFIG ~/my_config.py
on csh-like shells. On bash shells:
unix> export XMODEL_CONFIG=~/my_config.py
Please note that the current format of the configuration file is subject to change without notice.