Mentor Graphics ModelSim EE (Version 5.2e)

New Auburn Users

On a SUN workstation, run the user-setup program, select the eda (electronic design automation) menu, and then click on the Mentor entry to select it. Then log out and log back in for this to become effective, setting up the paths and environment variables needed to run the various digital, analog, MCM, circuit board, and IC design tools from Mentor Graphics.

Preparing VHDL/Verilog Models for Simulation

The Project Directory

Create a working project directory, into which you will place your VHDL and Verilog source files and simulation command files.

Example: My working directory is ~/nelson/ee530

Your Personal Design Library

The VHDL and Verilog compilers place all compiled files and related data into a special design library directory, named "work", which should be located within your project directory. The ModelSim EE simulator will automatically retrieve all models from this directory.

• Go to your project directory and create the design library with the vlib command, and map the library name to the directory as follows:

  cd ee530
  vlib work
  vmap work work

• After VHDL/Verilog models have been created and compiled, the directory structure will be as follows:

                            ~/nelson
                               |
                            /ee530
              _________________|___________________
             |            |                        |
         model1.vhd   model2.vlg   ....         /work
                                                   |
                                           compiled models
  

• List the design units in your library with the ModelSim EE Directory command:

  vdir

• Delete design units from your design library with the ModelSim EE Delete command:
  • vdel m1 - delete entity m1 and all of its architectures
  • vdel m1 a1 - delete only architecture a1 of m1

  NEVER use UNIX commands or the Windows File Manager to access, move, copy, etc., any file within design library directory "work"!! Always use the vdel command.

Creating VHDL models:

Use a text editor to create your VHDL models and place them in your working project directory. For each VHDL design unit, put its entity and architecture in a single file and use the entity name as the file name, with extension ".vhd".

Example:

VHDL entity statement: entity model1 is ...
Use file name: model1.vhd

Compiling VHDL models:

Compile each VHDL design unit with the vcom command in one of the following ways:

• vcom model1.vhd
• vcom -source model1.vhd

The second format displays a source line with each error message, while the first displays error messages only. The compiled model is automatically placed in your working library.

NOTE: A "make file" can be generated for your working library with the command: vmake. Executing this make file causes all out-of-date VHDL files in your library to be recompiled.

Using the ModelSim EE Simulator

Overview of VHDL Model Simulation

A modeled design unit is tested and evaluated by defining test stimuli to be applied to its inputs, simulating the operation of the unit as these stimuli are applied, and capturing values of outputs and other signals within the unit that can be examined to determine if the unit behaved properly.

The ModelSim EE simulator loads a compiled VHDL model, allows test stimuli (called "forces") to be defined, either interactively or via a "command file", and then simulates the operation of the design, displaying specified signals in list format and/or as timing diagram waveforms. Captured signal values may be examined within the simulator, or saved in files to be examined off-line. Any or all signals in a model may be captured and displayed. It is important to capture as much signal information as possible to simplify debugging of a model.

To debug a VHDL model, a user may interact with the simulator by defining "breakpoints", which stop simulation at selected VHDL statements within the model, at which time the user may examine signals and/or alter signal values. Simulation may then be resumed one VHDL statement at a time or continuously until the next breakpoint is reached.

As errors are located in a model, the VHDL source file may be edited, recompiled, and reloaded into the simulator. Simulation can then be repeated until desired results are obtained.

Typical simulation procedure:

1. Invoke the simulator and load the VHDL model.
2. Display the VHDL model by opening a Source Window.
3. Display signals in the model by opening a Signals Window.
4. Open a List Window to display captured signal values in tabular form during simulation, and/or a Wave Window to display signal values as logic analyzer waveforms.
5. Define input stimuli ("forces") for each input signal.
6. Run the simulation for the desired number of time units.
7. Study the simulation results in the List/Wave Window.
8. Save the List Window to a printable file.
9. Resimulate with new input stimuli, or correct and recompile the model and then repeat the simulation.

Invoking the Simulator

