magic/doc/latexfiles/tut3.tex

%----------------------------------------------------------------------------
% Magic tutorial number 3
%----------------------------------------------------------------------------

\NeedsTeXFormat{LaTeX2e}[1994/12/01]
\documentclass[letterpaper,twoside,12pt]{article}
\usepackage{epsfig,times}

\setlength{\textwidth}{8.5in}
\addtolength{\textwidth}{-2.0in}
\setlength{\textheight}{11.0in}
\addtolength{\textheight}{-2.0in}
\setlength{\oddsidemargin}{0in}
\setlength{\evensidemargin}{0pt}
\setlength{\topmargin}{-0.5in}
\setlength{\headheight}{0.2in}
\setlength{\headsep}{0.3in}
\setlength{\topskip}{0pt}

\def\hinch{\hspace*{0.5in}}
\def\starti{\begin{center}\begin{tabbing}\hinch\=\hinch\=\hinch\=hinch\hinch\=\kill}
\def\endi{\end{tabbing}\end{center}}
\def\ii{\>\>\>}
\def\mytitle{Magic Tutorial \#3: Advanced Painting (Wiring and Plowing)}

%----------------------------------------------------------------------------

\begin{document}

\makeatletter
\newcommand{\ps@magic}{%
	\renewcommand{\@oddhead}{\mytitle\hfil\today}%
	\renewcommand{\@evenhead}{\today\hfil\mytitle}%
	\renewcommand{\@evenfoot}{\hfil\textrm{--{\thepage}--}\hfil}%
	\renewcommand{\@oddfoot}{\@evenfoot}}
\newcommand{\ps@mplain}{%
	\renewcommand{\@oddhead}{}%
	\renewcommand{\@evenhead}{}%
	\renewcommand{\@evenfoot}{\hfil\textrm{--{\thepage}--}\hfil}%
	\renewcommand{\@oddfoot}{\@evenfoot}}
\makeatother
\pagestyle{magic}
\thispagestyle{mplain}


\begin{center}
  {\bfseries \Large \mytitle} \\
  \vspace*{0.5in}
  {\itshape John Ousterhout} \\
  {\itshape Walter Scott} \\
  \vspace*{0.5in}
   Computer Science Division \\
   Electrical Engineering and Computer Sciences \\
   University of California \\
   Berkeley, CA  94720 \\
  \vspace*{0.25in}
  {\itshape (Updated by others, too.)} \\
  \vspace*{0.25in}
  This tutorial corresponds to Magic version 7. \\
\end{center}
\vspace*{0.5in}

{\noindent\bfseries\large Tutorials to read first:}
\starti
   \> Magic Tutorial \#1: Getting Started \\
   \> Magic Tutorial \#2: Basic Painting and Selection
\endi

{\noindent\bfseries\large Commands introduced in this tutorial:}
\starti
   \> :array, :corner, :fill, :flush, :plow, :straighten, :tool, :wire
\endi

{\noindent\bfseries\large Macros introduced in this tutorial:}

\starti
   \> $<$space$>$
\endi

\vspace*{0.5in}
\section{Introduction}

Tutorial \#2 showed you the basic facilities for placing paint and
labels, selecting, and manipulating the things that are
selected.  This tutorial describes two additional facilities for
manipulating paint:  wiring and plowing.  These commands aren't
absolutely necessary, since you can achieve the same effect with
the simpler commands of Tutorial \#2;  however, wiring and plowing
allow you to perform certain kinds of manipulations much more quickly
than you could otherwise.  Wiring is described in Section 2;  it
allows you to place wires by pointing at the ends of legs rather
than by positioning the box, and also provides for convenient contact
placement.  Plowing is the subject of Section 3.  It allows you to
re-arrange pieces of your circuit without having to worry about
design-rule violations being created:  plowing automatically moves
things out of the way to avoid trouble.

\section{Wiring}

The box-and-painting paradigm described in Tutorial \#2 is sufficient
to create any possible layout, but it's relatively inefficient
since three keystrokes are required to paint each new area:  two
button clicks to position the box and one more to paint the material.
This section describes a different painting mechanism based on
{\itshape wires}.  At any given time, there is a current wiring material
and wire thickness.  With the wiring interface you can create a new
area of material with a single button click:  this paints a straight-line
segment of the current material and width
between the end of the previous wire segment and the cursor location.
Each additional button click adds an additional segment.  The wiring
interface also makes it easy for you to place contacts.
\section{Tools}

Before learning about wiring, you'll need to learn about tools.
Until now, when you've pressed mouse buttons in layout windows the
buttons have caused the box to change or material to be painted.
The truth is that buttons can mean different things at different times.
The meaning of the mouse buttons depends on the {\itshape current tool}.
Each tool is identified by a particular cursor shape and a
particular interpretation of the mouse buttons.  Initially, the current
tool is the box tool;  when the box tool is active the cursor has
the shape of a crosshair.  To get information about the current tool,
you can type the long command

\starti
   \ii {\bfseries :tool info}
\endi

This command prints out the name of the current tool and the meaning
of the buttons.  Run Magic on the cell {\bfseries tut3a} and type {\bfseries :tool info}.

The {\bfseries :tool} command can also be used to switch tools.  Try this
out by typing the command

\starti
   \ii {\bfseries :tool}
\endi

Magic will print out a message telling you that you're using the
wiring tool, and the cursor will change to an arrow shape.  Use
the {\bfseries :tool info} command to see what the buttons mean now.  You'll
be using the wiring tool for most of the rest of this section.  The
macro `` '' (space) corresponds to {\bfseries :tool}.  Try typing the space key
a few times:  Magic will cycle circularly through all of the
available tools.  There are three tools in Magic right now:  the
box tool, which you already know about, the wiring tool, which
you'll learn about in this tutorial, and the netlist tool, which has a square
cursor shape and is used for netlist editing.  ``Tutorial \#7:
Netlists and Routing'' will show you how to use the netlist tool.

The current tool affects only the meanings of the mouse
buttons.  It does not change the meanings of the long commands
or macros.  This means, for example, that you can still use
all the selection commands while the wiring tool is active.
Switch tools to the wiring tool, point
at some paint in {\bfseries tut3a}, and type the {\bfseries s} macro.
A chunk gets selected just as it does with the box tool.

\section{Basic Wiring}

There are three basic wiring commands:  selecting the wiring  material,
adding a leg, and adding a contact.  This section describes the
first two commands.  At this point you should be editing the
cell {\bfseries tut3a} with the wiring tool active.  The first step
in wiring is to pick the material and width to use for wires.
This can be done in two ways.  The easiest way is to find a piece
of material of the right type and width, point to it with the
cursor, and click the left mouse button.  Try this in {\bfseries tut3a}
by pointing to the label {\bfseries 1} and left-clicking.  Magic prints out
the material and width that it chose, selects a square of that
material and width around the cursor, and places the box around
the square.  Try pointing to various places in {\bfseries tut3a} and
left-clicking.

Once you've selected the wiring material, the right
button paints legs of a wire.  Left-click on label {\bfseries 1} to
select the red material, then move the cursor over label
{\bfseries 2} and right-click.  This will paint a red wire between
{\bfseries 1} and {\bfseries 2}.  The new wire leg is selected so that you
can modify it with selection commands, and the box is placed
over the tip of the leg to show you the starting point for the
next wire leg.  Add more legs to the wire by right-clicking
at {\bfseries 3} and then {\bfseries 4}.  Use the mouse buttons to paint
another wire in blue from {\bfseries 5} to {\bfseries 6} to {\bfseries 7}.

Each leg of a wire must be either horizontal or vertical.  If you
move the cursor diagonally, Magic will still paint a horizontal
or vertical line (whichever results in the longest new wire leg).
To see how this works, left-click on {\bfseries 8} in {\bfseries tut3a},
then right-click on {\bfseries 9}.  You'll get a horizontal leg.  Now
undo the new leg and right-click on {\bfseries 10}.  This time you'll
get a vertical leg.  You can force Magic to paint the next
leg in a particular direction with the commands

\starti
   \ii {\bfseries :wire horizontal} \\
   \ii {\bfseries :wire vertical}
\endi

Try out this feature by left-clicking on {\bfseries 8} in {\bfseries tut3a},
moving the cursor over {\bfseries 10}, and typing {\bfseries :wire ho}
(abbreviations work for {\bfseries :wire} command options just as
they do elsewhere in Magic).  This command will generate a
short horizontal leg instead of a longer vertical one.

\section{Contacts}

When the wiring tool is active, the middle mouse button places
contacts.  Undo all of your changes to {\bfseries tut3a} by typing
the command {\bfseries :flush} and answering {\bfseries yes} to the
question Magic asks.  This throws away all of the changes made to the
cell and re-loads it from disk.  Draw a red wire leg from
{\bfseries 1} to {\bfseries 2}.  Now move the cursor over the blue area and
click the middle mouse button.  This has several effects.  It
places a contact at the end of the current wire leg, selects the
contact, and moves the box over the selection.  In addition, it changes
the wiring material and thickness to match the material you
middle-clicked.  Move the cursor over {\bfseries 3} and right-click
to paint a blue leg, then make a contact to purple by middle-clicking
over the purple material.  Continue by drawing a purple leg to {\bfseries 4}.

Once you've drawn the purple leg to {\bfseries 4}, move the cursor over
red material and middle-click.  This time, Magic prints an error
message and treats the click just like a left-click.
Magic only knows how to make contacts between certain combinations of
layers, which are specified in the technology file
(see ``Magic Maintainer's Manual \#2: The Technology File'').  For
this technology, Magic doesn't know how to make contacts directly
between purple and red.

\section{Wiring and the Box}

In the examples so far, each new wire leg appeared to be
drawn from the end of the
previous leg to the cursor position.  In fact, however, the new
material was drawn from the {\itshape box} to the cursor position.  Magic
automatically repositions the box on each button click to help set
things up for the next leg.  Using the box as the starting point
for wire legs makes it easy to start wires in places that don't
already have material of the right type and width.  Suppose that you want
to start a new wire in the middle of an empty area.  You can't
left-click to get the wire started there.  Instead, you can left-click
some other place where there's the right material for the wire,
type the space bar twice to get back the box tool, move the box where
you'd like the wire to start, hit the space bar once more to get back
the wiring tool, and then right-click to paint the wire.  Try this
out on {\bfseries tut3a}.

When you first start wiring, you may not be able to find the right
kind of material anywhere on the screen.  When this happens, you
can select the wiring material and width with the command

\starti
   \ii {\bfseries :wire type} {\itshape layer} {\itshape width}
\endi

Then move the box where you'd like the wire to start, switch
to the wiring tool, and right-click to add legs.

\section{Wiring and the Selection}

Each time you paint a new wire leg or contact using the wiring
commands, Magic selects the new material just as if you had placed
the cursor over it and typed {\bfseries s}.  This makes it
easy for you to adjust its position if you didn't get it right
initially.  The {\bfseries :stretch} command is particularly useful
for this.  In {\bfseries tut3a}, paint a wire leg in blue from {\bfseries 5}
to {\bfseries 6} (use {\bfseries :flush} to reset the cell if you've made
a lot of changes).  Now type {\bfseries R} two or three times to stretch
the leg over to the right.  Middle-click over purple material,
then use {\bfseries W} to stretch the contact downward.

It's often hard to position the cursor
so that a wire leg comes out right the first time, but it's usually
easy to tell whether the leg is right once it's painted.  If it's
wrong, then you can use the stretching commands to shift it over
one unit at a time until it's correct.

\section{Bundles of Wires}

Magic provides two additional commands that are useful for
running {\itshape bundles} of parallel wires.  The commands are:

\starti
   \ii {\bfseries fill} {\itshape direction }[{\itshape layers}] \\
   \ii {\bfseries corner} {\itshape direction1 direction2 }[{\itshape layers}]
\endi

To see how they work, load the cell {\bfseries tut3b}.  The
{\bfseries :fill} comand extends a whole bunch of paint in a given direction.
It finds all paint touching
one side of the box and extends that paint to the opposite
side of the box.  For example, {\bfseries :fill left} will look underneath
the right edge of the box for paint, and will extend that paint
to the left side of the box.  The effect is just as if all the colors
visible underneath that edge of the box constituted a paint brush;
Magic sweeps the brush across the box in the given direction.
Place the box over the label ``Fill here'' in {\bfseries tut3b} and
type {\bfseries :fill left}.

The {\bfseries :corner} command is similar to {\bfseries :fill} except that
it generates L-shaped wires that follow two sides of the box,
travelling first in {\itshape direction1} and then in {\itshape direction2}.
Place the box over the label ``Corner here'' in {\bfseries tut3b} and
type {\bfseries :corner right up}.

In both {\bfseries :fill} and {\bfseries :corner},
if {\itshape layers} isn't specified then all layers are filled.
If {\itshape layers} is given then only those layers are painted.
Experiment on {\bfseries tut3b} with the {\bfseries :fill} and {\bfseries :corner}
commands.

When you're painting bundles of wires, it would be nice if there
were a convenient way to place contacts across the whole bundle
in order to switch to a different layer.  There's no single
command to do this, but you can place one contact by hand and
then use the {\bfseries :array} command to
replicate a single contact across the whole bundle.
Load the cell {\bfseries tut3c}.  This contains a bundle of wires
with a single contact already painted by hand on the bottom
wire.  Type {\bfseries s} with the cursor over the contact, and
type {\bfseries S} with the cursor over the stub of purple wiring
material next to it.
Now place the box over the label ``Array'' and type the command
{\bfseries :array 1 10}.  This will copy the selected contact across
the whole bundle.

The syntax of the {\bfseries :array} command is

\starti
   \ii {\bfseries :array} {\itshape xsize ysize}
\endi

This command makes the selection into an array of identical elements.
{\itshape Xsize} specifies how many total instances there should be
in the x-direction when the command is finished and {\itshape ysize}
specifies how many total instances there should be in the
y-direction.  In the {\bfseries tut3c} example, {\bfseries xsize} was one,
so no additional copies were created in that direction;  {\bfseries ysize}
was 10, so 9 additional copies were created.  The box is used to
determine how far apart the elements should be:  the width of the
box determines the x-spacing and the height determines the y-spacing.
The new material always appears above and to the right of the original
copy.

In {\bfseries tut3c}, use {\bfseries :corner} to extend the purple wires and
turn them up.  Then paint a contact back to blue on the leftmost
wire, add a stub of blue paint above it, and use {\bfseries :array} to
copy them across the top of the bundle.  Finally,
use {\bfseries :fill} again to extend the blue bundle farther up.

\section{Plowing}

Magic contains a facility called {\itshape plowing} that you can
use to stretch and compact cells.  The basic plowing command
has the syntax

\starti
   \ii {\bfseries :plow} {\itshape  direction }[{\itshape layers}]
\endi

where {\itshape direction} is a Manhattan direction like {\bfseries left} and
{\itshape layers} is an optional, comma-separated list of mask layers.
The plow command
treats one side of the box as if it were a plow, and shoves
the plow over to the other side of the box.  For example,
{\bfseries :plow up} treats the bottom side of the box as a plow,
and moves the plow to the top of the box.

As the plow moves,
every edge in its path is pushed ahead of it (if {\itshape layers}
is specified, then only edges on those layers are moved).
Each edge that is pushed by the plow pushes other edges ahead
of it in a way that preserves design rules, connectivity,
and transistor and contact sizes.  This means that material
ahead of the plow gets compacted down to the minimum spacing
permitted by the design rules, and material that crossed the
plow's original position gets stretched behind the plow.

You can compact a cell by placing a large plow off to one side of
the cell and plowing across the whole cell.  You can open up
space in the middle of a cell by dragging a small plow across
the area where you want more space.

To try out plowing, edit
the cell {\bfseries tut3d}, place the box over the rectangle
that's labelled ``Plow here'', and try plowing in various
directions.  Also, try plowing only certain layers.
For example, with the box over the ``Plow here'' label,
try

\starti
   \ii {\bfseries :plow right metal2}
\endi

Nothing happens.  This is because there are no metal2
{\itshape edges} in the path of the plow.  If instead you had
typed

\starti
  \ii {\bfseries :plow right metal1}
\endi

only the metal would have been plowed to the right.

In addition to plowing with the box, you can plow the
selection.  The command to do this has the following
syntax:

\starti
  \ii {\bfseries :plow selection }[{\itshape direction }[{\itshape distance}]]
\endi

This is very similar to the {\bfseries :stretch} command: it
picks up the selection and the box and moves both so that
the lower-left corner of the box is at the cursor location.
Unlike the {\bfseries :stretch} command, though, {\bfseries :plow selection}
insures that design rule correctness and connectivity are
preserved.

Load the cell {\bfseries tut3e} and
use {\bfseries a} to select the area underneath the label that
says ``select me''.
Then point with the cursor to the
point labelled ``point here'' and type {\bfseries :plow selection}.
Practice selecting things and plowing them.
Like the {\bfseries :stretch} command, there is also a longer
form of {\bfseries :plow selection}.  For example, {\bfseries :plow selection down 5}
will plow the selection and the box down 10 units.

Selecting a cell and plowing it is a good way to move the cell.
Load {\bfseries tut3f} and select the cell {\bfseries tut3e}.
Point to the label ``point here'' and plow the selection with
{\bfseries :plow selection}.
Notice that all connections to the cell have remained attached.
The cell you select must be in the edit cell, however.

The plowing operation is implemented in a way that tries to
keep your design as compact as possible.  To do this, it
inserts jogs in wires around the plow.  In many cases, though,
the additional jogs are more trouble than they're worth.  To
reduce the number of jogs inserted by plowing, type the
command

\starti
   \ii {\bfseries :plow nojogs}
\endi

From now on, Magic will insert as few jogs as possible when
plowing, even if this means moving more material.  You
can re-enable jog insertion with the command

\starti
   \ii {\bfseries :plow jogs}
\endi

Load the cell
{\bfseries tut3d} again and try plowing it both with and without jog insertion.

There is another way to reduce the number of jogs introduced
by plowing.
Instead of avoiding jogs in the
first place, plowing can introduce them freely but clean them
up as much as possible afterward.
This results in more dense
layouts, but possibly more jogs than if you had enabled
{\bfseries :plow nojogs}.
To take advantage of this second method
for jog reduction, re-enable jog insertion ({\bfseries :plow jogs})
and enable jog cleanup with the command

\starti
   \ii {\bfseries :plow straighten}
\endi

From now on, Magic will attempt to straighten out jogs after
each plow operation.  To disable straightening, use the
command

\starti
   \ii {\bfseries :plow nostraighten}
\endi

It might seem pointless to disable jog introduction
with {\bfseries :plow nojogs} at the same time
straightening is enabled with {\bfseries :plow straighten}.
While it is true that {\bfseries :plow nojogs} won't introduce
any new jogs for {\bfseries :plow straighten} to clean up,
plowing will straighten out any existing jogs after
each operation.

In fact, there is a separate command that is sometimes
useful for cleaning up layouts with many jogs, namely
the command

\starti
   \ii {\bfseries :straighten} {\itshape direction}
\endi

where {\itshape direction} is a Manhattan direction, e.g., {\bfseries up},
{\bfseries down}, {\bfseries right}, or {\bfseries left}.  This command
will start from one side of the box and pull jogs toward
that side to straighten them.
Load the cell {\bfseries tut3g},
place the box over the label ``put box here'',
and type {\bfseries :straighten left}.  Undo the last command
and type {\bfseries :straighten right} instead.  Play around
with the {\bfseries :straighten} command.

There is one more feature of plowing that is sometimes useful.
If you are working on a large cell and want to make sure that
plowing never affects any geometry outside of a certain area,
you can place a {\itshape boundary} around the area you want to
affect with the command

\starti
   \ii {\bfseries :plow boundary}
\endi

The box is used to specify the area you want to affect.
After this command, subsequent plows will only affect the
area inside this boundary.

Load the cell {\bfseries tut3h} place the box over the label
``put boundary here'', and type {\bfseries :plow boundary}.
Now move the box away.  You will see the boundary
highlighted with dotted lines.  Now place the box
over the area labelled ``put plow here'' and plow up.
This plow would cause geometry
outside of the boundary to be affected, so Magic
reduces the plow distance enough to prevent
this and warns you of this fact.
Now undo the last plow and remove the boundary with

\starti
   \ii {\bfseries :plow noboundary}
\endi

Put the box over the ``put plow here'' label and plow up again.
This time there was no boundary to stop the plow, so everything
was moved as far as the height of the box.  Experiment with placing
the boundary around an area of this cell and plowing.

\end{document}