The esim Simulator

This web page contains instructions for running the ESIM simulator. It assumes that the user has already compiled her program using the esim compiler.

The simulator and compiler are available for download at http://www.cse.ucsc.edu/~elm/Software/Esim/download.shtml.

Starting the simulator

The simulator is started by simply typing esim at the command line. This will start the simulator but will not load any netlists. The simulator interface is a Tcl shell, and can be programmed in the same way that any other Tcl shell can be programmed. If desired, the simulator can be started with a graphical window (if you're running under the X windowing system) by using the -tk command line option (esim -tk).

Circuit symbols & values

The values of any circuit symbol may be examined or set during simulation. This allows the user to interactively debug her design or provide toplevel control by setting global signals (such as a clock). All named signals may be examined or set. This includes symbols in components. The top level circuit has an empty name. All other circuits are given a name consisting of their parent's name combined with the label specified in the use statement as follows:

define foo (a, b)
circuits
    a <= b & 1;
end circuits;
end foo;
define bar (x[2], y[2])
circuits
    s use foo (x[0], y[0]);
    t use foo (x[1], y[1]);
end circuits;
end bar;
signal topx[4], topy[4];
circuits
    hi use bar(topx[3:2], topy[3:2]);
    lo use bar(topx[1:0], topy[1:0]);
end circuits;
In the above circuit, the top-level symbols are topx and topy. Each instance of the bar component creates its own copy of the symbols x and y. The hi use statement creates hi.x and hi.y, and the lo use statement creates lo.x and lo.y. Since each instance of bar itself creates two instances of foo, the following signals are defined: lo.s.a, lo.s.b, lo.t.a, lo.t.b, hi.s.a, hi.s.b, hi.t.a, hi.t.b. Each of these signals may have its own value; even though there are 4 instances of the signal a in foo, each may have its own value (and thus has its own name) because each belongs to a different "copy" of the foo component.

Symbol values may be specified in either binary or hex (using the -hex or -binary switch). The default for all commands is binary. Possible symbol values include 0, 1, X, and Z. 0 and 1 are self-explanatory: high and low logic values. Zrefers to a node that isn't currently driven by any gate. Xmeans that the value of the node can't be determined. This can occur for several reasons. First, the node could be driven to different values (0 and 1) by two or more different gates at the same time. Second, the node could be driven by a single gate whose output value can't be determined for some reason, such as indeterminate inputs (X-valued). For binary, each bit is represented individually by one of these four symbols. For hex, however, nodes are shown in groups of four. If all nodes in a group of four have "real" values, a hex digit is displayed. If all are undriven, Z is displayed. Otherwise, X is displayed. This means that the four bits 010X would be shown as a single hex digit of X, as would 0Z11.

Simulator commands

All simulator commands are preceded by the word esim. This is done because the esim keyword tells Tcl to send whatever follows to the esim simulator. Omitting esim from a simulator command can cause errors, particularly for commands that are valid for both esim and Tcl (such as load).

The simulator commands are as follows:

In addition to the commands listed above, the simulator understands all regular Tcl & Tk commands. This means that you can write Tcl/Tk programs to automate simulator initialization and circuit testing. For example, you might write your startup commands to a script file and then use the source command to read the script file when you start up the simulator. Alternatively, you may include any startup Tcl commands you want into a file called .esimrc located in your home directory; a sample .esimrc file is available. This file contains commands that allow a user to set up a small graphical window listing the current time and the current values of any signals in the simulator. Note that you must start the simulator with esim -tk for the graphical window to be available, and you need to have an X display to use graphics from Tk. Students at UCSC interested in building a graphical user interface for esim (using Tk) are invited to talk with me about a possible independent study project.

The following short Tcl program will print a message whenever a variable changes its value. You can type it as shown at the command line, or you can paste it in, or you can put it into a file and read the file in using the Tcl source command.

proc printval {n1 n2 op} {
    global Esim
    set t [esim curtime]
    puts "$t ns: $Esim($n2) => $n2"
}
Once you've defined the printval procedure, you can tell Tcl to invoke the procedure whenever a variable changes. For example, trace variable Esim(clk) w printval will tell Tcl to invoke the procedure printval whenever the variable Esim(clk) is written to (the w). Now, all you have to do is use the command esim trace clk which will update the variable Esim(clk) whenever the symbol clk changes. Whenever it does, a message like this will be printed: 400 ns: 0 => clk. You can prevent further messages for clk by using esim untrace clk.

Feedback

Feedback on this page is welcome. Please send your comments to elm@cse.ucsc.edu.

Last updated Saturday, 10-Jun-2000 10:29:43 PDT by Ethan Miller (elm «at» cs·ucsc·edu)