• Type Unix shell command vsim to produce the following Load Design Window.
  
  
  
  1. "Simulator Resolution": select the desired time unit ("ns" is the default).
  2. "Library" if not already listed as the default, select "work".
  3. "Design Unit": click on the top-level entity of the model to be simulated.
     If there is more than one architecture for the selected entity, click on the plus sign to the left of the entity name to display all available architectures, and then click on the one to be simulated.
  4. Click on the "Load" button to load the model.

  
  

• To save time, the Startup Window can be bypassed by including the top-level entity name on the UNIX command line:

  vsim adder

The ModelSim EE Simulator Main Window

Invoking the ModelSim EE simulator produces the Main Window, shown below. Simulation commands may be entered via the menu bar along the top of the window, by typing them at the prompt within the window, or by reading them from a command file. (A Command Summary is given at the end of this document.)



The menu bar contains pull-down menus and buttons to load models, to display VHDL structures and source code, to display signals and variables and their values during simulation, and to run and restart simulations.

• File pull-down menu:
  • Load New Design: Bring up a new Startup Window.
  • Restart: Restart the current simulation from time 0.
  • Save Transcript: Save a transcript of the Main Window to a text file.
  • Clear Transcript: Clear the Main Window.
  • Quit: Quit ModelSim and return to UNIX.
• Library pull-down menu: Access design libraries.
  • Browse Libraries: Browse all libraries associated with the design.
  • Create a New Library
  • View Library Contents: View all design units in a library.
• View pull-down menu: Open other simulator windows.
• Run pull-down menu: Run the simulation.
• Macro pull-down menu: Execute a "do" file (macro).
• Options pull-down menu: Set various vsim options.
  • Simulation options:
    • Default radix for signal display
    • Default run time
    • Maximum number of iterations, i.e. limit on number of "deltas" within a simulation time unit (to prevent oscillation).
    • Default force type
• Step button: Simulate one VHDL statement (if simulation is paused).
• Step Over button: Same as Step, but execute an entire VHDL function or procedure as a single statement.
• Run pull-down menu: Run the simulation for a designated amount of time:

  n time units: Simulate n time units.
  Time'High: Simulate a number of time units equal to the largest integer on the SUN.
  Continue: Resume execution of a paused simulation.

• Break button: Pause (break) a running simulation.

Displaying VHDL Models

While simulating and debugging a VHDL model, it is usually helpful to display the model hierarchy and VHDL statements in a Structure Window and a Source Window, respectively.

• A Source Window, illustrated below, displays VHDL source statements for the active design unit (the VHDL entity and architecture currently being simulated), with line numbers on the left and scroll bars to scan through the model. In this window, a breakpoint can be set for debugging by clicking on a statement line number, and signals can be selected to examine or change during simulation. The use of breakpoints for debugging is discussed later.
  
  
  
  
  • Open a Source Window from the Main Window menu bar: View>Source or by typing the command: view source.

  
  
  

• A Structure Window displays the structural hierarchy of a design (component instantiations, etc. at each level) as shown below.
  
  
  
  
  • Open a Structure Window from the Main Window menu bar (View>Structure) or by typing the command: view structure.
  • Each element in the design hierarchy is displayed as:

    instantiation_label:entity(architecture)

  • Clicking on a design unit name in the Structure Window selects it as the "current design unit" to be displayed in the Source Window. (The default is the topmost entity/architecture).
  • The hierarchy can be expanded by clicking on [+] or contracted by clicking on [-] to the left of a design unit name.

Displaying VHDL Signal Values

The purpose of simulation is to verify the correctness of a VHDL model. This is done by displaying the various signals within the model, applying stimuli to external input signals, observing signal values during simulation, and comparing observed values to expected values.

• The SIGNALS Window displays all signal names within the current region and their current simulated values. (The "current region" is selected via the Structure Window as described above).
  
  
  
  • Open a Signals Window from the Main Window menu bar (View>Signals) or by typing the command: view signals.
  • Expand composite signals to individual elements by clicking on [+] and contract by clicking on [-].
  • Click on a signal to "select" it and click on it again to deselect it.
  • The Signals Window provides the following useful pull-down menu functions:

    Edit > Select All - select all signals in the window.
    Edit > Unselect All - unselect all signals in the window.
    Edit > Force - force a specified value onto a preselected signal or a signal entered in the popup form.
    View > Wave - display selected, or all, signals in a Wave Window.
    View > List - display selected, or all, signals, in a List Window.
    

  
  
  

