1This is release 9.7 of irsim.
2
3----------------------------------------------------------------------------
4Compilation and installation
5----------------------------------------------------------------------------
6
7The make script has been changed to work similarly to the magic-7.3 GNU
8autoconf make. To make the default IRSIM version, which includes Tcl/Tk
9(if available) and OpenGL (if available), do:
10
11 ./configure
12 make
13 make install
14
15----------------------------------------------------------------------------
16Running IRSIM under Magic
17----------------------------------------------------------------------------
18
19Standard magic version:
20 See the magic tutorial #11 (document "tut11.ps" in the magic source
21 distribution).
22
23Tcl-based magic version and Tcl-based IRSIM (irsim-9.6):
24
25 Run the Tcl version of magic in the usual manner. As an example,
26 consider "tut11a" used in tutorial #11 for demonstrating IRSIM.
27
28 magic -w -d OGL tut11a
29
30 Start IRSIM with:
31
32 irsim
33
34 This is a Tcl procedure which can guess at default values. Magic
35 starts up with a definition for the procedure which looks for the
36 "irsim.tcl" script in the CAD_ROOT install directory. Assuming that
37 magic and irsim are installed in the same CAD_ROOT root (e.g.,
38 /usr/local/lib or /home/cad/lib), this file will be sourced, and IRSIM
39 will be ready to run. If not, it will be necessary to run "source
40 <pathname>/irsim.tcl" by hand, substituting the actual install path
41 for IRSIM.
42
43 If a layout is loaded into magic, it is assumed to be the circuit to
44 be simulated. If .ext and/or .sim files don't exist for the circuit,
45 they will be created.
46
47 The full syntax is:
48
49 irsim [parameter_file [sim_file]]
50
51 where "parameter_file" is an irsim ".prm" file from the IRSIM library
52 install directory, and "sim_file" is a .sim file, presumably generated
53 in magic by "exttosim".
54
55 At this point, if all goes well and no errors occurred, all IRSIM
56 commands will be available under magic. Additional commands are added
57 when running irsim under magic. These are:
58
59 watchnode [node_name [style_name]]
60 Display a node's simulation value on the layout. If
61 no name is given, find the node under the box and
62 display its value. The style name is one of magic's
63 display styles from the ".dstyle5" file. The default
64 is "white".
65
66 unwatchnode node_name
67 Erases the node value from the layout.
68
69 movenode node_name
70 Node values normally appear positioned at the point
71 found by the magic "goto" command. If this is a
72 poor choice, the node can be moved to a position
73 centered on the magic cursor box using this command.
74
75 watchtime
76 Causes the simulation time to be drawn on the layout,
77 centered on the magic cursor box's current position.
78
79 unwatchtime
80 Erases the simulation time from the layout.
81
82 movetime
83 Moves the position of the simulation time text to be
84 centered on the current position of the magic cursor
85 box.
86
87 For example, with layout file tut11a.mag, after invoking "startirsim", do:
88
89 watchnode bit_0
90 watchnode bit_1
91 watchnode bit_2
92 watchnode bit_3
93 watchnode RESET_B black
94 watchnode hold red3
95
96 vector clk phi1 phi2
97 vector clkb phi1_b phi2_b
98 clock clk 10 00 01 00
99 clock clkb 01 11 10 11
100 vector bits bit_3 bit_2 bit_1 bit_0
101 w clk hold RESET_B bits
102
103 c
104 l hold
105 l RESET_B
106 c
107 h RESET_B
108 c
109 c
110 c
111
112 The values are drawn on the magic layout in time with the simulation.
113 Note that "source tut11a.cmd" is a valid command. The .cmd file
114 that comes with the tutorial should be okay as-is. However, note
115 that several commands in IRSIM are not legal Tcl syntax, and have
116 been changed. Any of these commands in a file must be changed to
117 match before the file can be sourced. Also, some commands in
118 IRSIM are already defined as Tcl commands. These are: time, set,
119 and clear. To get the expected behavior in IRSIM, they must
120 include the namespace: irsim::time, irsim::set, irsim::clear.
121 "exit" is a trivial overloaded command. "clock" is also
122 overloaded, but because the IRSIM and Tcl syntax for "clock"
123 are mutually exclusive, the command is handled by IRSIM and
124 checked for which version of the command is intended.
125
126 Note that it is possible to display vectors on the magic layout.
127 Position the box to an empty area of the layout and type:
128
129 watchnode bits
130
131 Similarly, you can postion the box to another empty area and do:
132
133 watchtime
134
135 to get the simulation time display printed on the magic layout.
136 You do not need to know the name of a node in order to see its
137 value. For instance, select a random piece of the layout and
138 type "watchnode". The node value will be displayed at the position
139 of the selection.
140
141 To simply query a node value (without selecting it for display), use
142 the 2-argument form of "assert", combining IRSIM and Magic commands.
143 Select a bit of layout paint, and do:
144
145 assert [getnode]
146
147 -----------------------------------------------------------------------
148
149 Under irsim, the "display" command has an additional option, "tclproc".
150
151 display tclproc proc_name
152 display -tclproc
153
154 when proc_name is specified, the IRSIM "d" command will invoke the
155 specified Tcl procedure instead of printing values to the screen.
156 The procedure will also be called whenever node and vector values
157 in the watch list ("w" command) are updated. This method allows
158 signal names, values, and times to be captured and used by other
159 programs. "watchnode" makes use of this method to write simulated
160 node values back into the magic window.
161
162 The syntax of the Tcl procedure is:
163
164 proc proc_name { name value time } {}
165
166 This procedure is called internally from IRSIM. "name" will be
167 given the name of the node or vector being watched. "value" will
168 be given the value of the node or vector. "time" will be given
169 the current simulation time in nanoseconds. Note that this
170 procedure is always called at least twice, with the last call
171 being name="curtime", value="t", such that procedures may defer
172 printing the time value until all watched node values have been
173 displayed. Only the last call to the procedure will return its
174 value to the interpreter.
175
176----------------------------------------------------------------------------
177Release Notes
178----------------------------------------------------------------------------
179
180The calibrate directory contains information on creating your own prm files.
181
182Release 9.5+ includes the software to perform incremental simulations, which
183can also be used to create an incremental-fault-simulator. To make the
184fault simulator, you will have to do it by hand: First use the make_irsim
185script to build irsim, then (before cleaning anything in irsim) go into the
186src/fsim directory and run make. This will create the program called "ifsim",
187which you can use to run statistical simulations of stuck-at faults.
188The directory src/fsim/doc contains both latex and PostScript versions of the
189documentation needed to use ifsim.
190
191Release 9.5 also includes the following extra code:
192
193 1) Power estimation code through toggle counts (written by Don Ramsey)
194 The code is not completely debugged yet (?) but there is demand for
195 it from a lot of people. It can be turned on/off selectively
196 through the "make config" script. See the file man/powerEst.doc
197 for details on how to use this.
198
199 2) Code that enables the user to write their own subcircuit models
200 for "analogish stuff". (written by R. Gonzales and S. Sidiropoulos).
201 Again it is enabled in "make config". An example pll is in
202 src/irsim/UserSubckt
203
204 3) Some extra commands (assertWhen and until) which may help debugging
205 of asynchronous designs
206
207 4) Fixes for Linux displays (M. Godfrey)
208
209Release 9.6 includes the following new features:
210
211 5) Tcl-based IRSIM (T. Edwards)
212
213 6) Threaded X11 graphics (no anXhelper!) (T. Edwards)
214
215 7) Makefile configuration support for Mac OS-X, Solaris, and Cygwin.
216
217 8) Pseudorandom number generator for the Tcl version (T. Edwards)
218
219Release 9.7 includes the following new features:
220
221 9) GNU autoconf-base "make" process equivalent to that of magic-7.3
222
22310) Tk-based Analyzer window, including a full set of command-line commands
224 for manipulating the analyzer.
225
22611) Verilog testbench-like commands "at", "every", "when", and "whenever"
227
22812) Command "settle" to handle problematic tight loops (e.g., back-to-back
229 inverters in flip-flops) by waiting a certain period before setting a
230 node undefined.
231
23213) Command "relax" to handle problematic large loops (e.g., flip-flop/
233 multiplexer loops) by forcing initial conditions.
234
23514) Ability to handle multiple circuits by placing each in its own namespace.
236
23715) Ability to define and set nodes that are not part of an input circuit.
238
23916) Simplified vector definitions and setting, including handling of decimal
240 and hexidecimal notation, and specifying numerical ranges in a vector
241 name (such as "vector D D0:8")
242
24317) Tcl procedure-based user-defined subcircuits.
244