PWDoc.tioga
Created by Bertrand Serlet, March 25, 1986 10:11:45 pm PST PS,
Louis Monier July 29, 1985 6:27:59 pm PDT
HOW TO USE PW
CEDAR 6.0 — FOR INTERNAL XEROX USE ONLY
How To Use PatchWork
Louis Monier and Bertrand Serlet
© Copyright 1986 Xerox Corporation. All rights reversed.
Abstract: PatchWork is a Silicon Assembler, i.e. a VLSI layout program which generates geometry from ChipNDale cells (usually hand-drawn) and a Cedar Program describing the topological placement of these cells. It runs under Cedar and is fully integrated in ChipNDale. This manual corresponds to the version ChipNDale 23.
How to Use PW: Contents
0. Introduction
1. Basic concepts and terminology
2. Make a cell library
3. Abut things together
4. Conditional objects
5. Unsafe subset
6. PWmos
7. PWPins
8. Becoming a user
9. Fine Points and implementation details
[If you are reading this document on-line, try using the Tioga Levels menus (if you can) to initially browse the top few levels of its structure before reading it straight through.]
[ATTENTION, this document gets a bit old, and should be reworked (if you want to do it, fine, just take the lock on PW). The concepts, though, are still allright. BS March 25, 1986 10:11:27 pm PST]
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304
For Internal Xerox Use Only
0. Introduction
I beleive that large chips should be designed by programs. More precisely, cells should be drawn with a good graphic editor (ChipNDale), and assembled by program, with no hand-edition of program-generated pieces.
Let me give you several good reasons to do so.
Chips get very large: a procedural description is smaller and easier to manipulate than a flat graphical representation.
A chip is never finished, and it is much simpler to re-assemble a chip by running a program than to patch it with a graphic editor (even the best), trying to minimize the number of clicks. Think of the chill that would go down your spine in the event of a change in specs or design rules at the last minute!
The initial investment of writing the code is usually comparable to hand-layout for a small chip, and immensely less for a real VLSI.
Increasing a graphic editor with smarter primitives is not sufficient: you want arrays, then 2-D arrays, then 2-D arrays with mirroring, then the same with a special case for the first one, no the middle one, . . . You'll always need another feature, and in fact you need a full programming language, so use one!
Once a circuit is expressed that way, you have in hand a generator for a family of chips. Merely change a few parameters and simulate a smaller version, DRC a medium one, fabricate two versions, plot a huge one to impress your friends. . .
Once you are used to the notion of program-generated layout, the gap between your part of the circuit and the output of a magic generator (PLA, RAM, . . .) just vanishes. Some generators are standard, others are yours. You can also write a generator, and share it. You can share everything, or just the code, and users provide their cell library. So expressing circuits by program is an excellent way of "canning knowledge".
PatchWork was designed with the idea of helping you with the regular parts of a chip, i.e. datapath, control, arrays, . . . It needs in addition a placer/router, on which other people are now working, in order to be completely general.
PatchWork is based on a few simple ideas. First, it provides novice users with a way of defining chips by program which is simple, safe and efficient. Simple means that it is not necessary to know the inside of CD in order to generate geometry. Safe means that there will be no nasty surprise, like pieces of design which "are in there", but don't plot, or worse, don't appear in the CIF (it happened to me!). Efficient means that the few primitives provided go a long way, and allow you to describe a lot of chips by program.
Another key idea of PW is to be well-integrated with other tools. This is obtained by sharing as many concepts as possible with the existing basic tool, ChipNDale. Object, Instance, Design, Pin, orientation, ... , are exactly the same as CD, and this saves a lot of unnecessary code and prevents a lot of confusion.
To start, get PW from
/DATools/DATools6.0/Top/PW.df
and read in PWExample.dale (cmos technology). As you read this document, you can refer to cells in this design which illustrate the text.
1. Basic concepts, warnings, and terminology
It is necessary to have used CD before using PW, so please refer to the basic documentation and give yourself the time to play with CD. I assume that you know the meaning of the words: design, object, instance, directory, cell, pin, and that you know how to start CD, draw objects, save a design and read it again.
It is also a good idea to read the interface PW.mesa, soon after this document. You will notice that almost all functions use a "design" first argument. This design is the target design, i.e. the one in which the assembled objects will end up. In interactive mode, it is provided by PW as the argument of the UserProc.
2. Make a cell library
What I am describing here is a methodology which the early users of PW have adopted pretty instinctively, so give it a try.
To start, you need a set of cells. The easiest way is to draw them interactively with CD. Have a separate design for that, like MyChipCellLibrary.dale. You might use several designs if you prefer. The point is that you don't want to mix program-generated objects with hand-drawn ones. Reasons:
-- a cell library is usually a pretty small file, and it is all you need to save between sessions.
-- program-generated layouts have a profusion of objects which clutter the directory and slow down many operations. When working in the cell library, you want to zip through relatively small cells and save your design in no time.
-- it is amazing how easily your program can mess up things in the design. If a mad piece of code smashes your carefully hand-drawn cells, and does that in such a subtle way that you don't realize it until all back-ups are lost, you will be sorry.
So, one (or several) precious "source designs", or "library cells", and a scratch-pad design.
Preparing cells
After drawing a cell in the cell library, you probably want to assemble by hand a few cells, just to see if they match, and set their InterestRect. The InterestRect (don't ask why this name, it's history) of a cell is the black ouline displayed when you select it. This definition is not 100% exact, but good enough for our purpose. The InterestRect is not the bounding box of the geometry, there are other xxxRect for that. Its important properties are:
-- PW uses the InterestRect to abut objects.
-- You can set it interactively with P-Middle, and it becomes then independent of the geometry of the object. Once you set it, it stays, even if you edit the cell. If you don't set it, the default is (almost) the bounding box, but if you make minor edits to the cell, it might change and give you trouble when abuting cells. Play with the top three cells of PWExample.dale, select them, measure their size, push into them, edit them. If the InterestRect extends away from the geometry, you might encouter a redisplay bug, but it is OK (see the cell findMe).
When doing these adjustments, make sure that the cells are not rotated or mirrored. For this, you can either create a fresh instance of the cell, or check via the statistic command (Space-S) that the orientation-code of the selected object is zero. By the way, the statistic command gives you the size of an object, which is not the same as the size of its InterestRect. So far, the only way to know the size of the InterestRect iso measure it (CTRL-middle).
Pins
It is a good idea to put pins on all the ports of the cells. Even though the notion of formally-defined ports has not made it throughout the CAD system yet, many people around here beleive that it is the way of the future (and all these people talk loud and carry heavy sticks). Put pins on every piece of conductor which is going to have a connection with "the outside", make sure that the pin is on top of the material, is made of the same layer, is located inside and on the edge of the InterestRect, and bears a meaningful name. The reason is that several useful modules make these assumptions about pins. The cell cellWithPins contains pins with self-explaining names.
Accessing a library
Your code should be able to refer to a cell in a given design. You can set a default source for the cells, or specify it on a per-cell basis. The name used should be the same as in the design directory, and case is significant. Syntax:
design ← PW.OpenDesign["pwtest.dale"];
a ← PW.Get[design, "a"]; -- from the default source
3. Abut things together
The basic primitive in PW is abuting two objects, and comes in two flavors, AbutX and AbutY.
Let's consider AbutX[a, b], where a and b are ChipNDale objects in a design. PW will abut a and b so that the right edge of the InterestRect of a matches the left edge of the InterestRect of b. If the heights of the objects differ, PW comes to a halt, and returns the two culprits so that you can figure out by yourself why they don't match. Respectively, for an AbutY, the widths should match. The resulting object is not a cell, but an Abut. You don't really need to understand the difference, since as soon as you do something to an abut —like push into it— it turns into a cell (never feed it after midnight).
AbutX and AbutY can take up to 6 arguments, and if that is not enough, the AbutListX and AbutListY functions take a list of arguments. Omnipresent NIL is the neutral element for the Abut operation. If no argument is given in an AbutX or AbutY, the result is NIL. AbutCheck (not implemented yet) performs an additionnal check that all pins along the abuting edge match in position, size, layer and name.
Higher-lever functions have been introduced, such as Arrays. The best way to see what is available is to refer to the client interface (PW.mesa). We find ArrayX, ArrayY, Array and MapFunctionX, MapFunctionY, MapFunction. MapFunction tries to generalize the concept of an array, for the case where the cell on row i and on column j is a function of i and j. Very useful for making a decoder for example.
The following functions create an instance of the object and encase it in a new cell. The idea is that PW produces new objects, not instances, and that instanceName or orientation are properties of an instance, not of an object. We find FlipX (changes the sign on the X axis, i.e. symmetry wrt the vertical axis), FlipY, Rot90 (counter-clockwise), Rot180, Rot270, and InstanceName.
Here is a typical user program, and you'll find the corresponding cells in the example:
PWtest.mesa
Copyright © 1984, 1985 by Xerox Corporation. All rights reversed.
Created by: Monier, July 18, 1985 3:02:35 pm PDT
DIRECTORY
PW;
PWtest: CEDAR PROGRAM
IMPORTS PW =
BEGIN
MyProc: PW.UserProc =
BEGIN
-- Cells
a, b, test: PW.Object;
-- Default source
PW.SetDefaultSource[PW.OpenDesign["///PWExample.dale"]];
-- Get the cells
a ← PW.Get["a"];
b ← PW.Get["b"];
-- Abut them
test ← PW.AbutX[design, a, b];
RETURN[test];
END;
Register[MyProc, "PWTest"]; -- PWTest is the name of the generator
END.
Another example to illustrate the use of MapFunction to create irregular arrays:
BinaryCount: PW.XYFunction =
{RETURN[
SELECT TRUE FROM
y=0 => edge,
PW.XthBitOfN[y-1, x] => contact,
ENDCASE => noContact]};
test ← PW.MapFunction[design, BinaryCount, 0, 16, 0, 4];
That's all you need to generate a decoder. Also, if the XYFunction is just making reference to an array of bits, that's all you need to create a ROM.
4. Conditional Objects
The first step in the direction of parametrized cells: conditional objects. It is very often the case that several cells will be identical, except for a tiny geometrical difference: a contact will be missing, a wire will be shorter, . . . The idea is to draw only one cell, and create by program a family of cells which relate to it, by simply taking out some of the geometry, which thus becomes conditional. Of course you don't want to refer to an object by saying "the poly contact at coords [12, 45]", because this will be a pain to trace through edits, so we use names: to make an instance conditional, stick on it the property $PWCond with any rope as a value. Think of it as a symbolic name for this instance. Then use the function Inst which takes four arguments:
design: CD.Design -- as usual
name: Object -- a cell name
conds: LIST OF ROPE -- a list of Ropes, or conditional objects names
removeNamed: BOOL -- whether to remove or keep the listed objects; default is remove
Let's say the cell Decoder contains two objects named (with the property $PWCond) "OptionalContact" and "FatWire", among other things. If in the Patchwork program you use "Decoder", you get the complete cell with these two objects, just like usual. If you use
Inst[design, Decoder, LIST ["OptionalContact", "FatWire"], TRUE];
you get a copy of the cell with neither objects, and if you use
Inst[design, Decoder, LIST ["FatWire"], FALSE];
then "FatWire" will be present, but not "OptionalContact". Of course, several objects can carry the same name, and thus disappear always simultaneously. Any object can thus be made conditional: rectangle, contact, transistor, cell, . . .
5. Unsafe subset
Sometimes, abutment of hand-drawn cells is not sufficient to describe a piece of a chip. You might want a more powerful way of parametrizing a cell, down to the point where you want to create a cell from scratch. I assume then that you are a grown-up, and can read the interface. Briefly, let's go through an example, in the right order. You create a new cell, insert an object obj1, and finish properly:
newCell ← CreateEmptyCell[];
IncludeInCell[design, newCell, obj1, [12, 23]]; -- InterestRect coord system!!!
IncludeInDirectory[design, newCell]; -- If you forget this, or modify the content of the cell after doing this, you are in for big trouble! 
RenameObject[design, newCell, "MadeFromScratch"]; -- Not mandatory. If there is a name conflict, CD will change the name: it is only a proposition, not garanteed to make it.
Two important fine points: coordinate systems and repositioning.
ChipNDale has many coordinate systems: one for the design, one for each cell, one associated with the InterestRect, . . . Don't ask! Now, PW tries to make your life a little easy: unless it is explicitely mentionned, all coordinates refer to the [0, 0] of the InterestRect. For example, in the example above, the semantic is:
Take this obj1 in the specified orientation (in this case, original) and look at its bottom-left corner; this is the origin of the object in its InterestRect coordinate system. Now consider the cell newCell and consider the bottom-left corner of its InterestRect: that's its origin in its InterestRect coordinate system. Now inserting obj1 in newCell at location [12, 23] will bring its origin in position [12, 23] relatively to the origin of newCell.
Repositioning: whenever you create a new cell, or modify its content, CD has to reposition it, and propagates the changes throughout the design. The function IncludeInDirectory does it too, but it is important to remember that it should be called last, when the cell is in its final form. If you modify the content of an object and don't reposition it, it will display funny, plot funny, and worst of all, fabricate funny, so don't forget.
6. PWmos
A simple technology-dependant interface for PW. Helps you create rectangles (wires), contacts and transistors by program. Also provides very elementary design rules. Beware that all sizes are given in CD units, while you probably think in lambdas. The constant lambda is needed to convert. Never, never, never assume that lambda=2, even is this is true today. Lambda is whatever is defined in CD!
The function GetLayer is worth some attention: it accepts two ropes: the name of the technology (nmos or cmos) and the name of the layer, like metal, met2, poly, . . . Case does not matter and it is quite forgiving about the names. Syntax example:
poly: CD.Layer ← PWmos.GetLayer["cmos", "pol"];
wire ← PWmos.Rect[[5*l, 32*l], poly];
7. PWPins
Though it is not strictly a part of PatchWork only, you will use and love the module PWPins.
8. Becoming a user
On a Dorado running Cedar 6.0, bringover
/Cedar/ChipNDale/6.0/Top/PW21.df and /Cedar/ChipNDale/6.0/Top/CD21.df
Now start Chipndale, and issue the command
% runPW
to start PatchWork. Create a new CD design, and click inside its viewer. P-Middle calls the generator menu. At this point, you need a set of cells and a Cedar program. You can copy and edit the example of code shown previously. If you have compiled and ran your program, the menu should show "Run YourStuff Generator", where "YourStuff" is the name you registered with ChipNDale: click it to start. After some time (usually pretty short), an instance of the object should appear in the viewer.
9. Fine Points and implementation details
Trash: during the computation of the layout, PW might create some cells that are not finally included in the resulting object, but which belong to the design. It is the responsability of the user to use the CD Directory menu for deleting unused objects.
Goodies: PW also provide simple bit-manipulation routines, reverse for a lit of Objects, I/O with the CD terminal, . . .
High-level things: TransferCell.