Using the Logic Simulator

After having edited or created a circuit description file, you can execute the logic simulator by typing

logicsim

on the system you are using. In response to this, the logic simulator will output the following:

IOWA Logic Simulator,  Ver. 9
Source file name:

At this point, type in the file name of the file describing the circuit you wish to test. For example, type dlatch to simulate the example circuit, assuming the example circuit description is in file dlatch. After the file name is given, the system will compile your circuit description file. If there are syntax errors, the system will print out the error messages and terminate. When this happens, correct the errors and try again.

Note that the circuit description is compiled into an internal representation quite different from the textual representation of the specification language. Users of the simulator need not understand this representation, but the following description may be useful in understanding how the simulator works. The internal representation is not machine code or assembly code; instead, each gate is represented by a record with information about the state of that gate and a pointer to a linked list of wires connected to the output of that gate. Each wire record in this list holds a pointer to some other gates and a marker indicating which input of that gate it drives. This data structure is designed to support very fast simulation.

In the internal representation of a circuit, subcircuits and arrays have been replaced by data structures that are the same as the data structures that would have been used had the same circuit been described without subcircuits or arrays. Although the output of the compiler is not textual, the process by which subcircuits are processed resembles macro expansion. As a result, the decision to use or not use subcircuits or arrays should not be influenced by any consideration of simulation efficiency.

The Simulation Header

If there are no errors in the circuit, the logic simulator will print out the simulation header. For the example test file, this would be as follows:

==========================================================
   circuit name   = dlatch
   input interval = 1.0us    If you need help, type h.
   output interval= 500ns
----------------------------------------------------------
TIME:OUTPUT               :INPUT
----:------               :-----
500 :q  :qbar             : d
 NS : | : | :do :co       : |c
    : | : | : | : | :     : ||
==========================================================
   0:|  :|  :|  :|  :INPUT:

This header tells you the initial status of the simulator. The components of the header are explained in the following paragraphs:

circuit name:

Gives the circuit name specified in the circuit description.

input interval:

Gives the simulated time interval between consecutive INPUT: prompts in the following simulation. The default input interval value is 1 microsecond. That is, when the next INPUT: prompt comes out, 1$\mu$s of simulated time will have elapsed since the previous prompt. (See the advanced features section if you wish to override this default.)

output interval:

Gives the simulated time interval between two consecutive output display lines. The default output interval value is 500 nanoseconds. That is, when the next output display line comes out, 500ns of simulated time will have elapsed. (See the advanced features section if you wish to override this default.)

The rest of the header is a table with three columns, a TIME column, a OUTPUT column, and a INPUT column. These serve as the labels on the three columns of simulation output.

TIME:

The first column of the simulation output gives the time elapsed since the start of the simulation, in multiples of the output interval.

OUTPUT:

The second column of the output has a sub-column to display each output pin of the circuit being simulated. The header includes the name of each output pin at the top of the appropriate sub-column; these names are taken from the text of the circuit description. Note that output pin names longer than three characters force the use of additional lines in the header.

INPUT:

The last column is reserved for input to the simulator. The header for this column lists the names of each input pin of the circuit being simulated. These are listed one per line and one per column.

It is worth noting that on an 80 column display, there is room for only a limited number of inputs and outputs. The fixed parts of the display format require 12 columns, each output requires 4 columns, and each input requires 1 column. There is guaranteed to be room for 4 inputs, leaving room for a maximum of 16 outputs. Circuits can be constructed with more inputs and outputs, but their output will only be readable if printed on a line printer.

Following the header, the simulator prints the initial values of each output and the initial INPUT: prompt. The format for these is explained in the next section. Outputs are initially low (0 or false) when the simulated power is turned on, and all inputs are low prior to your entering the first input value. This initial state is unstable, since it means that some gates may start out with outputs that are not right for their inputs. As a result, even if you don't change the input values, some of the outputs will immediately change from 0 to 1. If your circuit has any feedback loops in it, for example, if it contains flipflops, it may oscillate between 0 and 1 for some time as a result of these initial changes; this oscillation may consume considerable computing time and it may delay the INPUT: prompt significantly.

