\newpage
\section{Running \NEWOL\ - The menu system}

     \NEWOL\ originated on the HP 9836C ``Chipmunk'' series of computer
with the HP 9111A graphics tablet attached.  A version that runs on the
``Bobcat'' machines is also available, and can use either their graphics
tablets or the mouse.  

     The \putindex{command-line syntax} of the \NEWOL\ command is:

     {\tt wol [-u$<$username$>$] [-t$<$tech$>$] [-q]
           [file1 [file2 ...]]}

     where
     \begin{description}
       \item[{\tt -u$<$username$>$}] \NEWOL's first action is to load a
         configuration file specifying technology, size of ``lambda'', and
         several internal mode settings.  The ``-u'' flag loads the initial
         configuration file belonging to user $<$username$>$.
       \item[{\tt -t$<$tech$>$}] Load the technology file {\tt
         $<$tech$>$.WOL}.  Only layers and colors are defined in this file;
         the size of ``lambda'' may have to be set explicitly.
       \item[{\tt -q}] Initiate quiet start-up.  The message-of-the-day is
         not displayed, and neither is the status of CIF I/O operations.
     \end{description}


     \NEWOL\ uses menus extensively to display and select all functions,
and understanding the menu system is crucial.  When invoked with no
filename arguements, \NEWOL\ comes to life displaying the OPTS menu (which
contains the commands to load and save project files).  If a project
filename was specified on the command-line, \NEWOL\ starts off in the MAIN
menu.

     The \NEWOL\ display is really quite simple.  There are three areas on
the screen.  The first of these is the \putindex{menu area}, consisting of
the group of cyan colored boxes at the top of the screen.  Moving the
cursor (which follows the pen on the pad) to one of these menu squares, and
pushing the pen down causes \NEWOL\ to initiate whichever function the menu
box represents.  Some of these functions are {\em \putindex{actions}} (the
function executes immediately, then returns); others are {\em
\putindex{modes}} (which affect the operation of a subsequent action or pen
operation).  When you select a mode menu square, it is turned to purple---to
show you what you have selected.  The color of the printing in the menu
boxes also has meaning.  Selecting a box with red writing will move you to
another menu, and yellow boxes represent file operations.

     The second area of the screen is the large area underneath the menu
boxes.  This is the so-called \putindex{$\lambda$-grid}, which
is the working area on which \NEWOL\ draws its pictures.  Notice that as
you move the pen around the grid that it seems to jump around.  This is
because the grid is in fact a real grid.  There are distinct points on the
grid, and the cursor (and the corners of all \NEWOL\ objects) can only be
located on a grid point.  \NEWOL\ allows you to zoom in and out, and
therefore when you move closer, the grid points are further apart.  The
zoom factor can be set by various ``keyboard commands''.

     It is worth mentioning here that \NEWOL\ uses a ``window'' system for
the $\lambda$-grid.  What you see in the grid area at any one time is only
a small portion of the whole area that can be filled with cells.  The ZOOM
and SCROLL functions allow you to move the window, to view different parts
of your work. 
 

     The last area on the screen is the \putindex{status area}.  This is
the little box in the upper right hand section of the screen.  \NEWOL\ uses
this area to communicate the state of the system.  Right now, there should
be a colored square (the current drawing layer), and the name of the
current menu (Main or Opts).  There will be more on the status area later.
Notice that the cursor can not be moved into the status area.  This is a
special reserved area, and {\em cannot} be used for drawing.

     There are several menu squares which have no writing in them.  These are
extras and will be filled with functions later.  For now, selecting them
will have no effect.

     Moving around to the various menus in \NEWOL\ is really very simple.
