Magic Tutorial #2: Basic Painting and Selection

John Ousterhout
(updated by others, too)
active version by Mário Silva, silva@cs.Berkeley.EDU)

Computer Science Division
Electrical Engineering and Computer Sciences
University of California
Berkeley, CA 94720

This tutorial corresponds to Magic version 6.

Tutorials to read first:

Magic Tutorial #1: Getting Started

Commands introduced in this tutorial:

:box, :clockwise, :copy, :erase, :findbox :grid, :label, :layers, :macro, :move, :paint, :redo, :save, :select, :sideways, :undo, :upsidedown, :view, :what, :writeall, :zoom

Macros introduced in this tutorial:

a, A, c, d, ^D, e, E, g, G, q, Q, r, R, s, S, t, T, u, U, v, w, W, z, Z, 4

1. Cells and Paint

In Magic, a circuit layout is a hierarchical collection of cells. Each cell contains three things: colored shapes, called paint, that define the circuit's structure; textual labels attached to the paint; and subcells, which are instances of other cells. The paint is what determines the eventual function of the VLSI circuit. Labels and subcells are a convenience for you in managing the layout and provide a way of communicating information between various synthesis and analysis tools. This tutorial explains how to create and edit paint and labels in simple single-cell designs, using the basic painting commands. `Magic Tutorial #3: Advanced Painting (Wiring and Plowing)'' describes some more advanced features for manipulating paint. For information on how to build up cell hierarchies, see `Magic Tutorial #4: Cell Hierarchies''.

2. Painting and Erasing