Running the Simulation

When an INPUT: prompt appears, the system is in simulation mode. Each time this prompt appears, you can give new input values for each input of the circuit. The legal input values are:

0 or L - a low (false) logic level.

1 or H - a high (true) logic level.

p - a pulse.

x,blank - repeats the previous logic level.

empty line - all input values remain unchanged.

If the input interval is 1 microsecond, there will be a new INPUT: prompt every microsecond of simulated time. Note that simulated time has nothing to do with real time. Making the input interval smaller will not necessarily make the simulator do any more or less work. This is because the simulator uses what is called a discrete event simulation model; in this model, it takes a (roughly) constant amount of computer time to simulate each change in the input of a gate from high to low or from low to high, completely independent of the input or output intervals. Every transition which takes place within a circuit is simulated, whether or not that transition has any observable effect on the outputs of the circuit. Note that this implies that the accuracy of the simulation is not influenced by the input or output interval! A long output interval only limits the accuracy with which simulation results are reported, not the accuracy with which they are computed. Some other methods of simulation involve an internal clock; such systems tend to give more accurate results if the clock is run at higher speeds.

Typing 11 in response to the INPUT: prompt for the example circuit indicates that both inputs d and c are assigned the value 1 (high), since a 1 appears in each column. After being given values, the system simulates all logic transitions which occur as a result of input changes. It also samples all the output values at the instant when one output interval expires and displays the sampled data. After the input 11, the following will be on the display screen:

OK, logicsim
IOWA Logic Simulator,  Ver. 9
source file name: dlatch
========================================================
   circuit name   = dlatch
   input interval = 1.0us    If you need help, type h.
   output interval= 500ns
--------------------------------------------------------
TIME:OUTPUT               :INPUT
----:------               :-----
 500:q  :qbar             : d
 ns : | : | :do :co       : |c
    : | : | : | : | :     : ||
========================================================
   0:|  :|  :|  :|  :INPUT: 11
   1:|= :|= :|_ :|_ :     : 11
   2:  |:|  :  |:  |:INPUT:

There are two new lines of output because the input interval is twice the output interval. The input interval should usually be an integer multiple of the output interval.

Typing a p as an input value causes the simulator to switch the indicated input from its previous value to the inverse of that value for roughly half of an input inverval, and then switch it back to the original value. Thus, a positive pulse will result if the previous value was low, and a negative pulse will result if the previous value was high. The pulse created by p will be roughly centered in the interval between successive INPUT: prompts.

The input/output formats of the logic simulator are similar to those of a tool called a logic analyzer. Logic analyzers are used in testing and debugging digital hardware; they have a graphical display which will show the outputs of a digital system plotted as a function of time, and they are able to inject prepared sequences of test data into the inputs of the circuit. Because common computer display screens can scroll vertically, but not horizontally, the output of the simulator is turned 90 degrees from its conventional orientation. Because of character set limitations, transitions resulting from input changes will be displayed at the end of the next output interval and not immediately after the change. The latter leads to an apparent delay of one output interval in all outputs from the circuit. (If the ASCII character set had an overbar as well as an underline, this problem would be eliminated.)

The values of circuit outputs are displayed by the logic simulator as follows:

:| : - a low (false, 0) logic level.

:|_ : - a transition from low to high.

: |: - a high (true, 1) logic level.

: _|: - a transition from high to low. :| :

:|- : - a short spike or pulse (2 transitions). :|_ :

: _|: - a longer pulse (1 transition per line). :| :

:|= : - multiple spikes (4 or more transitions). :| :

:|= : - a dirty transition (3 or more transitions). : |:

On a logic analyzer, the above output trace might have been shown as follows:

Note that, when a spike, multiple spikes, or a dirty transition is shown, repeating the experiment with a smaller output interval will show more detail, allowing each transition to be shown on a different line. This corresponds to stretching the time axis of the display.