• The LIST Window displays a tabular listing of simulated values of selected signals, captured over a period of time. Each row represents a snapshot of signal values taken at the time listed in the left-most two columns.
  
  
  
  • Open a List Window from the Main Window or Signals Window menu bar (View>List), or type the command: view list.
    • For each signal to be captured and displayed, click on the signal name in the Signals Window to select it, and then from the Signals Window menu bar select: View > List > Selected signal, or type the command list signal-name.
    • To capture and display all signals displayed in the Signals Window, from the Signals Window menu bar select: View > List > Signals in region, or type the command list /*.
    • To capture and display all signals in your design, from the Signals Window menu bar select: View > List > Signals in design, or type the command list -r /*.
  • Simulation time is given in the designated time unit (default is ns) plus some number of VHDL "deltas" (infinitessimally small, non-zero time increments).
  • The format and/or contents of the List Window can be saved via the List Window menu bar.

    File>Write List (tabular): Saves the entire list window in an ASCII file that can be examined and/or printed.
    File>Save Format: Saves the list of signal names and their formats in a file that can be executed later as a command file to regenerate the List Window format.

    
    
    

  • The display format of the List Window can be altered via its Prop>Display Props pull-down menu, which produces the following form.
    
    • The Triggers tab: enable/disable lines at "delta" times, define a periodic "strobe" to trigger lines (instead of triggering on signal events), or define a triggering expression.
    • The Window Properties tab: suppress/enable display of full hierarchical signal name and limit the number of characters displayed.

    
    
    

  • Alter the format of a selected signal in the List Window via its Prop>Display Props pull-down menu, which produces the following form.
    
    
    The following properties can be changed for a selected signal in the List Window:
    • The display radix (binary, hex, decimal, etc.).A few decimal or hex digits may be more readable than many binary digits.
    • The width (number of columns) used to display the signal value (eliminate "white space").
    • Whether or not an event on that signal produces a new line (snapshot) of values.

  
  
  

• The WAVE Window displays values of selected signals, captured over a period of time, as logic-analyzer-type waveforms.
  
  
  • Open a Wave Window from the Main Window or Signals Window menu bar (View>Wave) or by typing the command: view wave.
  • The Wave Window menu bar has the following selections:
    • File>Write Postscript: Saves the entire Wave Window in a printable postscript file
    • File>Save Format: Saves the signal names and their formats in a file that can be reloaded later.
    • Zoom> Expand/contract the displayed waveforms
    • Cursor> Display a vertical "cursor", shown at time 66 in the above window, that can be moved to assist in examining signal values at a given time. Drag the cursor to a desired location by pointing to the box containing the time, holding down the left mouse button, and moving the mouse left or right.
    • Prop> Change display properties (see description above under List Window).
  • Scroll bars may be used to scroll the picture left/right and up/down.
  • Click on [+] to the left of a signal to expand to individual signals, and click on [-] to "un-expand"
    (An empty box indicates a one-bit signal)

Defining Test Input Stimuli (Forces)

A "force value" is a value-delay pair that defines a stimulus to be applied to a signal and the time at which it is to be applied. The time is expressed as a delay from the current simulation time. Multiple time-delay pairs may be specified with a single "force" command, and a pattern may be repeated if desired.

• Force commands may be typed in the main window or read from a command file. The format of a force command is as follows.

  force signal-name value1 time1, value2 time2, ... [-rep]

  If the optional -rep n is specified, the pattern is repeated with a period of n time units.

• Forces may also be specified via the "Force" button in the Signals Window.
  
  Examples: (Assume current time is T)

  Force signal "abc" to logic value '1' at time T+20:

  force abc 1 20

  • 
    Force "abc" to '0' at time T, '1' at T+20 and then '0' at T+40:

    force xyz 0 0, 1 20, 0 40

    
    Create a clock waveform on signal "clk" with period 40, with value '0' for the first half and '1' for the last half:

    force clk 0 0, 1 20 -rep 40

  
  

• Numeric force values can be expressed in any radix by prepending the prefix radix# to the number.

  Example: The decimal number 123 may be expressed as:

  • Decimal: 123 or 10#123
  • Hexadecimal: 16#7B
  • Binary: 2#1111011

  
  

• Logic states "Z" and "X" may only be written as part of a binary string.

  Example: To float a 32-bit data bus at time 25:

  force data ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 25

  
  

• A signal within a lower-level components of a hierarchical design is specified via its full "path name", which is similar to the path name of a UNIX file.

  Examples:

     clk             - signal clk in the current environment
     /clk            - signal clk in the top-level model
     /blk1/clk       - signal clk within block blk1
     /blk1/blk2/clk  - signal clk within block blk2 of block blk1
  

  
  

• Force values are delayed from the "current time", allowing a simulation to be run in multiple steps.
  
  Example Procedure:
  1. Define force values for step 1, relative to time 0.
  2. Run the simulation for T1 time units (time is now T1).
  3. Define force values for step 2, relative to time T1.
  4. Run the simulation for T2 time units (time is now T1+T2).
     etc.

Running the Simulation

A simulation may be run for a designated amount of time, run until there are no more scheduled events, or run until a breakpoint is reached.

• Run the simulation for a designated amount of time:
  • From the Main Window menu bar, select Run > n time units, or type the command run n, where n is the number of time units to be simulated.
  • From the Main Window menu bar, select Run > Time'High, which runs for a number of time units equal to the largest integer on the SUN.
• Simulation can be paused by clicking on the Main Window Break button or by setting breakpoints. (Breakpoints are discussed below under "Debugging VHDL Models".)
• While simulation is paused at a break point, single-step operation can be used for debugging.
  • Main Window Step button: Simulate one VHDL statement (if simulation stopped). (Or type the step command.)
  • Main Window Step Over button: Same as Step, but treat an entire VHDL function or procedure as a single statement. (Or type the step over command.)
  • To resume continuous simulation, f rom the Main Window menu bar, select Continue, or type the command continue.

Altering and/or Resimulating a VHDL Model

After performing a simulation, it may be desirable to resimulate the model with different input stimuli, or to resimulate the model after making corrections to it.

Resimulating the Same Model:

Simulation time may be reset to 0 and the model resimulated. However, all force statements must be reentered or else read from a command file.

• From the Main Window menu bar select: File>Restart design, or type the command restart.
• Restarting causes all signal values to be erased, but all window formats will be retained.

Correcting and Resimulating a Model:

If an error is found in a model, correct it, recompile it, and then resimulate.

• Edit the VHDL source file to correct the model. If desired, you can invoke your default editor by typing the command edit source. (This uses your default UNIX editor as defined by the EDITOR environment variable.)
• Recompile the corrected design unit and any other design units dependent on the corrected unit. You can recompile from the Main Window by entering the command vcom.
• From the Main Window menu bar select: File>Restart , or type the command restart.
• Reenter force statements or read them from a command file.
• Run the simulation.

Command Files

A "command file" is a text file containing a list of simulator commands that can be executed by issuing a "DO" command. This provides a convenient way to develop a test for a VHDL model that can be reused for multiple simulation runs, as are usually needed during debugging. This saves the chore of retyping all commands for each simulation.

• To execute command file "file_name", type the command do file_name, or from the Main Window menu bar select: File>Execute command file and enter or select the file name in the popup menu that appears.
• To terminate execution of a command file, type the command: abort.
• To continue execution of a terminated command file, type the command: resume.

Example Command File:

  add list rd wr
  add list -hex abus dbus
  force wr 0 0
  force rd 0 0, 1 20 -rep 40
  force dbus ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 0
  force abus 16#000 0, 16#004 40, 16#008 80, 16#00c 120
  run 150

This command file opens a list window, displays one-bit signals "rd" and "wr", displays multi-bit signals "abus" and "dbus" in hexadecimal, creates waveforms for the four signals, and simulates for 150 time units.

Debugging VHDL Models

If a VHDL model does not behave as expected, the simulator provides a number of features to assist in tracking down the problems.

Display all signals

Capture and display in a List/Wave Window all signals that might be related to the part of the model containing the error. There is no need to "guess" what a signal might be doing when its actual values can be displayed and examined!

Use Breakpoints

A "breakpoint" is a location in the model at which simulation can be temporarily suspended. While simulation is suspended, the state of the model can be examined and/or altered and simulation continued.

• A breakpoint is defined for a single VHDL source statement.
• To set a breakpoint, find the desired statement in the Source Window and click near its line number at the left side of the window, or type the command:

  BP filename line_number

  where filename is the name of that design unit.

• Clear a breakpoint by clicking on it again in the Source Window or by typing the command:

  BD filename line_number

• While simulation is stopped at a breakpoint, you may do a number of things to aid in debugging the model.
  • Display current signal/variable values by typing the command:

    EXAMINE name

    where "name" is the signal/variable name.

  • Simulate the operation of the model one VHDL statement at a time.
    • Main Window menu bar: click on: Step
      (or type the command: STEP OVER)
    • Main Window menu bar: click on: Step Over
      (or type the command: STEP)

    "Step Over" treats an entire function/procedure as a single statement, while "Step" executes individual statements within a function/procedure.

  • Resume continuous simulation by typing the command: CONTINUE or, from the Main Window menu bar select: Run>Continue
• To save typing, you may wish to have one or more commands automatically executed when a breakpoint is reached. Type "onbreak" followed by a list of commands, separated by semicolons

  Example:

  onbreak examine wr,rd;
  continue

The Process Window

You can monitor which processes are active and which are scheduled to execute via the Process Window, which displays a list of processes and their VHDL path names. You may select (via two buttons):

• Active: Window shows all processes scheduled to run in the current simulation cycle.
• In Region: Window shows all processes that exist in the region selected in the Structure window.

Additional information displayed to left of process names:

• <Ready> Process is scheduled to be executed within the current delta time.
• <Wait> Process is waiting for a signal to change or for a specified time out period.
• <Done> Process has executed a wait statement without a time out or sensitivity list. (It can not execute again during the current simulation run.)

ModelSim EE Simulator Command Summary

ABORT

Halt execution of a macro file

BD <filename> <line>

Delete breakpoint at indicated line of VHDL source file

BP [<filename>] [<line>] [<command> {;<command>}]

Set breakpoint at indicated line of VHDL source file and execute one or more simulation commands. List all breakpoints if no filename/line given.

CHANGE <variable> <value>

Change the value of a variable or signal. (Simulator must be paused at a breakpoint or after STEP)

CONTINUE

Continue execution after a STEP command or breakpoint.

DESCRIBE <variable_name>

Display info about the type of a variable or signal

DO <filename> {<parameter_value>...}

Execute commands from a macro file. Can pass up to nine parameters, designated in the macro file as $1 ... $9.

DRIVERS <signal_name>

Display the current value and scheduled future values for all drivers of the specified signal.

ECHO <text_string>

Display a message in the Transcript window.

ENVIRONMENT [<pathname>]

Display or change the current signal environment.

EXAMINE <name>

Display current value of named signal. (Simulator must be paused at a breakpoint or after STEP)

EXIT [-FORCE]

Exit simulator. If -FORCE specified, then quit without asking if you want to save data.

FIND [-RECURSIVE] [-IN] [-OUT] [-INOUT] [-INTERNAL] [-PORT] <signal_name>

Display full pathnames of all signals whose names match the signal name specification.

FORCE <signal_name> <value> [<time>] {,<value><time>} [-REPEAT period]

Force signal to indicated values at indicated times. Optionally repeat the pattern. (eg. for clocks)
Example

     FORCE x1 0                   -- set x1<=0 now FORCE x1 0 100 set x1<="1" 100 time units hence FORCE x1 0 10, 0 20 Rep 40 set x1<="0" at time 10, 1 at time 20 then repeat every 40 time units 

FORMAT LIST <filename> and

 

FORMAT WAVE <filename>

Record list of signal names currently in List/Wave window to a file. This file may be invoked with a DO command to recreate the window.

IF <expression> {<command>} {;<command>} {ELSE {<command>} {;<command>} ENDIF

Execute selected commands if certain conditions are true.

LIST [-STROBE [<first_strobe>,]<period>] [-COLLAPSE] [-DELTA | -NODELTA] [{-RECURSIVE -IN -OUT -INOUT -INTERNAL -PORT -<radix> -TRIGGER -NOTRIGGER -WIDTH <n> {<signal_name> ...}]

List signals and their values in the List Window.

LOG [-RECURSIVE] [-IN] [-OUT] [-INOUT] [-PORT] [-INTERNAL] <signal_name> {<signal_name>...}

Create a log file containing simulation data for all listed signals. All signals in List/Wave Windows are automatically included. (The log file is the source of data for List/Wave windows.)

NOFORCE <signal_name> {<signal_name>...}

Cancel a repeating force on a signal.

NOLIST <signal_name> {<signal_name>...}

NOWAVE <signal_name> {<signal_name>...}

Remove signals from List/Wave Window.

ONBREAK [<command> ; {<command>}]

Specify command to be executed when a breakooint is encountered during simulation.

QUIT [-FORCE]

Exit simulator without saving data, after confirmation. (Confirmation not requested if -FORCE specified.)

RESTART [-FORCE] [-NOBREAKPOINT] [-NOLIST] [-NOLOG] [-NOWAVE]

Reload design and reset simulation time to 0.

-FORCE => without confirmation
  

  -NOBREAKPOINT => discard breakpoints (otherwise keep)
  

  -NOLIST => do not keep List window (otherwise keep)
  

  -NOLOG  => do not keep log file (otherwise keep)
  

  -NOWAVE => do not keep Wave window (otherwise keep)
  

RESUME

Resume execution of a macro file after a breakpoint.

RUN [<time_units>...] [-all]

Execute the simulation for the specified number of time units. If no time specified - run for default time. If -all specified, run until there are no events scheduled.

SET [<variable_name> <value>]

Create a user-defined variable and set it to the indicated value. If no argument - display all current user-defined variables.

SHIFT

Shift macro parameter values down one place. (Parameter $2 is assigned to $1, $3 to $2, etc.)

SHOW [<pathname>]

List signals and subregions visible from the current signal environment.

SOURCE [<filename>]

Display VHDL source file.

STEP [-OVER]

Step to the next VHDL statement. If -OVER specified, treat procedures/functions as single statements (do not step through them).

SYSTEM <unix_command>

Execute one UNIX shell command.
Ex. >SYSTEM cp vector2.dat vectors.dat

TB

Display stack trace for the current process.

TRANSCRIPT [ON | OFF]

Echo to Transcript window commands being executed from a macro file.

VIEW [LIST] [PROCESS] [SIGNAL] [SOURCE] [STRUCTURE] [VARIABLE] [WAVE]

Open one or more designated simulation windows. "VIEW *" will open ALL of the above windows.

WAVE {[-RECURSIVE] [-IN] [-OUT] [-INOUT] [-INTERNAL] [-PORT] [-<radix> -<format> [-OFFSET <n>] [-SCALE <n>] [-COLOR <color_name>] {<signal_name>...}}

Add signals to a Wave Window.

• -<radix> specifies signal display radix - default is DECIMAL (BINARY, OCTAL, DECIMAL, HEX)
• -<format> specifies whether to use "logic", "literal" or "analog"
• -OFFSET <n> => offset and scale values for analog signals
• -SCALE <n>
• -COLOR => display color of the the signal. Ex. >WAVE -logic -color gold signal1

WHERE

Display info about system environment (current directory, project file, and work library.)

WRITE LIST <filename>

Record contents of List Window in an output file.

WRITE REPORT <filename>

Print summary of design being simulated to output file.

WRITE WAVE <filename>

Record contents of Wave Window in an output file in PostScript format.