Menus are hierarchically organized by function of their contained
operations, and all of the sub-menus have a menu square called `MAIN' which
will send you back to the main menu.  Thus, you are always within a few
pen pushes of any menu in \NEWOL.

\subsection{Text pull-down menus}

   Specification of cell and file names is done textually, with the
optional assistance of pull-down menus listing possible choices\index{text
pull-down menus}.  The text prompt for the name contains several fields
which can be highlighted by using the pen.  In particular, a default
response is supplied (generated by the last cell/file name provided by the
user) and is selected either with the pen or by pressing ENTER.  An ABORT
option is also provided.  The last option is to press or type ``?'', which
will pull down the full menu.  Here, names are selected with the pen, or,
if you wish to supply a name which is not in the menu, simply by typing the
name at the keyboard (followed by ENTER).  An ABORT option is also located
in the menu.

   Rather than type ``?'' at the first text prompt, the user may wish to
directly enable the pull-down menu as a default action.  This is specified
in the INFO.WOL configuration file, by setting the \putindex{short
file/cell name prompt} variables appropriately.

\subsection{Keyboard commands}

   Several commands, in particular those that affect the graphics state of
\NEWOL\, are available at all times by pressing keys on the keyboard.  This
provides a shorthand mechanism for sophisticated users to quickly perform
common operations.  Typing ``?'' will print a
short \putindex{help} screen describing most of the keyboard commands.

\subsubsection{Selection commands}

   The \NEWOL\ algorithm for selecting objects\index{selection algorithm}
on the screen is based on a hierarchical data representation in the
geometry buffer.  Boxes are considered to own boxes which they entirely
contain.  Many operations (move, delete, etc.) can be performed on the
entire hierarchy at once.  The selection algorithm is concerned with
identifying the subtree of boxes that correspond to the pen being pressed
at a particular location.  The algorithm is straight-forward:  \NEWOL\
tries to grab the {\em smallest} object which completely surrounds the
cursor point (and of course, any children of that object), {\em unless} the
cursor falls on an {\em edge}, in which case \NEWOL\ tries to grab the {\em
largest} box with an edge on the cursor.  A few experiments will quickly
teach the user how this mechanism can be used to operate on various
structures.

An ambiguity exists in the case of two partially overlapping boxes; neither
one contains the other (they are siblings in the hierarchy).  In this case,
an arbitrary (but deterministic) choice is made by the selection algorithm.
In these cases, when it is difficult or inconvenient to unambiguously
select a given object, two mechanisms are provided to help steer the
selection algorithm:
\begin{enumerate}
\item The algorithms can be made principally selective to edges (as
   opposed to interiors of boxes) by pressing the ``E'' key.  If the
   search for an edge fails, the selection algorithm reverts to considering
   interiors of boxes, as before.  The ``E'' key toggles this
   \putindex{edge-priority selection} mode.
\item The select algorithm can by cycled repeatedly,
   indicating in sequence ALL of the selectable objects at a given point.
   When the desired object is highlighted, the pen is
   pressed (as in a normal selection operation), to actually perform the
   selection.  Lifting the pen at any point aborts the select process
   altogether. Running down the list of selectable objects is performed
   by pressing the \putindex{EXECUTE} key; the list itself is cyclic.
   The EXECUTE key sends a CTRL-C character.
\end{enumerate}

  Because it may not always be desirable to operate on all members of the
sub-hierarchy at once, various means are provided to disable its effect.
If the select algorithm is run in \putindex{ONE mode}, only a single box is
selected; all of its children are left untouched.  This mode may be made
the default by selecting the \putindex{disable heirarchy} option in either
the OPTS menu of the INFO.WOL configuration file.  The EXECUTE key and
edge-priority select mode are still operational in ONE mode.

    The converse is also true: sometimes the heirarchy is inadequate,
as one may want to operate simultaneously on several unrelated objects.
To this end, a \putindex{SELect box}  can be drawn; all boxes
that are entirely contained within the box are selected.  Boxes are
never broken; boxes that partially overlap with the SEL box are not selected.


\subsubsection{Viewing commands}\index{viewing commands}

\NEWOL\ has two main buffers (see {\em geometry buffer} and {\em composition
buffer}); each buffer has its own window representing the current viewing
transformion.  Moving between the buffers in no way changes the windows.
\NEWOL\ maintains a {\em stack} of ``graphics state'' records, including
such information as windowing transformations and zoom factors.  Separate
stacks are maintained for the geometry and composition buffers.
\begin{description}
\item Z -- \putindex{zoom to window}.  \NEWOL\ will ask the user to draw a
   box, which will then be used as the next viewing window (it will be fit
   as best as possible on the screen, without distorting the aspect ratio).
   As usual, lifting the pen while drawing the box aborts the operation,
   and leaves the window unchanged.  The old transform is pushed onto the
   stack.
\item ``+'',``--'' -- double and halve the \putindex{zoom factor},
   respectively, leaving the coordinate of the center of the screen
   unchanged.
\item 5 -- zoom back to top level.  Fits the entire contents of
   the buffer on the screen at once, setting zoom and center appropriately.
\item @ -- center viewing window.  Prompts for lambda coordinates on which
   to center the window.
\item \putindex{arrow keys} (and \putindex{wheel}) 
        -- scroll the screen in increments of 1/20 screen.
\item 8,2,6,4 -- scroll\index{SCROLL} the screen by one page 
        in N,S,E,W directions, respectively.
\item ``)'' -- explicitly PUSH a viewing transform onto the stack.  The user is
      asked to draw a zoom box (as for the Z command) for the new
      transform, but the current transform is left unchanged.
\item ``\^\ '' -- POP the viewing tranform stack, redrawing the screen as required.
\item ``('' -- exchange the top two tranforms.  This is especially useful for
      jumping back and forth between two widely separated sections of the chip.
      Remember that the current transform is usually not yet on the stack.
\item ``.''  -- PUSH the current transform onto the stack.  Usually used
      prior to the `)' command.
\end{description}

\subsubsection{Display commands}\index{display commands}

\begin{description}
\item R, {\em space} -- force a \putindex{screen refresh}.
\item F -- toggle display of boxes as filled regions.  This is very
    convenient for examining connectivity, but outline boxes are often
    more useful for editing (where you need to see the edges).
\item A -- toggle auto-refresh mode.  \NEWOL\ tries to minimize the number
    of screen refreshes that are made, but even so this may slow down
    experienced users (especially when doing several edits in rapid succession).
    In these cases, it is convenient to turn off the auto-refresh, and live
    with a somewhat inaccurate or messy display.  When required, refreshes
    can be forced by pressing the space bar.
\item Y -- draw a single ruler\index{RULER} (Yardstick).  The user is asked
    to select two points; a rubber-band ruler is drawn between them, and
    the distance in lambda is printed (if a decimal point is present in the
    distance value, a non-integral distance was measured).  One ruler is
    drawn for each time ``Y'' is pressed; the rulers remain on the screen
    until the next refresh.
\item TAB, BACKTAB -- cycle through the different display styles.
\item = -- display coordinates.  The (x,y) coordinates of the pen in lambda
    units are displayed in the lower right corner of the screen.  This feature
    (and the ``@'' command described above) is particularly useful in
    locating features found by some other program (e.g. an extractor, or DRC).
\item D -- toggle \putindex{display ports mode}.  When enabled, ports are
    drawn as dotted sides on the appropriate box.
\item W -- toggle \putindex{wide routing} mode.  When enabled, routing wires
    are drawn actual width; when disabled, only centerlines are drawn (more
    convenient for editing).
\item M -- toggle \putindex{Manhattan routing} mode.  When disabled,
    arbitrary angle routing is permitted.
\item C -- clear alpha screen.
\item G -- regenerate graphics screen.  This is more extensive than a
    simple refresh, in that the menus are regenerated as well.
\end{description}

\subsubsection{Filing operations}\index{filing operations}

\begin{description}
\item L -- load a CIF file.  The user is prompted for the name of
   the CIF file (the pull-down filer menu is NOT available here).
\item S -- save a CIF file.  The user is prompted for the name of
   the cell to save, and the file to save it in.
\item P -- enable the pull-down menus as defaults for LOAD, SAVE, NEW, MAKE
   operations.
\end{description}

\subsubsection{Other operations}
\begin{description}
\item !  -- \putindex{shell escape}.  Puts the user in a sub-shell.  When
   the sub-shell is exited (by typing {\em exit} or CTRL-D), the user is
   back in \NEWOL.
\item \# -- execute a program from inside \NEWOL.  The user is prompted
   for the program name.
\item CTRL-G -- enter the \putindex{gripe system}, to submit/examine bug
   reports to the \NEWOL\ maintainer.