When a the simulation of a circuit begins, flipflops will usually produce multiple spikes for a considerable time; this is a simulation of the behavior of real flipflops when the power is turned on. Flipflop outputs will usually settle into a stable state after a few microseconds, but they can be explicitly set or reset immediately, as was done with the example input for testing the dlatch circuit. It may take a considerable amount of computer time to simulate the power-on behavior of circuits with many flipflops, but this can usually be avoided by using the initial low value of some input to explicitly clear all flipflops in the circuit. Of course, if you do this, the circuit won't work at all until you enter a high value for this input.

The globally predefined high and low inputs provided by the simulator can be used to make an automatic power-on-reset circuit. The key to this is that the simulator provides a low-to-high transition on high immediately after simulating the power-on-transient at each gate. If an appropriate delay element is connected to the high input, a signal can be produced which will remain low for a period after the simulation begins, and then go high for the remainder of the simulation.

Commands to the Simulator

There are a number of special commands which the simulator will accept at the INPUT: prompt. With the exception of the quit command, these commands will be executed and then the output from the simulator will be re-displayed and a new INPUT: prompt will be given as if no simulated time had elapsed. The legal commands may all be abbreviated to one letter; thus, quit may be abbreviated q.

quit:

To stop the simulator, type q or quit.

input:

To change the input interval, type input nn uu, where nn is a positive number and uu is one of s, ms, us, or ns. Large input intervals will allow many output lines to be displayed between INPUT: prompts. The input interval should usually be an integer multiple of the output interval.

output:

To change the output interval, type output nn uu, where nn is a positive number and uu is one of s, ms, us, or ns. Small output intervals allow detals of multiple transitions to be observed with each transition on a line by itself. Note that the input interval should not be smaller than output interval.

read:

To read test data from a file other than the terminal, type read ff, where ff is the name of the new input file. This command is useful because it allows predefined test sequences to be used over and over, for example, while debugging a circuit, without the need to retype the data each time the circuit is tested. For example, consider the following test sequence stored in a file called example.

o 100ns
i 0.2us
11
10 -- a comment
01
11
q

The output from a session in which this command is used is shown below:

OK, logicsim
IOWA Logic Simulator,  Ver. 9
source file name: dlatch
=============================================================
   circuit name   = dlatch
   input interval = 1.0us    If you need help, type h.
   output interval= 500ns
-------------------------------------------------------------
TIME:OUTPUT               :INPUT
----:------               :-----
 500:q  :qbar             : d
 NS : | : | :do :co       : |c
    : | : | : | : | :     : ||
=============================================================
   0:|  :|  :|  :|  :INPUT: r example
   1:|  :|  :|  :|  :INPUT: o 100ns
   1:|  :|  :|  :|  :INPUT: i 0.2us
   1:|  :|  :|  :|  :INPUT: 11
   2:|= :|= :|_ :|_ :     : 11
   3:  |:|  :  |:  |:INPUT: 10 -- a comment
   4:  |:|  :  |: _|:     : 10
   5:  |:|  :  |:|  :INPUT: 01
   6: _|:|_ : _|:|_ :     : 01
   7:|  :  |:|  :  |:INPUT: 11
   8:|_ : _|:|_ :  |:     : 11
   9:  |:|  :  |:  |:INPUT: q

  Simulation ends.
OK,

Note that each line of the file contains only one command or one set of input values. Note also that comments on an input line are allowed as long as there is at least one space separating the comment from the last column associated with an input pin. If you want a paper copy of the output produced by a session with the simulator, redirect the output before you start the simulator.

title:

The title command reprints the simulation header. This would have been useful in the above example after the input and output intervals had been reset. This is also useful if the header scrolls off the screen and you forget which inputs are which.

help:

Help messages for all system facilities are available. Whenever you need help, try typing h and see what help the logic simulator can give you.

Simulator Error Messages

All error messages produced by the Iowa Logic Simulator during the compilation of a circuit description have the following format:

ERROR on line 999 of file XXX
      ---> MMM

The first line indicates the line number of the file on which the error was detected, and the second line indicates the nature of the error. The compiler operates in two passes, and if the first pass detects any errors, the second pass will be aborted. Within a pass, the compiler will usually report all errors it detects, tempered by an attempt to avoid reporting the same error more than once; for some errors, however, compilation will be aborted with the following message:

Compilation aborted; fatal error.

First Pass Error Messages

Pascal run-time execution errors:

An attempt to read from a file which does not exist will raise a Pascal run-time execution error in the machine independent version of the logic simulator. Other run-time errors should be reported, and any code that causes them should be saved so that the error can be recreated.

string pool overflow:

A fatal error. There were too many total characters in all identifiers in the circuit description. The best fix for this is to recompile the logic simulator with a larger string pool, but if this is impractical, use shorter identifier names, or re-use local identifier names from one subcircuit to the next.

packed text overflow:

A fatal error. The total number of lexemes in the entire circuit description, including the text of all subcircuits, was too large. The best fix is to recompile the logic simulator with a larger packed text pool, but if this is impractical, try to make more effective use of subcircuits, arrays, and iterators to shorten the circuit description.

symbol table overflow:

A fatal error. There were too many distinct identifiers in the entire circuit description. The best fix is to recompile the logic simulator with a bigger symbol table, but if this is impractical, use fewer distinct identifiers by re-using local names from one subcircuit to the next.

unexpected EOF:

A fatal error. An end-of file was found while scanning a circuit body for the keyword end.

"circuit" or "inputs" expected:

During the scan for subcircuit and constant declarations at the head of a circuit, something was found other than one of the keywords that can start a declaration (circuit, boolean, integer, real, time, time or use) or a keyword indicating start of of the body of that circuit (inputs, or outputs).

identifier expected:

The keyword circuit was not followed by an identifier giving the circuit name.

too many use levels; limit = 4:

A fatal error. The number of levels of nesting of files included by the use directive was too large. The logic simulator can have no more than 4 open input files at a time. The solution is to move use directives to the global level, so that instead of having the main file include another, which in turn includes yet another, all included files are directly referenced by the main file. Alternately, simply replace some of the more deeply nested use directives by the text of the included files.

"circuit" expected:

The main circuit did not begin with the keyword circuit.

EOF expected:

There was something after the end of the main circuit, or a file included by the use directive had something in it other than declarations of constants and subcircuits. Keep in mind that nothing but blank space may follow the (optional) period at the end of a file.

bad number:

A number was specified with too many digits.

")" expected in parameter list:

The formal parameter list of a circuit included a keyword illegal in the formal parameter list, or the end parenthesis was missing from the formal parameter list causing the entire circuit body to be interpreted as part of the list.

Second Pass Error Messages

x found; y expected:

This message is used for almost all syntax errors. The token x was found in a context where it is not legal; y is one of the tokens (or the name of a token class) that would be appropriate in this context.

x: illegal redefinition:

An attempt was made to redefine the identifier x in a context where that identifier already had a local definition.

too many (actual)parms:

The number of actual parameters provided in the declaration of a part was more than the number expected by the part type being instantiated.

too few (actual)parms:

While parsing a formal parameter list and binding the actual parameters to formal parameters, there were not enough actual parameters to bind with each formal parameter. Or, a subcircuit was declared with over 20 formal parameters, in which case, the logic simulator will need to be recompiled to increase this limit.

x: invalid gate/circuit name:

The identifier x was found after the colon in a part declaration and x was not the name of a subcircuit or a predefined gate type.

x: invalid pin name:

The identifier x was found after the dot in a pin name in a wire list and x was not the name of an input or output of that subcircuit or predefined gate.

x: invalid part name:

The identifier x was found before the dot (if there was one) in a pin name in a wire list and x was not the name of a declared part.

x: unmodifiable name:

The identifier x was found before a dot in a pin name, but was not modifiable by the suffix provided, for example, because x was the name of an input or output to the current circuit or subcircuit.

x.y: is illegally reused:

The pin x.y used as the destination of a wire already had another wire connected to it.

no destination given:

In parsing a wire list entry, a source pin was found and the keyword to was expected but missing.

is not a source:

In the wire list of a circuit, the input of a gate or subcircuit instance was used as a source pin, or an output of the current circuit was used as a source pin.

is not a destination:

In the wire list of a circuit, the output of a gate or subcircuit instance was used as a destination pin, or an input of the current subcircuit was used as a destination pin.

x.y: has an open source connection:

This error message indicates that no wire listed in the current subcircuit provided a source of data for x.y. After parsing the wire list of a circuit or subcircuit, a check is made to see that all outputs of that circuit or subcircuit were connected to some source of data, and a check is made that all inputs of all subcircuits of that circuit or subcircuit are connected to a source of data. As a result, this error message always lists the line number of the keyword end marking the end of the subcircuit where the wire is missing.

x: undeclared:

The identifier x was used in an expression but had no declared meaning.

x: value is of wrong type:

The identifier x was used in an expression and was declared as the name of an instance of a gate or subcircuit, or the name of an input or output pin. Or, in the declaration of the constant x, the type of the expression giving the value did not match the keyword used in the declaration. In the latter case, an extra line is added to the error message giving the value of the expression that was found.

operands of " " incompatible:

An attempt was made to apply one of the arithmetic operations to values that could not be operated on by those operations; for example, adding an integer to a time, or multiplying a subcircuit times a range.

incomparable operands:

An attempt was made to apply a comparison operator to values that could not be compared; for example, times cannot be compared with anything other than times, and ranges and circuits cannot be compared at all.

boolean expected:

A Boolean operator such as and, or or not was applied to a value which was not Boolean, or the expression governing an if statement in a parts list or wire list was not Boolean. In both cases, an additional line gives the actual value of the expression or operand that was found.

integer expected:

The predicate odd was applied to a non integer, an operand of the mod operator was not an integer, an attempt was made to exponentiate a non-integer, a range constructor was used with non-integer bounds, or a non-integer array subscript was used. In all cases, an additional line gives the actual value of the expression or operand that was found.

positive integer expected:

An attempt was made to raise a number to a negative or non-integer power, an attempt was made to raise zero to the zero power, integer division or mod involving negative numbers was attempted, division by zero was attempted, or an attempt was made to instantiate a pre-defined gate type with a negative or zero number of inputs. In all cases, an additional line gives the actual value of the expression or operand that was found.

nonzero real expected:

Division by a real or time value of zero was attempted. An additional line gives the value of the expression or operand that was found.

positive time expected:

The delay specified for a gate or wire was less than zero or not a time. In all cases, an additional line gives the actual value of the expression or operand that was found.

range expected:

The size, first or last operator was applied to a value that was not a range, or in the declaration of a part or an input or output pin of a circuit, the syntax of an array specification was used with a value that was not a range, or the expression governing the iteration in a for statement was not a range. In all cases, an additional line gives the actual value of the expression or operand that was found.

index out of bounds:

The pin number used to select an input of a predefined gate was out of bounds, or an array index was out of bounds. In both cases, an additional line gives the actual value of the expression or operand that was found.

x: not an array name:

A subscript was used on x, a part name or pin name that was not the name of an array of parts or pins.

x: unmatched parameter types:

An attempt was made to bind the formal parameter x to an actual parameter of the wrong type. An additional line gives the value of the actual parameter.

unmatched array bounds:

An attempt was made to wire a source to a destination where the array bounds of the two did not match or where one was an array and one was not an array.

x: index required for this part:

The name x of an array of parts was used without a subscript in specifying a pin to be connected in a wire list.

Simulation Error Messages

Most interactive simulator error messages should be self-explanatory and offer interactive help in correcting the error. The following error message will sometimes result from actual errors in the circuit being simulated, however, and can only be eliminated by changes to the circuit design:

Warning, bus "x" was driven with conflicting inputs:

The three-state bus named x had more than one bus-driver enabled at the same time, and two or more of the enbled drivers were attempting to drive the bus to differing values at the same time. In a real system, this can cause physical damage, overheating, or electrical noise and transient malfunctions; in the simulated system, it will cause no damage but the value on the three-state bus will be unpredictable until the conflict is resolved.