\newpage
\section{The WOLCOMP composition system}

\def\wol{{\bf W\kern-2pt o\kern-1pt\lower 1pt \hbox{L}}}
\def\wolcomp{\wol{\bf\kern-2pt c%
\kern-.8pt o\kern-.8pt m\kern-.8pt p}}
\def\wolery{\wol{\bf\kern-2pt e\kern-.5pt r\kern-.8pt y}}


\begin{center}
\rule{3in}{0.03in}
\end{center}
   This section is taken almost verbatim from a document prepared
   by Carver Mead.  For more information, please refer to
   the \wolery\.  Changes and additions are indicated by horizontal bars.
\begin{center}\rule{3in}{0.03in} \end{center}

\wolcomp\ is a very simple composition system embedded in Pascal.  It takes
cells from only those CIF files prepared on \wol, and composes them into
larger cells which can be further composed.
Being an embedded language, the user builds a chip by writing a program.
There are a number of built-in functions and procedures to make all that a
lot easier.  To compose a design, one must first get cells---each of which
resides as an individual file on your file system---into \wolcomp.  The
procedure that brings in a cell is
    \begin{flushleft}{\bf procedure getfile\rm(name:strng10);}  \end{flushleft}
To get a cell from file {\tt XOR.CIF} the call is {\bf getfile}(`{\tt XOR}');
Note that the file must have a {\tt .CIF} extension and you must be prefixed
to the directory where the file resides.  If you need to access a cell
in a different directory, set the global string variable {\bf prefix} to
the appropriate directory (don't forget to terminate it with a ``/'').

\begin{center}\rule{3in}{0.03in} \end{center}
{\em EDITOR'S NOTE:  It is no longer required that all geometry cells be in
separate files.  The {\tt load\_library} command described below can
accomodate multiple cells per file (as created by \NEWOL, particularly
by the DUMP command).  Since it can also accomodate one cell per file,
{\tt load\_library} is a superset of {\tt getfile}, and can be used in
its place everywhere!}
\begin{center}\rule{3in}{0.03in} \end{center}

\wolcomp\ builds a symbol table and places the cells in it so they can be
accessed by name.  A pointer to an entry in the symbol table is of type
`cptr'.  To get a pointer to a cell use
      \begin{flushleft}{\bf function cell\rm(name:strng10):cptr;} \end{flushleft}
To instantiate a copy of the cell, there are two commands:
      \begin{flushleft}{\bf procedure draw\rm(c:cptr);} \end{flushleft}
places an untransformed instance of the cell pointed to by the argument
with its lower left corner at the position given by the global coordinates
$x_0,y_0$.

For situations where cells need to be mirrored or rotated
       \begin{flushleft}{\bf procedure drawx\rm(c:cptr,tform:integer);} \end{flushleft}
places an instance with its lower left corner at $x_0,y_0$ and transformed
by one of the 8 transforms in the dihedral group defined by mirrors in {\em
x\/} and {\em y\/} and rotations by integral multiples of $90^\circ$.

\begin{tabular}{cl}
\multicolumn{2}{l}{The transforms are defined as follows:}         \\
0--3 &  unmirrored cell rotated by the number times $90^\circ$.     \\
4--7 &  cell first mirrored in $x$, then rotated as above.
\end{tabular}

When a cell is originally drawn, all of the shapes within it are defined
with respect to some {\em origin} local to the cell.  Many embedded systems
use the CIF convention that positions an instance of the cell by placing
the origin at some $x,y$ location.  Since the instance may be transformed
by rotation or mirror operators, the placement of the origin depends upon
the transformation applied.  This approach places the burden of keeping
track of these coordinate offsets on the user.  \wolcomp\ automatically
applies the proper offsets such that all cells are placed with their lower
left corner at $x_0,y_0$ rather than with their origin at that point.  In
this way, the user need never be aware of the cell origin.  Cell instances
are treated as tiles, and composition is the proper tiling of the plane.
Both procedures {\bf draw} and {\bf drawx} leave coordinates of the the
upper right corner of the instance in global variables $x_1,y_1$.

The main program must start with a call to {\bf start\_up} and end with a
call to {\bf shut\_down}. You may of course, add procedures, variables, etc.,
above the main program to make your life easier.  Since you are thus
mixing your own stuff with the \wolcomp\ primitives, your file will be
unique to a chip design.  I suggest that you name it after the chip.

A large design is always built up by defining a cell as a composition
of already defined cells. To define a new cell use
    \begin{flushleft}{\bf procedure define\rm(name:strng10);}\end{flushleft}
Then put the required {\bf draw} or {\bf drawx} commands for the subcells
and end with
    \begin{flushleft}{\bf procedure endef;}\end{flushleft}
which buttons the whole thing up and adds it to the symbol table. \hfil\break
{\em Note---definitions cannot be nested !}

The methodology I have used to build complex chips size is to define all
the ``real'' cells (those with transistors in them) in the context of the
others to which they must abut.  The odd corners are then filled up with
{\em wiring cells}, to connect the whole thing together.  I keep a
floorplan with cell names as I go along.  The cell names are also the file
names.  To date, \wol\ is not smart enough to do this floorplanning job for
us, but it does give a nicely annotated floorplan plot as it is run.  At
the end, I write a little program in \wolcomp\ to put the whole thing
together.  A small example follows to illustrate the technique.  Note that
there is not a single absolute coordinate in the entire text.  All of the
placement coordinates are done by the draw commands interacting with global
variables.  In a pinch, there are times when you will really want to stick
a long wire down, and don't want to make an enormous wiring cell in \wol\
just for that wire.  For those occasions there is 
       \begin{flushleft}{\bf procedure box\rm(c:strg);}\end{flushleft}
The string argument is the CIF layer name of the box.  This
procedure creates a box of the appropriate layer with one corner at
$x_0,y_0$ and the other at $x_1,y_1$.  You can make a whole pile of boxes
(even a whole design) by using this primitive and the composition functions
described above.  \wolcomp\ is thus a complete embedded layout language.
{\em However, it was never intended to be used that way}---\wol\ is really
a much easier and more idiot-proof way to design cells.

When your design is complete, compile the program and run it!  You will be
prompted for the name of an output file.  Some generally helpful
information is displayed on the screen as things progress.  If you have
forgotten to define a cell, or to get it off the disk, \wolcomp\ will tell
you that the cell is not loaded.  Once all is well, you will be asked if
you want a \putindex{floorplan plot}.  {\em Say yes!\/}\ You will find it
much easier to debug your composition this way before you start staring at
all that layout.  \wolcomp\ can plot any cell you have defined, so be sure
the entire project is defined as a cell.  Floorplans are only plotted to
one level---if you want to see the subcells of one of the subcells, you
should plot it as a separate cell {\em right?---O.K.---I'm sorry I asked!}
The name of the cell whose floorplan is plotted is shown in the upper right
corner of the plot.  The names of the subcells are centered in their
bounding boxes.  Of course, the output CIF generated by \wolcomp\ can be
read into \NEWOL, and viewed or modified there.

By now, programs in The \wolery\ have been used to do substantial designs
in all three technologies.  There are many more sophisticated members of
the {\bf PooH} family nearly ready to use.  Meanwhile, the simple programs
described in this document are a good example of which portions of a design
are naturally done in an interactive way, and which are more appropriate to
do as a language.  It sounds silly, but I know of no other system that has
got that issue right.  I hope the listeners in our far-flung radio audience
are enjoying the latest episode in the life of my favorite stuffed animals.
{\em They are so much more interesting than stuffed people!}

\medskip\leftline{\bf A Small Example}
The following example---a 6 bit pipeline multiplier---illustrates many of
the composition principles used in this style of design.  The variables
{\tt cell1}, {\tt cell2}, etc., are pointers to cells; {\tt x0}, {\tt y0},
{\tt x1}, {\tt y1}, etc., are integers.  All of these variables were
declared as globals in the program.

\wolcomp\ programs all follow the pattern shown.  First, all of the needed
cells are brought in.  Next, cells are defined in terms of smaller cells.
Finally, the entire design is defined as a cell, and brought into being
with the one naked {\em draw\/} command at the end.  This arrangement
produces CIF conforming to the ``one call convention'' described in certain
obscure books on the subject.

The cells {\tt rend}, {\tt lend}, {\tt lep1}, {\tt lep2}, {\tt rep1} and
{\tt rep2} are wiring cells, and contain no active elements.  The {\tt lco}
and {\tt rco} cells are the VDD and GND pads.  The multiplier itself is
made out of {\tt plbit} cells, which in turn are made out of subcells.  All
of the {\tt pd} and {\tt pad} cells are pads with drivers or static
protection.  The {\bf box} procedure is used to create two horizontal metal
wires that tie the VDD and GND busses in the pad ring between the two
center {\tt inpad} cells.  The number {\tt 3} is the wire coordinate
relative to the cell bounding box.  The {\tt 16} is the width of the wire.
The {\tt 4} is the spacing between the two wires.  The original design was
32 bits long, and was obtained by changing the 5 in the FOR loop to a 31.
The floorplan generated for this example by \wolcomp\ is shown in the
figure.


\subsection{\putindex{WOLCOMP Procedure Calls}}

In order to link in the \wolcomp\ module, the following file
should be searched, linked, and perm'ed:
{\tt
\begin{verbatim}
import
   $search '/LIB/WOLLIB/WOLCOMP/WOLCOMP'$  wolcomplib;
\end{verbatim}
}
   The following is a brief synopsis of the calling sequence for all the
routines in the current \wolcomp\ (version \#1.00).
\vspace{1cm}

\begin{flushleft}{\bf procedure getfile\rm(filename:strg);   }\end{flushleft}

    Load a single cell out of a .CIF file created with either WOL or NEWOL.
The file must contain \underline{one} geometry cell.  ``filename'' refers
to the name of the file that contains the cell.  If ``prefix'' has been
specified, that string will be pre-appended to ``filename'', thus providing
a facility to specify a search directory.  The cell will be added to the
internal symbol table.  If the CIF file contains a cell name (i.e.  user
extension 9), this name will be associated with the cell; otherwise, a cell
name will be generated from the supplied filename.

\begin{flushleft}{\bf procedure getcompfile\rm(filename:strg);}\end{flushleft}

    Load a file containing many cells.  These cells will be renumbered to
guarantee uniqueness and consistency within each top-level cell, and the
top-level cell will be added to the internal symbol table.  This is
intended for use as a MPC composition facility.

\begin{flushleft}{\bf procedure draw\rm(c:cptr);    }\end{flushleft}


    Draw the cell ``c'' at the position currently specified by x0, y0.  The
origin of the cell (usually the lower left corner) will be positioned at
x0, y0.  Upon return, the global variables x1, y1 will point to the upper
right corner of the cell that was just placed.


\begin{flushleft}{\bf procedure ndraw\rm(c:cptr; drawit:boolean);  }\end{flushleft}

     If ``drawit'' is TRUE, then this is the same as a call to ``draw'';
otherwise, the pointers x0,y0,x1,y1 will be updated, but no geometry will
be drawn.  This is very useful for testing compositions of large, repetitive
structures.


\begin{flushleft}{\bf procedure drawx\rm(c:cptr; tform:integer); }\end{flushleft}

    Draw the cell ``c'' at (x0,y0), but apply a transformation ``tform''
to it.  Possible transformations are:  

\begin{tabular}{ll}
      0 -& no transformation;                            \\
      1 -& rotate CCW by 90;                             \\
      2 -& rotate CCW by 180;                            \\
      3 -& rotate CCW by 270;                            \\
      4 -& mirror in the y-axis;                         \\
      5 -& mirror in the y-axis, then rotate CCW by 90;  \\
      6 -& mirror in the y-axis, then rotate CCW by 180; \\
      7 -& mirror in the y-axis, then rotate CCW by 270;
\end{tabular}


\begin{flushleft}{\bf procedure ndrawx\rm(c:cptr; tform:integer; drawit:boolean);}\end{flushleft}

    Same as ``ndraw'', but draws a transformed cell.


\begin{flushleft}{\bf procedure plot\rm(cell:cptr);}\end{flushleft}

    Plot out a cell, either to screen or to pen plotter.

\begin{flushleft}{\bf function  cell\rm(name:strg):cptr; }\end{flushleft}

    Lookup cell named ``name'' in symbol table, and return a pointer which
can then be passed to ``draw'', ``drawx'', etc.

\begin{flushleft}{\bf procedure define\rm(name:strg);  }\end{flushleft}

    Start the definition of a composition cell.


\begin{flushleft}{\bf procedure endef;         }\end{flushleft}

    Close the definition of a composition cell.


\begin{flushleft}{\bf procedure box\rm(c:strg);}\end{flushleft}

  Draw a box on layer ``c'' from (x0,y0) to (x1,y1).

\begin{flushleft}{\bf procedure set\_up;}\end{flushleft}

   Should be called first to set up all \wolcomp\ internals.  This
sets a default ``prefix'' (null), and ``lambda'' (1.5 microns).
If a different lambda is desired, it should be changed (by assignment
to the exported variable {\bf lambda}) \underline{after} {\bf set\_up} is
called. Remember:  {\bf lambda} is in hundreths of microns.
Similarly, {\bf prefix} should be set after {\bf set\_up} is called.

\begin{flushleft}{\bf procedure shut\_down;}\end{flushleft}

  Closes the output file, and optionally plots a floorplan for
a generated cell.  The floorplan can be drawn on either the
screen or a pen plotter.  Also, the internal symbol table can
be displayed (useful for seeing how large cells are).

\begin{flushleft}{\bf procedure dumplist;}\end{flushleft}

    Prints out the internal symbol table.  This is primarily a
debugging aid for \wolcomp\ maintainers.

\begin{flushleft}{\bf procedure set\_mbb\rm(llx,lly,urx,ury:integer); }\end{flushleft}

    Forces the MBB of a composition to be set to the specified values.
This is primarily useful for handling non-WOL generated CIF, in conjunction
with the {\bf cif\_type} attribute.

\begin{flushleft}{\bf procedure load\_library\rm(filename:strg); }\end{flushleft}

   Reads a file containing a composition cell, and inserts all contained
geometry cells into a ``library table''.  If the global variable
{\bf search\_library} is {\bf true}, any subsequent calls to
cells with names that match that of a cell in the library will cause
a call to the library cell to be generated, instead of the supplied cell.
This is most useful for commonly maintained cells such as pad libraries,
etc.

\begin{flushleft}{\bf function  lam\rm(x:integer):integer;}\end{flushleft}

    Returns the value of {\bf x} lambda in \wolcomp\ internal units.
This is the recommended way to incorporate fixed (i.e. non-relative)
offsets.  (e.g.  x0 := x1 + lam(4);  would cause the two cells
to be separated by 4 lambda).

\begin{flushleft}{\bf function  fix\_name\rm(fname:strg):strg;}\end{flushleft}

    Fix up file names.  You should never have to use this.

\paragraph{Routing wire primitives}

\begin{flushleft}
       \bf procedure width \rm (x : integer);      \\
       \bf procedure wire \rm (layer : strg; startx, starty : integer);   \\
       \bf procedure x \rm (delta : integer);        \\
       \bf procedure y \rm (delta : integer);        \\
       \bf procedure dx \rm (delta : integer);       \\
       \bf procedure dy \rm (delta : integer);       \\
       \bf procedure xy \rm (x, y : integer);        \\
       \bf procedure dxdy \rm (deltax, deltay : integer);  \\
       \bf procedure endwire;     \\
\end{flushleft}

  These routines allow routing wires to be included in WOLCOMP-generated
cells.  All dimensions are specified in WOLCOMP internal coordinates
(basically, 1$\lambda$~=~2~units, and the cell origin is in the lower left
corner).  The width of the wire is set by {\bf width}; the wire is started
by a call to {\bf wire} with the layer (pass the CIF layer name--for
example, metal in the SCG technology is CMF--and the start coordinates of
the wire).  The procedures {\bf x}, {\bf y}, and {\bf xy} set the next
corner of the wire to have that x,y and (x,y) coordinate, respectively.
The procedures {\bf dx}, {\bf dy}, and {\bf dxdy} are analogous, but are
passed the {\em relative} displacement of the next vertex from the current
point.  To terminate the wire, call {\bf endwire}.


\vspace{1cm}
\centerline{\bf Exported Variables }
{\tt 
\begin{verbatim}
EXPORT
TYPE
   strg = string[80];
   strng10 = string[10];
   cptr = ^cel;
   sptr = ^subcel;

   cel = record
          name : strg;
          lx, ly, cifnum  :integer;
          next : cptr;
          contents : sptr;
       end;

   subcel = record 
              cell : cptr;
              x, y, xfrm : integer;
              next : sptr;
            end;

   cif_types = (LYON, TELLE, WOL);

VAR
        { cell position, last cell position   }
   x0, y0, x1, y1 : integer;

        { value of lambda in 1/100 of microns }
   lambda : integer;

        { type of CIF being parsed            }
   cif_type : cif_types;

        { should the library be searched for each subcell? }
   search_library : boolean;

        { if true, print cell list on line printer }
   print_cells : boolean;

        { filename prefix to specify directories }
   prefix : strg;

\end{verbatim}}

