An Introduction to Logic-Sim

1. Logic Simulator

The logic simulator program is named logic-sim. logic-sim reads a circuit defintion from an input file and builds the specified digital circuit. It creates a window and displays the circuit in that window. You can then interact with the circuit by toggling switches in the circuit.

2. Setup the Logic Simulator

You need to add the following path to your PATH variable:

You can to this by adding the following line to the startup script file of your shell (ksh: ~/.kshrc, bash: ~/.bashrc):

After adding this line, log out and log back in to let the command take effect.

You can log back in immediately or later and the logic-sim program will now be available for you to use.

3. Example of Using the Logic Simulator

Begin to familiarize yourself by performing the following experiment by getting the file allgates by clicking here and saving it into your own directory. To save an example from Netscape do the following: 
     Click File -> Save As
     Complete the file name in the "Selection" box
       (Make sure you specify the right directory name and file name !)
     Click OK when the file name is right
After you saved a copy into your own directory, you can run the circuit by using logic-sim. If you had called your file "allgates", the command you use to run the circuit is: 
        logic-sim allgates
Logic-sim prints a lot of connection messages and error. You can re-direct logic-sim's output/error messages to a file using: 
        logic-sim allgates > error-file-name
This will allow you to look for error message with your favorite editor - looking for errors this way is much easier than looking for them on the screen ! (Hint: use the search command in your editor and look for the string "Error").

After invoking logic-sim allgates, a window will pop up and in the window you will see a circuit with 2 switches in the left column and 7 basic components in the center column: and, or, not, nand, nor, xor (exclusive or) and xnor (exclusive nor, which is the same as not-exclusive or). We did not discuss xor and xnor, so ignore these. The rightmost column contains a set of 7 `probes', which are bascially lights that goes on (filled) if the signal probed is `1' and off (not filled) if it is `0'. You can now interact with the circuit by toggling the switches in the circuit (if you have some switching in the circuit). By the way, the only kind of interaction allowed is toggling of switches.

4. Components in logic-sim

Logic-sim has a "built-in" set of logic circuits that it know how to create one when you want one. It knows how to create all basic digital circuits (AND, OR, NOT, NAND, NOR, XOR gates). It also knows about more complex digital circuits (later). In general, the digital circuit that you are gonna build will make use of existing digital circuit components from logic-sim and digital circuit components that you has built before.

You build a digital circuit by:

You do this by entering the digital components in a "circuit file". Examples of circuit files are: and , or, not, nand , nor, xor, and allgates,

The input line for the logic simulator follows a very simple syntax: 

      Component Coordinates Inputs Outputs ;
where: Most components have one or more input signal and one or more output signal. Each signal must have an unique name. A connection is made when the same name is used.

5. User inputs in Logic-Sim: Switches

A switch is the only way to obtain input into a circuit. A switch is created with the command ``Switch'', see for an example in the file allgates. You will see these: 

		Switch 1a sw0 ZERO;
		Switch 1a sw1 ONE;
