\documentstyle[newcen,utility,margins,rpulse,underscore,11pt]{report}
\title{User's Guide to the 6.111 C Simulator}
\author{Mark W. Eichin}


\begin{document}
\bibliographystyle{plain}

\maketitle
\newpage
\tableofcontents
\newpage
\newcommand{\templatesim}{{\tt mysim.c}}
\newcommand{\templatesub}{{\tt mysub.c}}
\chapter{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~\ref{chsigfiles} and the document \cite{tm:sig}).

\chapter{How to create a simulation}
\label{chapbuild}

Make a copy of the boilerplate simulation file, \templatesim\/ (see
figure~\ref{mysimc}). Also
make a copy of the {\tt Makefile} which you will find there. Load
\templatesim\ into your favorite editor (presumably {\tt emacs}) and
prepare to enter your simulation.

\begin{figure}
\label{mysimc}
\begin{frepcode}{../src/mysim.c}\end{frepcode}
\caption{mysim.c --- Boilerplate Simulation File}
\end{figure}

You should leave the template file unchanged above and below the lines
\begin{code}
/* Simulation BEGINS here, type your work BELOW this line */
/* Simulation ENDS here, only type your work ABOVE this line */
\end{code}
These are comments to tell you where your work should go (the C language
begins comments with {\tt /*} and ends them with {\tt */}). Everything
outside these lines is the same for all simulations, only the code
pertaining to your circuit goes between these two lines.

\begin{figure}
\special{psfile=democirc.ps voffset=36}
\vspace*{4in}

\caption{Simple circuit.}
\label{figcirc}
\end{figure}
Let's begin with the simple circuit pictured in figure~\ref{figcirc}.
First, trace out each run of wire that is electrically connected.
Insert a declaration

\begin{code}
MAKEWIRE(A);
MAKEWIRE(B);
MAKEWIRE(C);
MAKEWIRE(D);
\end{code}
for each run of wire that you have traced out. Record the names (scribbling
them on the schematic might be appropriate) since you will need them later
to actually assemble the circuit. Pick any names you want, but keep in mind
that
\begin{itemize}
\item they have to begin with a letter, though they may contain numbers
(they obey the same rules as C identifiers.)
\item 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~\ref{chsigfiles} for more details.)
\end{itemize}

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~\ref{secsubmods}.) 

Then, using the function for each element, create a connection, as follows:
\begin{code}
AND(C, A, B);
OR(D, A, B);
\end{code}

Once connections have been made, output lines should be defined. Since {\tt
C} and {\tt D} are interesting, we will output them:
\begin{code}
OUTPUT(C);
OUTPUT(D);
\end{code}
And, since the schematic shows {\tt A} as being carried through to the
output of the circuit, we'll print it as well:
\begin{code}
OUTPUT(A);
\end{code}

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 {\tt make mysim}. This will compile your simulation, and add the
standard simulation libraries to it. If you see messages like\footnote{Bear
in mind that different compilers may generate different messages.}
\begin{code}
"mysim.c", line 33: syntax error
"mysim.c":33: syntax error
*** Exit 1
Stop.
\end{code}
then there was some error in what you typed.

Another error you may receive is
\begin{code}
mysim.c:33: undeclared variable `D' (first use here)
\end{code}
If `D' is a wire name, perhaps you left out the \verb+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:

\begin{itemize}
\item Make sure that you have not left out the semicolons after the commands
used. Semicolons separate commands, newlines are ignored.
\item Make sure that you have spelled and capitalized the commands
correctly. C is both case and spelling sensitive.
\item Make sure that you gave the right arguments to the function (check the
table again if you are not sure.) 
\item Make sure that the wire name you used was created in advance (with the
{\tt MAKEWIRE} command). Also be sure that it is spelled correctly.
\end{itemize}

You may also get an error of the form
\begin{code}
Undefined:
_ANND
*** Exit 1
Stop.
\end{code}
The undefined symbol will probably be a misspelled command name.
Check back in \templatesim\ for that spelling, and correct it. Check in the
table of functions if you are not sure.

\begin{figure}
\begin{code}
  /* 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);


/* Simulation ENDS here, only type your work ABOVE this line */
\end{code}
\caption{Complete user code for simulation}

\end{figure}