Enter Magic to edit the cell tut2a (type magic tut2a to the Unix shell; follow the directions in `Tutorial #1: Getting Started'' if you have any problems with this). The tut2a cell is a sort of palette: it shows a splotch of each of several paint layers and gives the names that Magic uses for the layers.

The two basic layout operations are painting and erasing. They can be invoked using the :paint and :erase long commands, or using the buttons. The easiest way to paint and erase is with the mouse buttons. To paint, position the box over the area you'd like to paint, then move the cursor over a color and click the middle mouse button. To erase everything in an area, place the box over the area, move the cursor over a blank spot, and click the middle mouse button. Try painting and erasing various colors. If the screen gets totally messed up, you can always exit Magic and restart it. While you're painting, white dots may occasionally appear and disappear. These are design rule violations detected by Magic, and will be explained in `Magic Tutorial #6: Design Rule Checking''. You can ignore them for now.

It's completely legal to paint one layer on top of another. When this happens, one of three things may occur. In some cases, the layers are independent, so what you'll see is a combination of the two, as if each were a transparent colored foil. This happens, for example, if you paint metal1 (blue) on top of polysilicon (red). In other cases, when you paint one layer on top of another you'll get something different from either of the two original layers. For example, painting poly on top of ndiff produces ntransistor (try this). In still other cases the new layer replaces the old one: this happens, for example, if you paint a pcontact on top of ntransistor. Try painting different layers on top of each other to see what happens. The meaning of the various layers is discussed in more detail in Section 11 below.

There is a second way of erasing paint that allows you to erase some layers without affecting others. This is the macro ^D (control-D, for `Delete paint''). To use it, position the box over the area to be erased, then move the crosshair over a splotch of paint containing the layer(s) you'd like to erase. Type ^D key on the text keyboard: the colors underneath the cursor will be erased from the area underneath the box, but no other layers will be affected. Experiment around with the ^D macro to try different combinations of paints and erases. If the cursor is over empty space then the ^D macro is equivalent to the middle mouse button: it erases everything.

You can also paint and erase using the long commands

:paint layers

:erase layers

In each of these commands layers is one or more layer names separated by commas (you can also use spaces for separators, but only if you enclose the entire list in double-quotes). Any layer can be abbreviated as long as the abbreviation is unambiguous. For example, :paint poly,metal1 will paint the polysilicon and metal1 layers. The macro ^D is predefined by Magic to be :erase $ ($ is a pseudo-layer that means ``all layers underneath the cursor'`).

3. Undo

There are probably going to be times when you'll do things that you'll later wish you hadn't. Fortunately, Magic has an undo facility that you can use to restore things after you've made mistakes. The command

:undo

(or, alternatively, the macro u) will undo the effects of the last command you invoked. If you made a mistake several commands back, you can type :undo several times to undo successive commands. However, there is a limit to all this: Magic only remembers how to undo the last ten or so commands. If you undo something and then decide you wanted it after all, you can undo the undo with the command

:redo

(U is a macro for this command). Try making a few paints and erases, then use :undo and :redo to work backwards and forwards through the changes you made.

4. The Selection

Once you have painted a piece of layout, there are several commands you can invoke to modify the layout. Many of them are based on the selection: you select one or more pieces of the design, and then perform operations such as copying, deletion, and rotation on the selected things. To see how the selection works, load cell tut2b. You can do this by typing :load tut2b if you're still in Magic, or by starting up Magic with the shell command magic tut2b.

The first thing to do is to learn how to select. Move the cursor over the upper portion of the L-shaped blue area in tut2b, and type s, which is a macro for :select. The box will jump over to cover the vertical part of the ``L'`. This operation selected a chunk of material. Move the box away from the chunk, and you'll see that a thin white outline is left around the chunk to show that it's selected. Now move the cursor over the vertical red bar on the right of the cell and type s. The box will move over that bar, and the selection highlighting will disappear from the blue area.

If you type s several times without moving the cursor, each command selects a slightly larger piece of material. Move the cursor back over the top of the blue ``L'`, and type s three times without moving the cursor. The first s selects a chunk (a rectangular region all of the same type of material). The second s selects a region (all of the blue material in the region underneath the cursor, rectangular or not). The third s selects a net (all of the material that is electrically connected to the original chunk; this includes the blue metal, the red polysilicon, and the contact that connects them).

The macro S (short for :select more) is just like s except that it adds on to the selection, rather than replacing it. Move the cursor over the vertical red bar on the right and type S to see how this works. You can also type S multiple times to add regions and nets to the selection.

If you accidentally type s or S when the cursor is over space, you'll select a cell (tut2b in this case). You can just undo this for now. Cell selection will be discussed in `Magic Tutorial #4: Cell Hierarchies''.

You can also select material by area: place the box around the material you'd like to select and type a (short for :select area). This will select all of the material underneath the box. You can use the macro A to add material to the selection by area, and you can use the long command

:select [more] area layers

to select only material on certain layers. Place the box around everything in tut2b and type :select area metal1 followed by :select more area poly.

If you'd like to clear out the selection without modifying any of the selected material, you can use the command

:select clear

or type the macro C. You can clear out just a portion of the selection by typing :select less or :select less area layers; the former deselects paint in the order that :select selects paint, while the latter deselects paint under the box (just as :select area selects paint under the box). For a synopsis of all the options to the :select command, type

:select help

5. Operations on the Selection

Once you've made a selection, there are a number of operations you can perform on it:

:delete

:move [direction [distance]]

:stretch [direction [distance]]

:copy

:upsidedown

:sideways

:clockwise [degrees]

The :delete command deletes everything that's selected. Watch out: :delete is different from :erase, which erases paint from the area underneath the box. Select the red bar on the right in tut2b and type d, which is a macro for :delete. Undo the deletion with the u macro.

The :move command picks up both the box and the selection and moves them so that the lower-left corner of the box is at the cursor location. Select the red bar on the right and move it so that it falls on top of the vertical part of the blue ``L'`. You can use t (`translate'') as a macro for :move. Practice moving various things around the screen. The command :copy and its macro c are just like :move except that a copy of the selection is left behind at the original position.

There is also a longer form of the :move command that you can use to move the selection a precise amount. For example, :move up 10 will move the selection (and the box) up 10 units. The direction argument can be any direction like left, south, down, etc. See the Magic manual page for a complete list of the legal directions. The macros q, w, e, and r are defined to move the selection left, down, up, and right (respectively) by one unit.

The :stretch command is similar to :move except that it stretches and erases as it moves. :stretch does not operate diagonally, so if you use the cursor to indicate where to stretch to, Magic will either stretch up, down, left, or right, whichever is closest. The :stretch command moves the selection and also does two additional things. First, for each piece of paint that moves, :stretch will erase that layer from the region that the paint passes through as it moves, in order to clear material out of its way. Second, if the back edge of a piece of selected paint touches non-selected material, one of the two pieces of paint is stretched to maintain the connection. The macros Q, W, E, and R just like the macros q, etc. described above for :move. The macro T is predefined to :stretch. To see how stretching works, select the horizontal piece of the green wire in tut2b and type W, then E. Stretching only worries about material in front of and behind the selection; it ignores material to the sides (try the Q and R macros to see). You can use plowing (described in Tutorial #3) if this is a problem.

The command :upsidedown will flip the selection upside down, and :sideways flips the selection sideways. Both commands leave the selection so it occupies the same total area as before, but with the contents flipped. The command :clockwise will rotate the selection clockwise, leaving the lower-left corner of the new selection at the same place as the lower-left corner of the old selection. Degrees must be a multiple of 90, and defaults to 90.

At this point you know enough to do quite a bit of damage to the tut2b cell. Experiment with the selection commands. Remember that you can use :undo to back out of trouble.

6. Labels

Labels are pieces of text attached to the paint of a cell. They are used to provide information to other tools that will process the circuit. Most labels are node names: they provide an easy way of referring to nodes in tools such as routers, simulators, and timing analyzers. Labels may also be used for other purposes: for example, some labels are treated as attributes that give Crystal, the timing analyzer, information about the direction of signal flow through transistors.

Load the cell tut2c and place a cross in the middle of the red chunk (to make a cross, position the lower-left corner of the box with the left button and then click the right button to place the upper-right corner on top of the lower-left corner). Then type type the command :label test. A new label will appear at the position of the box. The complete syntax of the :label command is

:label [text [position [layer]]]

Text must be supplied, but the other arguments can be defaulted. If text has any spaces in it, then it must be enclosed in double quotes. Position tells where the text should be displayed, relative to the point of the label. It may be any of north, south, east, west, top, bottom, left, right, up, down, center, northeast, ne, southeast, se, southwest, sw, northwest, nw. For example, if ne is given, the text will be displayed above and to the right of the label point. If no position is given, Magic will pick a position for you. Layer tells which paint layer to attach the label to. If layer covers the entire area of the label, then the label will be associated with the particular layer. If layer is omitted, or if it doesn't cover the label's area, Magic initially associates the label with the ``space'` layer, then checks to see if there's a layer that covers the whole area. If there is, Magic moves the label to that layer. It is generally a bad idea to place labels at points where there are several paint layers, since it will be hard to tell which layer the label is attached to. As you edit, Magic will ensure that labels are only attached to layers that exist everywhere under the label. To see how this works, paint the layer pdiff (brown) over the label you just created: the label will switch layers. Finally, erase poly over the area, and the label will move again.

Although many labels are point labels, this need not be the case. You can label any rectangular area by setting the box to that area before invoking the label command. This feature is used for labelling terminals for the router (see below), and for labelling tiles used by Mpack, the tile packing program. Tut2c has examples of point, line, and rectangular labels.

All of the selection commands apply to labels as well as paint. Whenever you select paint, the labels attached to that paint will also be selected. Selected labels are highlighted in white. Select some of the chunks of paint in tut2c to see how the labels are selected too. When you use area selection, labels will only be selected if they are completely contained in the area being selected. If you'd like to select just a label without any paint, make the box into a cross and put the cross on the label: s and S will select just the label.

There are several ways to erase a label. One way is to select and then delete it. Another way is to erase the paint that the label is attached to. If the paint is erased all around the label, then Magic will delete the label too. Try attaching a label to a red area, then paint blue over the red. If you erase blue the label stays (since it's attached to red), but if you erase the red then the label is deleted.

You can also erase labels using the :erase command and the pseudo-layer labels. The command

:erase labels

will erase all labels that lie completely within the area of the box. Finally, you can erase a label by making the box into a cross on top of the label, then clicking the middle button with the cursor over empty space. Technically, this will erase all paint layers and labels too. However, since the box has zero area, erasing paint has no effect: only the labels are erased.