The ModelSim commands you need to know

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 vsim and vcom executables you want to add to the path.

vlib

Everything starts with the vlib command, which creates a design library. You’ve probably used libraries like ieee or 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 vlib:

vlib work

And delete it using the vdel command:

vdel -all -lib work

vcom

This is the VHDL compiler command in ModelSim. It’s easy to compile; type vcom followed by the path to your VHDL file:

vcom .\my_module.vhd

Note that when you call vcom without other arguments, the module ends up in the default work library.

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 vlib command)

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

Using the 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 vcom).

To list all mappings, type vmap without arguments:

vmap

That will print a list of library mappings from which you may recognize some names from. For example, ieee and 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:

vmap -c

Then you can set an environment variable pointing to this file:

set MODELSIM=<project_dir>/modelsim.ini

When you now call vmap or any other command that relies on the INI file, it will use the local copy of modelsim.ini.

vsim

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:

vsim

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:

vsim -c

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.