\begin{figure}
\begin{frepcode}{../src/demo.c}
\end{frepcode}

\caption{Raw user template}
\end{figure}

Once you have successfully compiled the simulation (that is, once make runs
through and prints only the compilation commands, and no error messages or
``Stopped'' messages) you can run it. Typing
\begin{code}
mysim
\end{code}
by itself will set up the simulation, and process any {\tt SETOUTPUT()}
statements, and run the simulation, printing the results.

If you want to read an input file into the simulation, use the command
\begin{code}
mysim -i filename
\end{code}
where {\tt filename} contains the input statements (see
Chapter~\ref{chsigfiles}). To record the result in a file {\tt outputfile},
use the command 
\begin{code}
mysim -o outputfile
\end{code}
The {\tt -o} and {\tt -i} commands may be mixed. You can use the digital
oscilloscope to produce and read the data files.


\chapter{Building Submodules}
\label{secsubmods}
Complex submodules should either be
\begin{itemize}
\item implemented in C as new functions, or
\item implemented as simulator subunits.
\end{itemize}

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 \templatesub. If
you are only making one subunit, this will suffice. Follow the same
procedure described in Chapter~\ref{chapbuild} to construct the simulation,
using {\tt 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:
\begin{code}
#define FUNCTION my_func
#define MY(OUT, IN1, IN2) make_binop(my_func, OUT, IN1, IN2)
#define DONE
\end{code}

Use your editor's global replace to change all uses of {\em my}\/ to
whatever name you want to assign to the function you create. This
should change {\em my_func}, {\em MY}, and later {\em MY_DELAY}\/ to
appropriate names. {\em MY_DELAY}\/ is optional, and probably set it
to 1 if your element doesn't use it.

The {\em \#define MY(OUT, IN1 ... ) ... } statement is what creates
the macro the user calls to link this element into their wirelist.
There are several procedures for creating these:
\begin{itemize}
\item make_binop(op, c, a, b) creates a node of circuit element op
that has arguments c, a, and b, but only depends on a and b. This is
used for and, or, xor, delay, and tristate.
\item make_unop(op, b, a) creates a node of circuit element op that
has arguments b and a, but only needs to run when a changes. This is
used for the not primitive.
\item make_tracer(op, line) creates a node which runs the procedure op
when line changes state. This is used by the output primitive, and as
an obvious way to implement LED's or other indicator devices.
\item make_anop(opcount, oparguments, argcount, arguments) is the
generic construction macro with arguments of
\begin{itemize}
\item opcount: the number of arguments in the oparguments list. The
valid range is currently 0 through 9.
\item oparguments: the list of the arguments that should cause the
procedure to run.
\item argcount: the number of arguments in the real arguments list.
The valid range is currently 0 through 10.
\item arguments: the real arguments, which are passed as a generic
list to the procedure which is the first element in the list. By
design, the first element of this list {\em must}\/ be the procedure
to call to process the circuit changes; by convention, the next
elements are the output lines, followed by the input (driving) lines.
\end{itemize}

\end{itemize}


The primitives you should need are either declarations or statements.
The declarations are
\begin{itemize}
\item STATE to declare variables that hold the current values of
wires.
\item Wire for variables which actually hold wires.
\end{itemize}

Statements include
\begin{itemize}
\item SAVEOUTWIRE(argumentlist, wirename) saves the current wire in the
list of arguments into the wire called wirename (which must be
declared above.) It then advances the argumentlist to the next
argument.
\item READNEXTSTATE(argumentlist, statename) saves the state of the
current wire in the list of arguments into the state variable called
statename (which must be declared above.) It also advances the
argumentlist to the next argument.
\item READNEXTSTATETIME(argumentlist, statename, timeval) saves the
state of the current wire in the list of arguments into the state
variable called statename (which must be declared above) and the time
at which the change will occur into the variable called timeval.  It
also advances the argumentlist to the next argument.
\item SETOUTPUT(wirename, statename, timeval) sets the write named wirename
to the value of the state variable called statename at the value of
the time expression timeval. timeval is often in the form
globaltime+MY_DELAY.
\item READNEXTTIME(argumentlist, timevariable) saves a time value
from the argument list and stores it into timevariable. It advances
the argumentlist to the next argument. (This is used in the DELAY
primitive, and is included as an example of other argument choices.)
\end{itemize}

\begin{figure}
\begin{frepcode}{../src/funclib/xor.c}\end{frepcode}
\caption{{\tt xor.c}: a sample circuit element extension.}
\end{figure}


\chapter{Simulator data files\protect\footnotemark}
\footnotetext{Taken from \cite{tm:sig}}
\label{chsigfiles}

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

\begin{tabular}{r|l}
Tag & Meaning \\ \hline
1 & Logic High \\
0 & Logic Low \\
U & Undefined \\
X & Tristate \\
C & Contention
\end{tabular}

A sample file is included in Figure~\ref{datainfig}.

\begin{figure}
\caption{Sample input waveform.}
\label{datainwave}

\begin{wave}{330}A.\wfl\wdn{50}\wrs\wup{10}\wup{40}\wfl\wdn{50}\wrs\wup{10}\wup{40}\wfl\wdn{100}\wdn{30}\end{wave}

\begin{wave}{330}B.\wfl\wdn{50}\wdn{10}\wrs\wup{40}\wup{50}\wup{10}\wfl\wdn{40}\wdn{100}\wdn{30}\end{wave}

\end{figure}

\begin{figure}
\caption{Sample input wave file}
\label{datainfig}
\begin{frepcode}{../src/demo.in}\end{frepcode}
\end{figure}

\begin{figure}
\caption{Output simulator waveform}
\label{dataoutwave}

\begin{wave}{232}A.\wxx{1}\wfl\wdn{10}\wdn{40}\wrs\wup{10}\wup{10}\wup{30}\wfl\wdn{10}\wdn{40}\wrs\wup{10}\wup{10}\wup{30}\wfl\wdn{10}\wdn{21}\end{wave}

\begin{wave}{232}C.\wxx{1}\wxx{10}\wfl\wdn{40}\wdn{10}\wdn{10}\wrs\wup{30}\wup{10}\wfl\wdn{40}\wdn{10}\wrs\wup{10}\wfl\wdn{30}\wdn{10}\wdn{21}\end{wave}

\begin{wave}{232}D.\wxx{1}\wxx{10}\wrs\wfl\wdn{40}\wdn{10}\wrs\wup{10}\wup{30}\wup{10}\wup{40}\wup{10}\wup{10}\wup{30}\wup{10}\wfl\wdn{21}\end{wave}

\end{figure}

\begin{figure}
\label{dataoutfig}
\begin{frepcode}{../src/demo.out}\end{frepcode}

\caption{Output of simulator run.}
\end{figure}

A wait statement is a line containing the token {\tt 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 Oscilloscope. The Oscilloscope can also build these input
files.

\appendix
\chapter{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.

\newcommand{\asn}{\mbox{$\leftarrow$}}

\begin{tabular}{|l|l|l|l|}\hline
Function name & Arguments & Inputs & Description \\ \hline
and & C, A, B & A, B & C \asn A .AND. B \\
or & C, A, B, & A, B & C \asn A .OR. B \\
xor & C, A, B, & A, B & C \asn A .XOR. B \\
not & B, A & A & B \asn .NOT. A \\
tristate & C, A, B & A, B & if B, C \asn A else C \asn tristate  \\ \hline
delay & B, A, del & A & B \asn A after del ticks \\
output & A & A & write text value of A with timestamp \\ \hline
\end{tabular}


The D Flip Flop is a bit more complex, and is simulated in the detail
described below.


\begin{tabular}{|c|c|c|c||cc|}\hline
\multicolumn{6}{|c|}{Table from page 5-22, TI databook\cite{ttlref}, for 7474:}
\\ \hline \hline
\multicolumn{4}{|c|}{inputs} &
\multicolumn{2}{|c|}{outputs}\\ \hline
preset& clear &clock& D& Q& Q'\\ \hline \hline
L & H & X & X & H & L \\
H & L & X & X & L & H \\
L & L & X & X & H* & H* \\
H & H & \^{} & H & H & L \\
H & H & \^{} & L & L & H \\
H & H & L & X & Q0 & Q'0 \\ \hline \hline
\multicolumn{6}{|r|}{*unstable.} \\ \hline
\end{tabular}

\bibliography{usrdoc}
\end{document}
