User’s Guide to the 6.111 C Simulator

Mark W. Eichin May 11, 1988

Contents

1 Introduction 2 2 How to create a simulation 3 3 Building Submodules 7 4 Simulator data files^{1} 9 A Standard Circuit Element Library 12

Chapter 1

Introduction

The C Simulator is a time domain digital simulator. It is a set of macros and libraries in the C programming language that can be used to build a program which simulates the operation of a circuit, which is then compiled and executed. External inputs and outputs are permitted via the filesystem (see Chapter 4 and the document [1]).

How to create a simulation

Make a copy of the boilerplate simulation file, mysim.c. Also make a copy of the Makefile which you will find there. Load mysim.c into your favorite editor (presumeably emacs) and prepare to enter your simulation.

You should leave the template file unchanged above and below the lines

/* Simulation BEGINS here, type your work BELOW this line */
/* Simulation ENDS here, only type your work ABOVE this line */

These are comments to tell you where your work should go (the C language begins comments with /* and ends them with */). Everything outside these lines is the same for all simulations, only the code pertaining to your circuit goes between these two lines.

Let’s begin with the simple circuit pictured in figure 2.1. First, trace out each run of wire that is electrically connected. Insert a declaration

MAKEWIRE(A);
MAKEWIRE(B);
MAKEWIRE(C);
MAKEWIRE(D);

for each run of wire that you have traced out. Record the names (scribbling them on the schematic might be apropriate) since you will need them later to actually assemble the circuit. Pick any names you want, but keep in mind that

• they have to begin with a letter, though they may contain numbers (they obey the same rules as C identifiers.)

• any wires that are external inputs or outputs should be labelled the way you want to see them in the input or output files (see Chapter 4 for more details.)

Now that all the wires have been declared, they should be connected to the circuit. Start by looking up function names for the simulations of each of the circuit elements. If any of them are not in the predefined table, you will have to break them down into existing elements, or define a new C procedure to simulate them (see chapter 3.)

Then, using the function for each element, create a connection, as follows:

AND(C, A, B);
OR(D, A, B);

Once connections have been made, output lines should be defined. Since C and D are interesting, we will output them:

OUTPUT(C);
OUTPUT(D);

And, since the schematic shows A as being carried through to the output of the circuit, we’ll print it as well:

Figure 2.1: Simple circuit.

OUTPUT(A);

The input values will be assumed to come from a file automatically. Now that you have entered these into the file, save it, and exit the editor.

Now type make mysim. This will compile your simulation, and add the standard simulation libraries to it. If you see messages like

"mysim.c", line 33: syntax error
"mysim.c":33: syntax error
*** Exit 1
Stop.

then there was some error in what you typed.

Another error you may receive is

