A Short Intro to ModelSim Verilog Simulator

This is a beginner's tutorial to get you off the ground from scratch. Detailed tutorials on various aspects of Modelsim can be found here: /afs/ece/support/mgc/mgc.release/modelsim-se_2020.1/modeltech/docs/pdfdocs/modelsim_se_tut.pdf complete with examples.

This assumes you are running bash on an ECE Linux machine. (You can determine which shell you are using by typing echo $SHELL into your Unix command prompt. If you are not running bash, you can type bash into the command prompt to start a bash shell. If you are running a different shell, I assume you know enough to adapt the instructions to your favorite shell.)

Type this command

export PATH=/afs/ece.cmu.edu/support/mgc/mgc.release/modelsim-se_2020.1/modeltech/linux_x86_64:$PATH

(PATH tells your shell where to find the executables for ModelSim.)

Next type

export LM_LICENSE_FILE=/afs/ece/support/mgc/share/image/usr/local/mgc/license.dat:$LM_LICENSE_FILE

LM_LICENSE_FILE tells ModelSim where to find its license file.

(The above should work regardless of how your environment is initially set up. If you are familiar with the Unix shell environment, you can figure out how to properly add the above to your .bashrc so you don't have to type them each time.)

If you messed up on the first command, which vsim will report there is no vsim in your path. If you messsed up on the second command, vsim will not run in the steps below.

ModelSim requires a “library directory” to store information about your project. In your project directory (where the simulation project .v files are), type

vlib work

This creates a directory called work needed by Modelsim. If you delete this directory, you will need to create it again before running any compilations.

Next from the project directory, type

vlog «list of verilog files»

This might look like (try example.zip)

vlog op.v recip.v top.v

Or, if all of the .v files are pertinent, just type

vlog *.v

This compiles your .v files for simulation. Note that recent versions of Modelsim are geared towards performance and will by default perform optimizations which might limit visibility of the design simulation results you can view¹⁾. Look ahead at the Debugging section for more details.

If there were no errors, the compilation should list the modules compiled and point out the top-level modules (ones not included by any other modules). If the compilation failed with ERR messages, you will need to revise your .v files to address the complaints and recompile. It is a good practice to also look for WARN messages and resolve those as well.

To run ModelSim, from the project directory, type:

vsim «top-level module name»

For example,

vsim top

if top is the top level module in your design. In an X-ready environment, this should bring up the simulator main window. You can start the simulation by typing in the simulator command window:

run -all

The simulation will run until it encounters a $stop or $finish command in your .v files. If you are using only $display and $print for debugging, this is all the ModelSim you need know. In fact, if this is all you do, you can just type

vsim -c -do “run -all” top

(Note: in the above, if you cut-and-paste, you need to retype with straight quotation marks.)

at the Unix command prompt to run vsim in text mode (without X).

Most likely, you'll run into bugs and need to muck around with the waveform viewer and debugger.

As was hinted earlier, Modelsim performs aggressive optimizations by default. To debug you need to make sure that the optimizer is aware of the level of debug information it needs to retain. There are a couple of ways to go about this:

• Global Optimization: Add the option -voptargs=“+acc” to the vsim command. This enables full visibility into every aspect of the design. The command might look like: vsim –voptargs=“+acc” <top_level>
• File Level Optimization: This is a more powerful option which lets you control optimization of specific HDL files and hence modules. Add the option +acc to the vlog command for the files you want to have view into. For example if you wanted to look into a module named top in top.v you'd use the following command just for that file: vlog +acc top.v. You can compile the rest of the files as usual.

Here's a full list of possible options other than just using +acc which can also be obtained by running the command vlog -help Debug

+acc[=<spec>]                   <spec> consists of one or more of the following
                                letter codes:
                                m (module, program, and interface instances)
                                n (nets)
                                p (ports)
                                r (variables and parameters)
                                t (task and function scopes)

These let you finely control how much view you get into your design and tradeoff with simulation performance.

ModelSim has a great GUI with which to debug the design. Most of this you will have to discover for yourself. Here's a quick tutorial.

• To bring up an object window: View→Debug Windows→Object

• To bring up a waveform window: View→Debug Windows→Waves.
  You can add signals to the waveform window by dragging and dropping things from the object window into the waveform window (left panel).

• To run the simulation (from the Simulate→Run pull-down menu):
  • Run - All: Run until the next breakpoint or until a $finish or $stop, or forever.
  • Run - Continue: Continue running after a breakpoint.
  • Run - 100ns: Run for 100ns of simulation time.

• If you find a bug, you can edit, recompile and restart the simulation, without quitting the ModelSim executable. Just type the same compilation command into the bash shell and then type restart the simulation inside ModelSim. You do not need to restart ModelSim after recompiling.

• Virtually all click-able things can be accessed with keyboard commands. For power users with too much time on their hands, ModelSim can be scripted using TCL.

This tutorial should have set you up for the most minimum of functionalities to run a basic Verilog simulation project. Reading documentations will help you access the more powerful debugging and simulation features. You can google online for more thorough, more advanced tutorials. You can also try googling a specific question phrase; it is amazing how much expert help is just out there.