Many people struggle to understand the ModelSim/QuestaSim VHDL simulator’s workflow. I think that’s unnecessary because the basic workflow isn’t hard to learn.
I regard the graphical user interface (GUI) as a front-end for the commands listed in this article. For example, when you click the Compile button in the ModelSim GUI, it runs the
vcom command back-end. The screenshot below shows the command echoed to the transcript window after we click the Compile button.
You can run the commands manually by typing them in the console from within the ModelSim, but you can also run them as standalone programs from a terminal without starting the GUI.
To run a command in batch mode, the program must be in the path of your shell. Some ModelSim installers update the path automatically, while on other systems, you must set it manually. The location may differ among installations, but in any case, it’s the subfolder that contains the
vcom executables you want to add to the path.
Everything starts with the
vlib command, which creates a design library. You’ve probably used libraries like
std in your VHDL code before. But the VHDL code you write must also go into a design library.
The default library in ModelSim is
work. If you create a new VHDL project in the GUI, it will automatically create it for you. Unless you specify a different location, each design library will appear as a folder in your project folder. For example, the compiled code belonging to the
work library usually resides in a subfolder named “work”.
Let’s create the
work library manually using
And delete it using the
vdel -all -lib work
This is the VHDL compiler command in ModelSim. It’s easy to compile; type
vcom followed by the path to your VHDL file:
Note that when you call
vcom without other arguments, the module ends up in the default
You can compile it into a different library by giving the ‘-work’ switch:
vcom -quiet -work my_lib .\my_module.vhd
(But then you first have to create
my_lib using the
vcom command has lots and lots of optional arguments that allow you to control the compilation rules in detail. Check out the ModelSim Reference Manual for a comprehensive list of all the options.
vmap tool, you can view and edit the mapping between the VHDL library name and the path to the compiled VHDL code in your file system (the folder you created with
vlib and compiled into using
To list all mappings, type
vmap without arguments:
That will print a list of library mappings from which you may recognize some names from. For example,
std. The standard libs are probably located in your ModelSim installation directory as they came with the simulator.
Other libraries like
work will probably map to the current working directory “./work”.
You can add or update a mapping by typing:
vmap lib_name path/to/the/lib/folder
Or you can delete a library mapping by typing:
vmap -del lib_name
Finally, you should know that
vmap modifies your modelsim.ini file. The location of modelsim.ini may vary. There’s one in the ModelSim installation directory, but it’s often not writable without admin privileges.
If you make the INI file writable,
vmap will happily modify it. But a better strategy is to use the system’s modelsim.ini file as a template and copy it to your local folder by using the special “-c” switch:
Then you can set an environment variable pointing to this file:
When you now call
vmap or any other command that relies on the INI file, it will use the local copy of modelsim.ini.
This is the command that starts the VHDL simulator (ModelSim). If you call
vsim from a shell without any arguments, the ModelSim GUI will open:
But you can avoid opening the GUI by appending the “-c” flag. The following command will drop you in a batch mode Tcl shell identical to the console found in the GUI:
Another useful switch is “-do”, which lets you specify a command that ModelSim will run when it opens. Here, we combine it with the “-c” flag to print “Hello World!” to the console and exit:
vsim -c -do "echo Hello World!; exit"
And, of course, you can simulate from the command line. Just give the library and entity of the testbench and combine it with the “-do” switch to start the simulation like this:
vsim -c my_lib.my_tb -do "run -all"
If you start a batch mode simulation from a script or a Makefile, you may want to return an exit code that you can pick up in your script. The exit command in ModelSim has a “-code” switch that lets you do this. Check out the video above for an example!
ModelSim Reference Manual PDF
If you want to dig deeper into these and other ModelSim commands, I recommend checking out the *ModelSim Reference Manual. It’s 455 pages long and lists all the possible ModelSim commands along with their optional switches.
* Or you can access it from within ModelSim by clicking: Help -> PDF Documentation -> Reference Manual. (Thanks to Rafael from the comment section for that tip!)
The VHDLwhiz Membership
I made this write-up now because I’m teaching it in this month’s tutorial series for the members. We’re setting up a script-based design flow for VHDL projects, and to do that, we have to understand how the ModelSim batch mode commands work.
If you’re interested in the membership and the monthly premium tutorials, you can read more about it here:
VHDLwhiz Membership - The FPGA learning experience that never ends
It’s only open for enrollment a few times each year. If you leave your email in the form at the bottom of the page, I will notify you the next time it accepts new members.
6 thoughts on “The ModelSim commands you need to know”
The ModelSim Manual you linked in this article is from an older version (10.1). When one installs a newer version from Intel Edition (say 2020.1), the help menu:
Help -> PDF Documentation -> Reference Manual
Thanks for the tip! I’ve updated the MODELSIM REFERENCE MANUAL PDF section of this blog post with that information.
You’re welcome. 🙂
Now I read my message again, sorry for the incomplete text.
I stumbled across a feature by accident, but cannot now replicate it!
I ran my simulation in QUESTA as usual, and in the CONSOLE window I printed out timestamp with debug statements. In the WAVE window I plotted signals of interest.
This is the feature that happened in one run: when I on a debug statement in the CONCOLE, the CURSOR in the WAVE window moved to corresponding point in waveform.
I don’t know how this happened, or how to switch it on again. Any help please?
If you print a time value in Questa/ModelSim like this:
Then you can click the printed time string in the console window (“100 ns” in this case):
And the cursor will jump to that point in the waveform if you have one open.
There’s no setting to enable it. Just go ahead and print a time value like in the example.
Thank you Jonas. Solved!
I was only doing a on the timestamp – you have to do to make the cursor follow.