\item CTRL-W -- make suggestions for high-level improvements to
   design tools (i.e. the next generation of \NEWOL).
\end{description}


\subsection{The Main menu}

     The \putindex{main menu} is the simplest menu in \NEWOL.
There are only two actions the user can take from this menu.  The first is
to press the far right menu square and leave the program.

     The other is to press one of the other filled menu squares.  This will
cause \NEWOL\ to send you to the appropriate sub-menu.  These sub-menus,
and their basic functions, are:

\begin{tabular}{ll}
\putindex{LAYER} & Specify a mask layer to draw geometry \\
\putindex{BUILD} & Edit geometry cells  \\
\putindex{ELEC}  & Specify electrical node names and ports of geometry cells \\
\putindex{CELL}  & Maintain the list of defined geometry cells \\
\putindex{COMP}  & Edit and manage composition cells \\
\putindex{OPTS}  & File loading and saving, and setting \NEWOL's internal state \\
\putindex{DBUG}  & Provide support for program maintainers \\
\putindex{EXIT}  & Leave \NEWOL.  If changes have been made, you will be warned
\end{tabular}

\subsection{The Layer menu}


     This menu\index{layer menu}\index{changing layers} allows the user to
select the layer of the next box(es) to be drawn.  Each of the layers
available is shown, and the text for each is in the color of the layer.
Note:  These layer text names and colors can be set by the user (see
{\em technology files}).  The number of available layers is also
determined by the technology being used.

     Pressing one of the layer boxes has two effects.  First, it changes
the current drawing layer to the one selected (this is denoted by the color
box in the status area changing color).  Also it moves the user from the
Layer menu to the Build menu and puts \NEWOL\ into ADD
mode, ready to draw a box.

     The grid area shows the current geometry buffer while in the layer menu.



\subsection{The Build menu}


     The Build menu\index{build menu}\index{drawing geometry} is the menu
which allows you to draw and edit {\em geometry cells}.
The menu squares perform the following functions:
\begin{description}
\item[\frameindex{ADD}] This menu square puts you in ADD mode, allowing you
   to add boxes to the geometry.  While this menu square is selected (purple
   in color), pressing the pen down anywhere on the pad will select the
   first corner of the new box.  After you pick the pen up, moving the pen
   around will make \NEWOL\ create a ``\putindex{rubber-band box}'' (RBB).
   This rubber-band box is not permanent, but is there to help you decide
   where it is that you want the other corner of the box to be.  When you
   have put the pen where you would like the other corner of the box,
   simply press the pen down again.  The box will then become a permanent
   part of the geometry of the cell.  If, while drawing the RBB for the
   box, you decide that you would like to forget about drawing this box,
   simply lift the pen away from the tablet.  This operation {\em
   aborts}\index{aborting commands} most commands, not just ADD.
   Alternately, pressing the pen down in the menu area will also abort the
   operation.
\item[\frameindex{MOVE}] This menu square allows you to move boxes
   around the screen.  While in MOVE mode, pushing the pen down on the grid
   area will select an object to move.  When you lift the pen, the object will
   follow the pen around until the pen is pushed down again.  If you do
   not wish the object to follow the pen around while MOVing (e.g. if the
   screen refresh is too slow), use ``\putindex{point-to-point move}'' by
   pressing the ``V'' key on the keyboard.  In this mode, select the object
   to be moved by pressing the pen as before, then go to the new location
   of the object and press the pen again.
   \begin{enumerate}
    \item Note that while in MOVE mode, a word appears in the right of the
       status area.  This shows the MOVE sub-mode.  There are three
       sub-modes:  ALL, ONE, SEL.  Repeatedly pressing the MOVE menu square
       will cause \NEWOL\ to change its sub-mode.  Do it several times and
       see what happens.  The sub-modes have the following meanings:  ALL
       means that the selected shape {\em and all shapes which are entirely
       inside of it} will be moved around the screen.  ONE mode means that
       just the one shape selected will be moved.  SEL (Select) is a bit
       more tricky.  If you are in SEL mode, \NEWOL\ will wait for you to
       go to the pad area and press the pen down twice - drawing, in the
       process, a rubber-band box.  Everything which is completely inside
       of this select box will be moved with the cursor.
    \item If the {\em corner} of a box is selected in MOVE ALL or ONE mode,
       no move is performed.  Rather, a rubber-band edit of that corner of
       the box is done (this feature reduces the number of times you have
       to enter EDIT mode (below) for little corrections).
    \item MOVE mode has one further subtlety:  when in MOVE ALL or ONE
       modes, if the pen is dragged while depressed in selecting an object,
       a SEL rubber-band box will be drawn, and the system is (temporarily)
       in SELect mode.
   \end{enumerate}
\item[\frameindex{DEL}]
   This mode allows you to delete boxes from the geometry
   buffer.  Like MOVE, DEL has three modes (ALL,ONE,SEL) and they allow you to
   delete a shape and all of its contained shapes, just the shape itself, or
   a selected region of the buffer.
\item[\frameindex{COPY}]
   Copy allows you to make a copy of a box or boxes and then move
   the copy around the screen.  Like the previous two options, you can COPY a
   shape and all of its included shapes, just the one shape, or all of the
   shapes in a select box.  Once you have picked up the object to copy, you
   drag it around by moving the pen, and put down copies by pressing the
   pen.  Multiple copies can be placed with multiple presses;  lift the
   pen from the tablet when you are finished copying that object.
\item[\frameindex{EDIT}] 
   This option allows you to select one side of a box, and move that {\em
   whole} side in or out.  While the menu square is selected, to use EDIT you
   move to the {\em edge} of one of the shapes on the grid.  Pressing the
   pen down selects that edge.  Now the side will follow the pen.  Pushing
   the pen down again selects the new position of the edge.  See the
   MOVE command for a rubber-band edit of the corner of a box.
\item[\frameindex{UNDEL}]
   This option allows you to bring back objects that had been deleted with
   the delete option.  Moving the pen up to the UNDEL menu square and pressing
   it causes the last deleted object(s) to reappear (in their last
   position).  It does not matter how many boxes were deleted (or with
   which sub-mode), they all come back.  Pressing the UNDEL box again will
   cause the boxes deleted before that to come back. In all, five
   objects can be brought back with the UNDEL.  So if you delete six
   objects in a row, only the last five to be deleted can be brought back.