Each switch is associated with a key. The first switch you create corresponds to the zero (`0') key, the next switch to `1', and so on. You can toggle the switch by hitting the corresponding key on your keyboard, but make sure your mouse cursor is in the circuit window when you do so. Try pressing the `0' and `1' keys and see the effects on the circuit.

6. Coordinate System in logic-sim

Logic-sim defines a big canvas divided into squares and you can put one or more components in any square. When you put multiple components in one square, the componets will displayed vertically stacked. The coordinate is given as (row,column) and you can either use letters or digits to indicate a row or a column. So the coordinate grid consists of 26x26 squares if you use letters, which I recommend (but you will find some examples in the demo directory that use digits as coordinates). The upper left coordinate is `aa', the one at it's right is `ab', and the one below it is `ba', and so on:

Each coordinate identifies a ``square'' that you can use to place (one or more) components. For example: 

		Switch aa sw0 ZERO;
You can put as many components in a square as you wish: 
		Switch aa sw0 ZERO;
		Switch aa sw1 ONE;
If you put multiple compnents in a square and would like to see a different kind of arrangement other than stacking, then you would need to place the component in a specific coordinate in a square. Yes, within a square (e.g., square `aa'), you have 26x26 subsquares ! The coordinate of the subsquares are similar to those of the squares themselves. The coordinates of the subsquares are denoted by 2 pairs of coordinates, joined by a period. For example, the coordinate `aa.aa' refers to the top-left subsquare in the top-left square of the grid: the first coordinate `aa' denotes the square, the second `aa' denotes the subsquare.

Range coordinate

7. Some Basic Components

The following table shows a partial list of the available components in the logic simulator (later project handouts will explain new components when they are needed).

Component Command line syntax Notes
Switch Switch Coord Output InitValue; Toggle switch with key, 1 output
Probe Probe Coord Input; 1 input & no output
Not Not Coord Input Output; 1 input & 1 output
And And Coord Inputs Output; Many inputs & 1 output
Or Or Coord Inputs Output; Many inputs & 1 output
Nand Nand Coord Inputs Output; Many inputs & 1 output
Nor Nor Coord Inputs Output; Many inputs & 1 output

Some components can have one or more inputs. Although most components you find in this table have one outputs, later on you will see components that have multiple outputs.

To make a circuit that logic-sim understand, each output signal is given an unique name. Later, when you want to connect a given output signal to the input of a component, you identify the output signal with its unique name. A name in logic-sim begins with a capital letter, optionally followed by one or more letter, digit, `-' (dash) or `_' (underscore). The different components are separated by a semi-colon.

Again, to connect the output of a component X to the input of another component Y, do:

8. Examples

Example 1: 
	   Switch aa sw0 ZERO;
defines a switch located at grid coordinate (a,a). The output of this switch is named `sw0' and the switch is initially off (ZERO). Only switches can have initial values. As initial values for a switch, you can use ZERO (off) or ONE (on).

Example 2: 

       Switch aa sw0 ZERO;
       Probe "myProbeName" ab sw0;
Here, we connect the output of the switch `sw0' to the input of a probe. Note: the proble is label with the name "myProbeName". Hint: label the probes in your program with a meaningful name to help debugging.

This program is found in `example2' in the demo directory. Try run it and see the effect (remember that the first switch is associated with the 0 key, toggle the 0 key and see the effect). Note: notice the little `0' at the upper left hand corner in the switch. This indicates that the switch is associated with the key `0'. Now, you can also label a switch with a name, just like we did with the probe. But if you do label a switch, make sure you include the digit that is associated with the switch, because otherwise it would be very difficult to find the key that toggles the labeled switch. Try run this example to see a labeled switch: 

       Switch "0:mySwitch" aa sw0 ZERO;
       Probe "myProbeName" ab sw0;

Example 3: 

     Switch aa sw_0 ONE;
     Switch ba sw_1 ONE;
     Switch ca sw_2 ONE;
     And bb sw_0 sw_1 sw_2 out;
     Probe bc out;
defines three switches located at grid coordinates (a,a), (b,a) and (c,a). The output of switches one, two and three are named `sw_0', `sw_1' and `sw_2', respectively and they are all initially on. At coordinate (b,b), an `AND' gate is placed which has three inputs: `sw_0', `sw_1' and `sw_2' (the outputs of the switches). The output of the AND gate is named `out'. A probe is placed at coordinate (b,c) which use input `out' (the output of the AND gate). Thus, the probe will display the output of the AND gate. This circuit is found in file `and3' in the demo directory.

You can play with any digital circuit in the demo directory by copying it over to your directory and run logic-sim filename. By hitting the zero (`0') key, you toggle the first switch, `1' the second switch, and so on.

9. Comments

You can have C-type comments /* ... */ embedded in the file. For example, the `allgates' circuit file contains the following: 
		/*  allgates netlist - NOTE: comment */

		Switch aa sw0 ZERO;
		Switch aa sw1 ONE;

		And ab sw0 sw1 and;
		Probe ac and;

		Or ab sw0 sw1 or;
		Probe ac or;

		Not ab sw0  not;
		Probe ac not;

		Nand ab sw0 sw1 nand;
		Probe ac nand   ;

		Nor ab sw0 sw1 nor;
		Probe ac nor;

		Xor ab sw0 sw1 xor;
		Probe ac xor;

		Xnor ab sw0 sw1 xnor;
		Probe ac xnor;

10. Macros

Later in the course (in project 3), you will need macros to help you build more complex circuits. You may not need it now, just keep these information handy and read about it when you will need it.

You can build more complex components from basic gates and use the complex component in further design using the macros facility in logic-sim. The syntax of a macros definition is:

Example:

It makes this circut (discussed in class):

NOTES:

The Input-signals of the Full_Adder component are: CarryIn, a and b while the output signals are CarryOut and Sum.

You can use the input signals (like an input parameter) as inputs to circuit components.

Notice that the circuit components in the body of the macros follows the same structure as the components you used to construct a circuit. The macro component will be displayed as a rectangle and the coordinate used in the circuit components of a macro are used to place the component inside the rectangle that represents the macro.

Hint:

What you need to look out for when defining a macro:

Using a macro

After you define a macro, you can use the component defined as a macro exactly like an ordinary component... except:

For example, to use the Full_Adder component, use the following syntax:

Example of a circuit file that uses the Full_Adder macro:

(The coordinate "ab-cd" is a range coordinate - it means: occupy the coordinates between "ab" upto "cd"; i.e.: ab, ac, ad, bb, bc, bd, cb, cc, cd, db, dc, dd)

(You can cut and paste the above circuit into a file and run it with logic-sim and see the circuit).

Clearly, a macro definition is similar to a method definition in Java and you can "invoke" a macro similar to invoking a method in Java. Macros can help you simply your circuit design When you want to make many copies of the same component, you need only define the component once as a macros and create it as many times as you want. The demo logic-sim file `4-bit-adder' ( click here) illustrate the use of macros clearly. We first define a Full Adder macro at the start of the circuit program, then later, we define 4 Full Adders to make a 4 bit adder circuit.

Macros will also allow you to simplify the circuit design. In the later project assignments, I will adopt a "plug-and-play" approach. I will give you a logic-sim circuit file that contains all the necessary switches, probes and connections to a component that you need to design. For these projects, you will need to design a macro that can be used to "plug" into the circuit file given to you. The circuit has all the controls you need to test the circuit for correctness.

11. Common Errors.

  1. Before you even start looking for errors, make sure you do not have any of these "structural" errors which will cause logic-sim to become completely confused:

  2. How to find your errors when logic-sim tells you there are fatal errors and exits:

    The following is a list of some common errors made by students from previous courses....

  3. Using lower case letter as first letter for a macro name.

  4. Unconnected:

    Logic-sim reports the error: 

       ........  "ZZ..variableName" unconnected; UNKNOWN assumed.
    Check the spelling of your variable "variableName" (case sensitive). If the variable was an array variable, make sure it has [ ].

  5. Common error using array variables:

  6. Too many switches

  7. You see slashes in you switches.

  8. You see slashes in you probes.

  9. Error message: "sim.lib not found".

  10. Error message: Output tied together.

  11. Error message: Incorrect I/O configuration for Alu at COORD