mysim.c:33: undeclared variable `D' (first use here)

If ‘D’ is a wire name, perhaps you left out the MAKEWIRE(D) statement.

Be sure to check the line listed (and lines before it; C may report errors after they happen, but it will never report them before it finds them) and the following things:

• Make sure that you have not left out the semicolons after the commands used. Semicolons separate commands, not newlines.

• Make sure that you have spelled and capitalized the commands correctly. C is both case and spelling sensitive.

• Make sure that you gave the right arguments to the function (check the table again if you are not sure.)

• Make sure that the wire name you used was created in advance (with the MAKEWIRE command). Also be sure that it is spelled correctly.

/* Simulation BEGINS here, type your work BELOW this line */
MAKEWIRE(A);
MAKEWIRE(B);
MAKEWIRE(C);
MAKEWIRE(D);
AND(C, A, B);
OR(D, A, B);
OUTPUT(A);
OUTPUT(C);
OUTPUT(D);
SETWIRE(A, LOGIC_HI, 100);
SETWIRE(A, LOGIC_LOW, 200);
SETWIRE(B, LOGIC_HI, 50);
SETWIRE(B, LOGIC_LOW, 150);
/* Simulation ENDS here, only type your work ABOVE this line */

Figure 2.2: Complete user code for simulation

You may also get an error of the form

Undefined:
_ANND
*** Exit 1
Stop.

The undefined symbol will probably be a misspelled command name. Check back in mysim.c for that spelling, and correct it. Check in the table of functions if you are not sure.

/*
 * rawusrt.c
 * Template file, with sample circuit
 * [eichin:19880511.1823EST]
 */

#include <stdio.h>
#include <msimdecl.h>
#include <msimfunc.h>
main(argc, argv)
     int argc;
     char **argv;
{
  int dummy = init_run();
  Wirelist master = getblock();
  FileArgs(master,argc,argv);
  /* Simulation BEGINS here, type your work BELOW this line */
  /* Simulation ENDS here, only type your work ABOVE this line */
  run_all(master);
}

Figure 2.3: Raw user template

Building Submodules

Complex submodules should either be

• implemented in C as new functions, or

• implemented as simulator subunits.

New functions are straightforward to implement, and fast as well, if you are familiar with the internal workings of the simulator. This is currently left to the technical reference manual, but may be detailed here at a later time.

A simulator subunit can be created by making a copy of mysub.c. If you are only making one subunit, this will suffice. Follow the same procedure described in Chapter 2 to construct the simulation, using MAKEWIRE for the internal wiring. To create a template function for the main body of the simulator to use, edit the template line at the top of the file:

invent a template line! This space for future expansion...
#define NAME(OUT1, OUT2, IN1, IN2, IN3) std_frobs()

/*
 * xor.c
 * sample user designed application
 * [eichin:19880511.1825EST]
 */
#include <msimdecl.h>
/*
 * z = xor(a, b...): z = a; z=z xor b; repeat.
 */
#define XOR_DELAY 10
xor_func(dep)
     Generics dep;
{
  Event_tag etmp = LOGIC_LOW;
  Wire outwire;
  Timeline outtime;
  nextwire(dep, outwire, outtime);
  while(dep->tag.CTL != END)
    {
      Wire awire;
      Timeline aline;
      readnextwire(dep, awire, aline);
      switch(aline->tag.EVENT)
{
case LOGIC_HI:
  etmp = (etmp==LOGIC_HI)?LOGIC_LOW:LOGIC_HI;
  break;
case LOGIC_LOW:
  etmp = (etmp==LOGIC_LOW)?LOGIC_LOW:LOGIC_HI;
  break;
}
    }
  add_event(outtime, etmp, globaltime+XOR_DELAY);
}

Figure 3.1: xor.c: a sample circuit element extension.

Simulator data files^{1}

The input file format consists of lines which are either assignments or wait statements. An assignment consists of a wire name followed by a space and then a value, which is one of

Tag Meaning
1 Logic High
0 Logic Low
U Undefined
X Tristate
C Contention

A sample file is included in Figure 4.1.

A wait statement is a line containing the token wait either alone or followed by a number of time units (nominally nanoseconds) before the next state change. If the number is left out, it means to allow the simulator to “settle” before making the next state change. The simulator currently ignores these statements, as it propagates any non-delayed changes immediately.

These files can be read in by the C simulator, the Lisp Simulator, or the Digital Oscilliscope. The Oscilliscope can also build these input files.

1Taken from [1]

wait 5000
A 1
B 1
wait 500
A 0
B 0
wait 100
wait 5000
A 1
B 1
wait 500
A 0
B 0
wait 100
wait 5000
A 1
B 1
wait 500
A 0
B 0
wait 100

Figure 4.1: Sample input file.

 wait 50
B 1
wait 10
C 0
wait 40
A 1
wait 10
C 1
wait 40
B 0
wait 10
C 0
wait 40
A 0
wait 10
C 0
wait 4791
A 1
wait 0
B 1
wait 10
C 0
wait 0
C 1
wait 490
A 0
wait 0
B 0
wait 10
C 0
wait 0
C 0
wait 5090
A 1
wait 0
B 1
wait 10
C 0
wait 0
C 1
wait 490
A 0
wait 0
B 0
wait 10
C 0
wait 0
C 0
wait 5090
A 1
wait 0
B 1
wait 10
C 0
wait 0
C 1
wait 490
A 0
wait 0
B 0
wait 10
C 0
wait 0
C 0

Figure 4.2: Output of simulator run.

11

Appendix A

Standard Circuit Element Library

The following table lists the standard circuit elements included with the C Simulator. Other specific elements may be have been added for specific projects; see your local documentation for more detail.

Function name Arguments Inputs Description
and  C, A, B  A, B C ←A .AND. B
or  C, A, B,  A, B C ←A .OR. B
not  B, A  A  B ←.NOT. A
tristate  C, A, B  A, B if B, C ←A else C ←tristate

Bibliography

[1] Tom Masotto. Tools-11: simulator signal input/output data structure. September 1986. frob.