\item[\frameindex{ZOOM}] This option allows you to select how fine the
   $\lambda$-grid is.  When ZOOM is selected, \NEWOL\ will tell you what
   the current zoom factor is (i.e.  how many screen pixels correspond to
   $1\lambda$), and will then ask for the new zoom factor.  Zoom
   factors are most useful when integers $\geq$ 1, but non-integral zooms
   are permitted (primarily for viewing purposes; it is virtually
   impossible to select objects when the pen grid and the $\lambda$-grid do
   not line up).  \NEWOL\ will then redraw the buffer for you, zooming
   around the center of the screen.  If, instead of typing a number at the
   text prompt, the user draws a box on the screen, \NEWOL\ will try to
   zoom to that window (this operation is the same as the ``Z'' keyboard
   command\index{zoom to window}).
\item[\frameindex{MAKE}]
   This is how you define the geometry buffer into a cell name.  After you
   MAKE a cell, it exists in memory, independent of the GEOM buffer and can
   be used both in geometry and composition operations.  {\em Until MAKE is
   done, your edits in the GEOM buffer are transient, as they were done on
   a {\em copy} of the cell; the MAKE operation overwrites the old entry
   with the GEOM buffer contents}.  When you press the MAKE menu square,
   \NEWOL\ asks for the name of the cell.  NOTE:  Only one cell can have a
   given name.  Cells names can be up to 12 characters long, so use names
   that mean something!!  After \NEWOL\ asks for the name of the cell, it
   offers you two options for making the cell.  If you want this cell to
   have the \putindex{minimum bounding box} (MBB) defined by its geometry,
   press the pen down again in the MAKE menu square.  If you wish to define
   your own bounding box (which must be {\em larger} than the MBB), then
   move the pen to the grid, and push the pen down twice to denote the
   corners of the bounding box.  Like before, if you decide not to make the
   cell (or you don't like the bounding box), and you are drawing the RBB
   of the bounding box, just lift the pen or move the pen up to the menu
   area and press it down.  Like before, the box will go away, and the cell
   will not be made.
\item[\framebox{LAYER}] Go to the layer menu.  Once you select a layer,
   you will be returned to the BUILD menu.
\item[\framebox{MAIN}]  Go to the main menu.
\end{description}

\subsection{The Cell menu}

     This menu allows you to define geometry cells, and to manipulate them.
Since it deals with geometry cells, it shows the current geometry buffer in
the grid area.  The menu squares have the following effects:
\begin{description}
\item[\frameindex{MAKE}]  Same as MAKE in the Build menu.
\item[\frameindex{LIST}]
   Pressing this menu square will cause \NEWOL\ to list the geometry cells
   (including the GEOM buffer) that it knows about.  For each cell, it will
   list the name of the cell, the cell type (GEOM), the height, and the width.
   If there are more cells defined than will fit on the screen, don't worry,
   just hit return and the rest of the cells will be shown.
\item[\frameindex{APPEND}] Pressing this menu square will cause \NEWOL\ to ask
   you for the name of a geometry cell.  It will then ask you to press the
   pen down on the grid on the location of the lower left hand corner of
   the cell.  \NEWOL\ will then take a copy off that cell and add it to the
   buffer.  NOTE:  This is {\em not} composition.  Appending a cell to the
   buffer takes a copy of the geometry in a cell and integrates it into the
   buffer's data tree.  Once this operation is over, there is no way to
   tell that any of the boxes in the buffer came from another cell.
   It is exactly as if the user had ADDed each box by hand in the BUILD menu.
\item[\frameindex{NEW}] This operation is done immediately prior to
   editing a cell, and causes the cell to be copied into the GEOM buffer.
   \NEWOL\ will ask for the name of a geometry cell, using the cell lister
   menu.  \NEWOL\ will then clear out the GEOM buffer, and move a copy of
   the named cell into the buffer.  It also will change the viewing window
   to scale the new cell to the proper size.  Remember that after the new
   copy of the named cell has been moved to the GEOM buffer, it has no
   relation to the cell in memory.  Editing the buffer will only change the
   buffer, not the cell from which the copy was made.
\item[\frameindex{ERASE}] This allows you to erase the cell definition of a
   cell in memory.  The cell's space in memory will be collected for future
   use.  NOTE:  A cell cannot be erased if it is used in the definition of
   any composition cells (i.e.  if it is called by any other cell).
\item[\frameindex{CLEAR}]  Clears the geometry buffer.  The user is warned
   if the buffer contains a cell which has been modified but not saved.
\item[\frameindex{PLOT}]  Plots the contents of the GEOM buffer to
   a HPGL plotter.
\item[\framebox{ZOOM}]   Same as ZOOM in Build menu.
\item[\framebox{MAIN}]   Return to main menu.
\end{description}

\subsection{The Elec menu}

     This menu provides means to geometrically transform boxes,
and to name nodes and ports.  The latter two features are primarily
used by subsequent tools (extractors, automatic routers, DRCs), as
means to identify boxes.

\begin{description}
\item[\frameindex{ELEC}] Names a box, prompting for a string.  The name is
  saved in the .CIF file using the ``{\tt 86 $<$name$>$ ;}'' extension.
\item[\frameindex{XFORM}] Similar in concept to XFORM in the composition
  buffer.  See the description there.  There are no XFORM ONE or SEL modes,
  transformations apply to ALL the selected object(s).
\item[\frameindex{RULER}] Enter yardstick mode; press a menu square to
  exit.
\item[\frameindex{PORT}] Define one edge of a box as a {\em port}.  When
  \putindex{display ports} mode is set, ports are visible as dashed edges
  in the geometry buffer, and as solid lines in the composition buffer (in
  the latter, they are visible even when the geometry cell is poked shut).
  The PORT command will wait for a box to be selected, then prompt for
  which edge (N,S,E,W) and a port name.
\item[\framebox{DRC}] Enter the design-rule checker.
\item[\framebox{BUILD}] Return to Build menu.
\item[\framebox{MAIN}] Return to Main menu.
\end{description}


\subsection{The Composition Menu}

     This menu allows the user to compose (by abutment) as many cells as
he/she would like.  They can have any orientation, and can be repeated
many, many times.  The composition menu has its own buffer (*COMP*), and its
own window to view it with.  These are independent of the GEOM buffer and
window.

     It is very important to understand how \NEWOL\ does its composition.
Each composition cell (including the COMP buffer) is made up of $0-n$
instances of other cells.  Each instance is an exact map of that other
cell.  Therefore, if you later go and change the cell from which the
instances get their definition, you will also change these instances, and
therefore change the composition cell.  The menu squares perform the following
actions:
\begin{description}
\item[\frameindex{ADD}]
   This option allows you to add an instance of either a composition or
   geometry cell to the buffer.  \NEWOL\ will ask you for the name of the
   cell, and then will ask you to push down the pen on the grid where you
   would like the lower left corner to be.  Don't worry if it's not quite
   right, you can always move the instance later.  \NEWOL\ tries to fit as
   much of the name of the cell as possible into the box on the screen.
\item[\frameindex{MOVE}]
   This allows you to move instances around the screen.  As long as the
   MOVE menu square is lit, pressing the pen down on the grid will select an
   instance to move.  Once the pen is lifted, the instance will follow the
   pen around until it is pressed down again.  Unlike the build menu, you
   can only move one shape at a time.  However, the \putindex{EXECUTE}
   select mechanism still works in the composition buffer.
\item[\frameindex{DEL}]
   This allows you to delete instances that are on the screen.  While the
   DEL menu square is lit, selecting a shape on the grid deletes it from the
   COMP buffer.  NOTE:  There is {\em no} undelete buffer for composition.
   You can simply ADD the cell back.
\item[\frameindex{COPY}]
   Allows you to copy an instance, and move the copy around.
   When you press the pen down again, the copy stops moving, and is added to
   the buffer.  Again, successive presses put down multiple copies;
   lift the pen to abort.
\item[\frameindex{POKE}]
   Pressing the POKE menu square takes you to the POKE sub-menu, which is used
   to view the contents of subcells in the composition buffer.  If the cell
   is a geometry cell, you will see the geometry in the cell.  If it is a
   composition cell, you will see the cells which make up the composition
   cell.  This operation is recursive, and can be repeated on the newly
   revealed cells.  NOTE:  This is just for looking at how the compositions
   line up, {\em NO} editing can be done on the contents revealed with a
   POKE.
\item[\frameindex{MAKE}]
   When pressed, MAKE asks you for the name of the cell you wish to make.
   A copy of the composition buffer is then put into memory with that name.
   NOTE:  The bounding boxes of compositions are always the minimum size.
   Unlike geometry cells, they cannot be set.
\item[\frameindex{DRAW}] Enter the point-to-point routing menu (see below).
\item[\frameindex{NEW}]
   This does just the same as the NEW function on the Cell menu.
   It clears the composition buffer and moves a copy of a new cell into the
   buffer.  Also, it scales the window to the proper size.  This is the
   first step to editing an existing cell.
\item[\framebox{OTHER}]
   Since there are too many things to do for composition, there are two
   comp menus.  Hitting OTHER causes \NEWOL\ to alternate between them.
\item[\framebox{MAIN}]  Returns back to main menu.
\end{description}

\paragraph{OTHER menu}
\begin{description}
\item[\frameindex{XFORM}]
   This menu square allows you to rotate and mirror the instances in the COMP
   buffer.  Note that when this menu square is lit that a word appears in the
   right of the status area.  This shows the current transform, and can be
   changed by repeatedly hitting the menu square.  The transforms are:  Rotate
   by 0, 90, 180 and 270 degrees, and mirror the X coordinates, mirror the
   Y coordinates, mirror in the line X=Y, and mirror in the line X=-Y.  The
   transforms are all done around the center point of the instances, and
   the transform is applied by pressing the pen in the grid area inside of
   one of the instances.  Since all of the transforms look like one of two
   boxes, \NEWOL\ uses different colors to denote the different transforms.
   Here are the transforms (and the strings displayed):
\begin{verbatim}
   Rotations:   null = 0 = white;  R90  = red;
                    R180 = green;  R270 = amber;
   Reflections: m(x=0) = MX = blue;  m(x=-y) = M-XY = purple;
                m(y=0) = MY = cyan;  m(x=y)  = MXY  = brown;
\end{verbatim}
\item[\frameindex{ERASE}]
   When called, ERASE asks for the name of a cell to erase.  It will remove
   the cell entirely from memory.  NOTE:  Like before, if the named cell is
   used elsewhere, \NEWOL\ will not let you erase it.
\item[\frameindex{ZOOM}]
   Just like before, but it zooms the composition window.
\item[\frameindex{ARRAY}] A fast means to lay down multiple instances of a
   cell.  ARRAY asks for a ``basis'':  two cells must be selected (by
   pressing the pen on them), and a replication factor, N, is requested.
   Then, N-2 instances of the {\em second} basis cell will be placed,
   separated by the distance between the two basis cells.
\item[\frameindex{NAMES}] Analogous to the NODES command in the geometry
   buffer, NAMES allows unique names to be given to different instances of
   the same cell.  The instance name is written out in the .CIF file using
   the {\tt 85 $<$name$>$ ;} extension.
\item[\frameindex{LIST}]
   This option lists all of the composition cells that \NEWOL\ has stored
   in memory.  The listing is different than that for geometry cells,
   though.  For each cell, the name, cell type, height, and width is
   listed.  Also is listed the instances that are in the cell.  The
   instances are listed in cyan, and are inset.  Also, for each instance,
   its transform is also listed.
\item[\frameindex{PLOT}] Plot the contents of the composition buffer.
\item[\framebox{OTHER}] Switches to the other comp menu.
\item[\framebox{MAIN}]  Back to the main menu.
\end{description}

\subsubsection{The Poke sub-menu}

   The Poke menu provides a means to view the contents of subcells within
the composition buffer.  It is important to remember that cell {\em
editing} is only performed at the {\em top} level of the hierarchy.  Thus,
you cannot modify the contents of cells that you ``open up'' via the poke
command; rather, you must ``NEW'' those cells into the appropriate buffer,
and modify them there.

\begin{description}
\item[\frameindex{POKE}] This is the default action; the first time a cell
   is POKEd, it is opened up by one level in the hierarchy, revealing any
   cells that it contains.  If these sub-cells are POKEd, {\em they} open
   up to reveal their contents.  Finally, if a geometry cell is POKEd open,
   and is then POKEd again, it closes itself; this repeats all the way up
   the hierarchical tree (on successive POKEs), until the original cell is
   POKEd shut.
\item[\frameindex{TOP}]  Immediately closes all poked open cells.
\item[\frameindex{BOTT}] When pressed the first time, all cells are opened
   {\em down to the geometry level}.  The geometry cells are not opened
   until BOTT is pressed again; at this point, all geometry is displayed.
   Subsequent presses alternate between these two states.
\item[\framebox{RULER}] Enters yardstick mode; press any menu button to exit.
\item[\frameindex{PLOT}] Plot the contents of the composition buffer on an
   HPGL plotter.  The ``poked'' status of the cells is the same as they
   appear on the screen.  Also, the current directory is searched for a
   \putindex{LABELS.TEXT file}, which contains the (x,y) position (in
   lambda) and a label string to plot.
\item[\frameindex{EDIT}] This command provides a shortcut to editing
   geometry cells.  After pressing the menu button, select a geometry cell
   to be edited.  The cell will automatically be ``NEW''ed in the geometry
   buffer, which will be made the current buffer.  When the editing is
   complete, press ``POP'' in the Build menu (in the menu square which used
   to be occupied by ``MAKE''); the cell will automatically be Made, and the
   user is returned to the composition buffer.  Should the user wish to
   abort this editing sequence, going from Build to Main causes the 
   \putindex{POP} button to revert to MAKE.
\item[\frameindex{LAYER}] Causes a sub-menu to be entered in which only
   selected layers are displayed.  This is often convenient for design rule
   checking.  Pressing the pen in the main display window causes a return
   to the Poke menu.  NOTE:  any cells saved to a .CIF file while in this
   menu will only contain the mask layers that were being
   displayed.\index{saving selected layers}
\item[\frameindex{XTRACT}] Enters the network extraction sub-menu.
\item[\framebox{COMP}] Return to the composition menu.
\item[\framebox{MAIN}] Return to the main menu.
\end{description}

\subsubsection{The \NEWOL\ extractor}\index{topology extraction}

   To provide connectivity and topology verification, \NEWOL\ contains an
extractor that locates all transistors and generates a netlist of their
interconnection.  This netlist can then be compared, via the
\putindex{NETCMP} program, to that generated via a schematic capture
system.

   In order to maximize its versatility, \NEWOL's extractor operates on a
{\em flattened} representation of the geometry.  Memory limitations
consequently limit extraction to chips of under 20K transistors.  For chips
within this limit, the extractor is exceptionally fast, making use of
box-level and cell-level information together with a bin-sorting algorithm
to yield a speedup factor of 100+ over pixel-based extractors.

   Once the chip has been extracted, the connectivity information that has
been generated can be displayed interactively.  Entire electrical nodes can
be highlighted, and estimates of their area and electrical capacitance
can be made.

\begin{description}
\item[\frameindex{XTRACT}] Extract the cell currently loaded into the
   composition buffer.  It is {\em vital} that this cell be freshly loaded
   (via a ``NEW'' command) into the buffer.  You will be prompted for a
   file name for the .NTK output file.
\item[\frameindex{FLATTEN}] Write a .CIF file with a flattened
   representation of the cell loaded in the composition buffer.
\item[\frameindex{NODES}] Toggle the display style {\em after} the
   extraction.  When enabled, the actual node number of each box is
   displayed.  When disabled, a conventional display style is selected.
\item[\frameindex{FLASH}] A convenient way to find a particular node, FLASH
  prompts for a node number, then flashes that electrical node.  Nodes can
  also be flashed by pressing the pen down on the geometry itself.
  Whenever a node is flashed, some information about the node (fanout to n-
  and p-transistors, and optionally, area and capacitance) is also
  displayed.
\item[\frameindex{AREA}] Enables the computation of area and capacitances
  of FLASHed nodes.
\item[\frameindex{SHORT}] Treats all P+/N+ diodes as short circuits.  These
  structures arise (legally) in CMOS ohmic conacts.  Extracting the chip
  twice (once with this switch set), and comparing it against itself, ensures
  that all such contact structures have both sides connected to a power
  source.
\item[\framebox{DRC}]  Enter the composition buffer DRC facility.
\item[\framebox{COMP}] Return to composition menu.  All extraction data
  structures are freed when the Xtract menu is exited.
\item[\framebox{MAIN}] Return to main menu.
\end{description}


\subsubsection{The point-to-point router}\index{routing wires}

   \NEWOL\ has a manual pont-to-point router, intended mainly for
high-level routing such as pad-wrapping, where density considerations are
offset by a desire for fast and easy wiring.  The router is available only
in the DRAW sub-menu of the COMP menu.

   The router uses {\em wires} as a primitive data structure.  They require
separate generation and editing paradigms than the boxes used everywhere
else.  The display and specification properties of routing wires are set
primarily by keyboard commands, including ``W'' (toggle fleshed-out routing
display), ``M'' (toggle Manhattan routing).

\begin{description}
\item[\frameindex{DRAW}] Draw a wire by specifying end points of line
  segments that make up the centerline of the wire.  The wire is completed
  by lifting the pen (the end of the wire is the last point pressed).  By
  definition, a wire is the set of points within 1/2 of the {\em width}
  from the centerline.  In Manhattan mode, only right-angle bends are
  permitted; otherwise, arbitrary angles are permitted (the extractor,
  however, will ignore any non-Manhattan geometry).
\item[\frameindex{LAYER}] Select the layer for DRAW.
\item[\frameindex{DEL}] Delete an entire wire\index{deleting routing
  wires}, by pressing the pen on one of the line segment end points.
\item[\frameindex{EDIT}] Edit a routing wire\index{editing routing wires}.
  In Manhattan mode, points or centerlines can be selected and moved; in
  non-Manhattan mode, only vertices can be edited.  The connectivity of
  the wire is maintained.
\item[\frameindex{WIDTH}] Set the width of the wire in lambda.
\end{description}

\subsubsection{The \NEWOL\ design rule checker}\index{design rule checking}

   \NEWOL\ provides a simple geometric design rule checker.  Like the
extractor, it does not operate continuously in the background, but rather,
exploits the high-level box internal representation to operate quickly in a
``batch'' mode (typical performance is approximately 2500 square lambda per
second).  Unlike the extractor, the DRC is {\em NOT} guaranteed to find all
the errors the user may have made (design-rule checking is a difficult, and
presently open, research topic).  The philosophy for the DRC is the
following:  (i) finding some errors is more useful than finding none, and
(ii) only true errors should be reported.  Consequently, the DRC fails by
``errors of omission'' (i.e.  not finding or reporting particular errors),
rather than by errors of commission (reporting a valid construct as an
error).  The DRC is presently being improved, so this documentation is
possibly incomplete. For a more complete specification of the DRC
configuration file, see the System Maintainer's Guide.

\def\drcrule#1{\newline\null\hspace{1in}{\tt #1}\newline}

There are four categories of rules that are required.  These are, and
\NEWOL's current status regarding them:
\begin{description}
  \item[\putindex{Separation Rules}.] These rules specify some minimum
    distance between boxes on two particular layers.  A typical example is
    that disconnected pieces of polysilicon must be separated by
    $2\lambda$.  \NEWOL\ reads a configuration file of the design rules.
    The syntax of this rule is:
      \drcrule{separation <layer1> <layer2> <distance>}
    A variant on this rule provides a logical-AND between two layers to
    generate ``$<$layer1$>$'' above.  For example:
      \drcrule{separation2 diff select well 5}
    guarantees that n-diffusions (green (diff) surrounded by select)
    are at least 5 lambda from a well edge.
  \item[\putindex{Overlap rules}.] These rules specify that some layer must
    be entirely contained within some other layer.  For example, contact
    cuts must be surrounded by boxes corresponding to the two layers which
    are to be electrically connected:
      \drcrule{overlap poly polycut 2}
    guarantees that a poly surround of $2\lambda$ around each cut to poly.
    Again, binary interactions are specified by:
      \drcrule{overlap2 diff well well 5}
    which specifies that all active within the well must lie within the
    well by at least $5\lambda$. {\em Note that this applies to ohmic contacts
    to the well, in addition to any p-diffusions.}
  \item[\putindex{Width rules}.] These are single-layer rules, and specify
    the minimum width of a particular layer.  For example:
      \drcrule{width diffcut 2}
    specifies that $2\lambda \times 2\lambda$ is the minimum size for
    a cut to active.
  \item[\putindex{Extension rules}.] These rules specify composite rules
    such as the distance that poly must extend beyond a transistor channel
    in order to guarantee the integrity of the channel in the case of mask
    alignment errors.  This rule is currently not tested in \NEWOL.
  \end{description}

The DRC has two user interfaces: it is accessible through both the
geometry buffer and the composition buffer.  In general, it is executed
by drawing a box around the region to be checked.  Any errors found are
reported as white boxes drawn at the location of the error.  These
boxes can then be examined for information regarding the nature of the error.
Errors are also reported in a file created in the current directory
called {\tt drc.out}.


The menu squares common to the two DRC interfaces are:
\begin{description}
\item[\frameindex{RUN DRC}]  Execute the DRC. The user is prompted to
  draw a box enclosing the area to be checked.
\item[\frameindex{CLEAN}]  Clean up the data structures generated by
  the DRC.  In the geometry buffer, DRC errors are incorporated into
  a cell's data structure as boxes on a special layer.  The node names
  of these boxes (visible through the ELEC command, below) describe
  the error.  In the composition buffer, special boxes are maintained
  as part of the buffer, and are automatically cleared when the DRC
  menu is exited.
\item[\frameindex{WELLS}] Perform the additional tests required by
  the {\em separation2} and {\em overlap2} rules above.  These tests
  are required for testing well-related rules, but are rather slow
  to execute.
\item[\frameindex{FLASH}] Highlight the errors found by the DRC by flashing the
  white error boxes.  As in the extractor, FLASH is terminated by
  lifting the pen from the tablet.
\end{description}

In the geometry buffer, there is an additional command to inquire
about the error in question:
\begin{description}
  \item[\frameindex{ELEC}] A short summary of the error is saved as the
    electrical node name of the error box.  Thus, ELEC can be used to
    display the name.
\end{description}

In the composition buffer, a special command must be used to display the
results of a previous DRC:
\begin{description}
  \item[\frameindex{SHOW DRC}] When the DRC is first run, this function
    is executed automatically.  However, as the screen is refreshed, the
    DRC boxes also disappear (since, technically, they are not part of the
    data structure);  SHOW DRC is used to re-display them.
\end{description}


\subsection{The Options menu}\index{options menu}

   The last menu accessible from the main menu is the
\putindex{OPTS}\index{options menu} menu.  This menu contains a collection
of file management functions, as well as provisions to monitor and modify
\NEWOL's operation.  This is the menu that allows you to save and recover
your work, from session to session.  \NEWOL\ saves its data in Caltech
Intermediate Format (CIF -- see Chapter 4 of Mead \& Conway)\index{.CIF
files}, which is directly compatible with the suite of design tools ({\bf
cifp}, {\bf cifplot}, {\bf extract}) used at Caltech, as well as the
verification/PG-tape generation software used by MOSIS.

\begin{description} 
\item[\frameindex{LOAD}] This allows you to read in a file containing one
   or more cells.  These cells may be either geometry cells, in which case
   they are appended to the list in the *GEOM* buffer, or composition
   cells, in which case the composition information will be added to the
   *COMP* buffer list.  Any sub-cells in a composition cell will also be
   read in and added to the appropriate buffer lists (remember that you
   have to enter these buffers and NEW the cells before they will appear on
   the screen for editing).  Thus, if your finished project is in the form
   of a single cell (which is required by MOSIS), it can be read in simply
   by pressing LOAD, and typing in the name of the file in which it is
   found.  Filenames of up to 12 characters are permitted in the CHIPmunk
   operating system.  \NEWOL\ will automatically append a {\tt .CIF}
   extension to the name you supply, if no extension is given.  By default,
   only the current directory will be searched; full pathnames must be
   supplied if the file is not in this directory.
\item[\frameindex{SAVE}] This command saves \NEWOL's internal data
   representation in a file as CIF.  Cell revision numbers and last
   modification dates are also updated as required and written to the file.
   \NEWOL\ will prompt for a filename to write into (again, 12 characters
   maximum), and a cell name (either composition or geometry) to save.  If
   the file already exists, \NEWOL\ will rename the original to file.CFO,
   as a backup feature.  \index{.CFO files} Please note:  only cells which
   you save explicitly will in fact survive when you exit \NEWOL\ (however,
   the program {\em will} keep track of your work, and warn you if you try
   to exit with unsaved changes).  To save the state of the entire system,
   instead of a single cell, use the DUMP command (below).
\item[\frameindex{PORTS}] This command creates a file PORTS.WOL that
   contains the (heirarchical) portnames of all instanced cells, as
   well as their absolute (x,y) coordinates (in lambda, with (0,0) in
   the lower left corner of the chip).  \typeout{Check OPTS-PORTS with Johnw}
   This is primarily useful for interfacing with an external router.
\item[\frameindex{MEM}] Prints the current state of \NEWOL's memory
   manager, including the (user-set) memory threshold.  \typeout{Program
   maintainers are referred to sysmaint for further details.}
\item[\frameindex{DIR}] Enters the file-lister environment (see above), to
   display the {\tt .CIF} files found in a particular directory.  This
   feature has been largely replaced by the file-lister in LOAD/SAVE, and
   by the ability to perform shell-escapes.
\item[\frameindex{OPTS}] Enters a CAGED-style textual options specification
   sub-menu.  These are the options that are written to the INFO.WOL
   configuration file.  The options, some typical values, and their
   meaning, are:

{\footnotesize
   \begin{tabular} {lll}
     Lambda:& 150 & sets $\lambda$ in hundreths of microns  \\
     Display style:& 0 & see {\em \putindex{display styles}} \\
     Short cell name prompt:& Off& if On, enter cell-lister environment immediately \\
     Short file name prompt:& On & if On, enter file-lister environment immediately \\
     Auto refresh:&On& see {\em \putindex{auto-refresh}} \\
     Edge-priority selection:&Off& see {\em \putindex{edge-priority selection}} \\
     Point-to-point move:&Off& set \putindex{point-to-point move} as default \\
     Disable Hierarchy:&Off& if On, \putindex{disable hierarchy} for select mechanism \\
     Display Bounding Boxes:& On& \\
     Display Ports:& Off& set \putindex{display ports} mode \\
     Manhattan routing:& On& if On, limits DRAW to rectangular geometry \\
     Fleshed-out routing:& Off& If Off, draws centerlines only \\
     Background color:& 0& sets gray level of screen background \\
     Memory threshold:& 20000& \NEWOL\ will warn when this is reached \\
     CIF symbol start:& 1 & Symbol number to start numbering at \\
     Technology file:& SCG&
   \end{tabular}
}
\item[\frameindex{CNFG}]  Writes an INFO.WOL file into the current directory.
   When \NEWOL\ begins execution it searches for this configuration file in
   (i) the current directory, (ii) the user's home directory, and (iii) the
   WOL library directory (/LIB/WOLLIB).
\item[\frameindex{TECH}]  Prompts for the name of a technology file
   to read in.  The default file is specified in the INFO.WOL configuration
   file.  Since different technologies often have different numbers of layers,
   it is often not possible to change technologies from within \NEWOL.
   The preferred mode is to use the MOSIS program to perform layer conversion,
   and/or use the {\tt -t$<$tech$>$} command-line option to \NEWOL.
\item[\frameindex{DUMP}] Causes all cells, geometry and composition, to be
   written to a single file, with no top-level call.  This is a convenient
   way to save all of your work at intermediate points in your editing
   session.  For submission to MOSIS, however, CIF must be generated via
   the SAVE command.
\item[\framebox{MAIN}]  Return to MAIN menu.
\end{description}


\subsection{The DBUG Menu}

   This menu, accessible from the main menu, is primarily intended
for emergency debugging and problem identification.  There are
very {\em *DANGEROUS*} operations in this menu, and they should not
be fooled around with, unless you think you know what you are doing.
The exception to this caveat is the WCOMP command; it is located in
this menu because of its fairly specialized nature.

\begin{description}
\item[\framebox{GEOM}] Dump the data structures of the geometry buffer.
\item[\framebox{GCELL}] Dump the data structures of the geometry cell
  dictionary list.
\item[\framebox{COMP}] Dump the data structures of the composition cell
  dictionary list.
\item[\framebox{CCELL}] Dump the data structures of the composition buffer.
\item[\frameindex{EMERG}] Take emergency buffer action.  The entire contents
  of the geometry or composition buffers can be destroyed.  No attempt is
  made to reclaim any memory.  This command is only intended for use
  in truly dire straits, and to buy enough time to save what you can, then
  exit \NEWOL.
\item[\frameindex{OPTS}] Another path into the OPTS text sub-menu, should
  the primary path (through the Options menu) become corrupted.
\item[\frameindex{MAKE}] Another path to MAKE either the geometry or
  composition buffer.
\item[\frameindex{WCOMP}] A means to individually save all the cells loaded
  in \NEWOL\index{saving all cells}.  This is useful for the WOLCOMP
  composition system, which requires files to contain single geometry
  cells.  The user is prompted if only newly modified cells are to be
  dumped, and if only geometry cells should be considered.
\item[\frameindex{FLUSH}] Re-initializes the memory manager.  Effectively,
  this wipes out the \NEWOL\ data structures, clearing the cell dictionaries
  and buffers, and basically resetting \NEWOL\ to a power-up state.
\end{description}


