Magic is an interactive system for creating and modifying VLSI circuit layouts. With Magic, you use a color graphics display and a mouse to design basic cells and to combine them hierarchically into large structures. Magic is different from other layout editors you may have used. The most important difference is that Magic is more than just a color painting tool: it understands quite a bit about the nature of circuits and uses this information to provide you with additional operations. For example, Magic has built-in knowledge of layout rules; as you are editing, it continuously checks for rule violations. Magic also knows about connectivity and transistors, and contains a built-in hierarchical circuit extractor. Magic also has a plow operation that you can use to stretch or compact cells. Magic has (simple) routing tools that you can use to make the global interconnections in your circuits.
Magic is based on the Mead-Conway "scalable CMOS" style of design (from the classic textbook by Carver Mead and Lynn Conway), using "lambda-based" dimensions. Whereas foundries specify detailed dimensions (physical dimensions, that is, in microns) for a specific fabrication process, "lambda" units are dimensionless. When layout data are converted to a CIF or GDS file to send to the foundry for chip fabrication, the lambda units are converted to physical units at a scale appropriate for the intended fabrication process. The advantage of scalable CMOS is that the same design can be fabricated on a different fabrication process by generating a different output file, converting the lambda units to physical dimensions at a different scale. The disadvantage of scalable CMOS is that to ensure a valid layout meeting all the design rules of all the processes, each lambda dimension must meet the worst-case design rule requirements for every process intended to be compatible with the technology file. Unless the processes are completely compatible with one another and processes at different feature sizes scale exactly, then the lambda rules cannot ever specify the densest possible widths and spacings of materials.
Independently of attempting to encompass multiple fabrication processes with one design style, lambda-based rules also attempt to simpify design style by describing most geometry with small integer units that do not vary from process to process. The foundation of this idea is the fact that process "feature sizes" are (nearly always) derived from the most critical dimension for digital circuit speed, the gate length of a MOS transistor. The "feature size" of the process is equal to the minimum gate length (or minimum nFET gate length, in the case that n and p devices have different minimum length requirements). A "0.18 micron" process is one in which the minimum nFET gate length is 0.18 microns. Lambda-based rules use the gate length as the standard measure. One lambda is equal to 1/2 minimum nFET gate length. For most processes, then, minimum dimensions generally work out to the following:
The simplifications make it easier for the layout engineer to design circuits and permit Magic to provide powerful assistance that would not be possible (or at least, prohibitively slow) otherwise. However, they result in slightly less dense circuits than you could get with more complex rules and structures. Circuit designers tell us that our conservative design rules cost 5-10% in density. We have found that the density sacrifice is compensated for by reduced design time.
Most layout editors other than Magic use manufacturers' exact design rules, and the increasing speed of microprocessors has allowed such features as interactive design rule checking to creep back into the tools as the "prohivitive computational cost" of those algorithms becomes increasingly less prohibitive. The intensely competitive nature of integrated circuit manufacture has meant that most companies have been willing to make the tradeoff of slower design times to benefit from the marginal increases in circuit density and speed. Over the long term, then, scalable CMOS rules have gradually disappeared from use. Magic versions upto and including major version 6 enjoyed a lengthy survival time for a piece of software, about 20 years from 1980 to 2000. After 2000, it was clear that the use of scalable CMOS rules had nearly vanished and was unlikely to come back. So development efforts began to lift many of the restrictions imposed by scalable CMOS rules in Magic, the result being version 7.4, combining the original scalable CMOS design style with the possibility of designing to manufacturer-specified rules.
The tutorials are not necessarily complete. Each one is designed to introduce a set of facilities, but it doesn't necessarily cover every possibility. The ultimate authority on how Magic works is the online command reference manual. This manual gives concise and complete descriptions of all the Magic commands. Once you have a general idea how a command works, the command reference manual is probably easier to consult than the tutorial. The command reference manual may not make much sense until after you've read the tutorials. The tutorials are ordered so the user can learn the most useful commands first, include information about the graphical user interface that are not covered in the command reference, and contain useful tips about good layout design using Magic's style of layout editing. Magic is fundamentally based on command-line entry of commands, and the graphical user interface and keyboard one-keystroke functions are both implemented by commands. The command reference manual explains the underlying commands, but only the tutorials explain how the key macros and graphical user interface are designed and used.
Another way of getting help is available from Magic itself. The help command will print out one line for each Magic command, giving the command's syntax and an extremely brief description of the command. This facility is useful if you've forgotten the name or exact syntax of a command. After each screenful of help information, help stops and prints "-More-". If you type a space, the next screenful of data will be output, and if you type q the rest of the output will be skipped. If you're interested in information about a particular subject, you can type
help subject
This command will print out each command description that contains the subject string.
If you have a question or problem that can't be answered with any of the above approaches, you may contact the Magic authors by sending mail to magic-dev@csl.cornell.edu. In addition to being forwarded to everyone on the mailing list, the message will be stored in the email archive, so answers to your questions will be added to the knowledge base. Like all such mailing lists, please make a good-faith effort to ensure that the question you have is not already answered in the tutorials or the email archive.
Magic maintenance is a mostly volunteer effort, so when you report a bug or ask a question, be specific. Obviously, the more specific you are, the more likely we can answer your question or reproduce the bug you found. We'll tend to answer the specific bug reports first, since they involve less time on our part. Try to describe the exact sequence of events that led to the problem, what you expected to happen, and what actually happened. If possible, find a small example that reproduces the problem and send us the relevant (small!) files so we can make it happen here. Or best of all, send us a bug fix along with a small example of the problem. Do not send any large attachments with email messages posted to magic-dev; instead, state your problem and let one of the maintainers respond so that you can send the attachments directly to him or her. Lastly, remember that there are multiple versions of Magic in existance, so it is very important to report which version of magic you are using when you report a problem.
Make sure that your DISPLAY variable is set correctly. Generally this should be done automatically. However, if you get an error message on startup to the effect that "the DISPLAY variable is not set", then set it to :0.0:
setenv DISPLAY :0.0
export DISPLAY=:0.0
DISPLAY=:0.0; export DISPLAY
The Magic window is an ordinary X11 window, and can be moved, closed, iconified, and resized using the window manager.
For now, you can skip to the next major section: Running Magic.
The X11 driver can read in window sizing and font preferences from your .Xdefaults (occasinally .Xresources) file. The following specifications are recognized:
magic.window: 1000x600+10+10
magic.newwindow: 300x300+400+100
magic.small: helvetica8
magic.medium: helvetica12
magic.large: helvetica18
magic.xlarge: helvetica24
magic.window is the size and position of the initial window, while magic.newwindow is the size and position of subsequent windows. If these are left blank, you will be prompted to give the window's position and size. small, medium, large, and xlarge are various fonts magic uses for labels. Some X11 servers read the .Xdefaults file only when you initially log in; you may have to run xrdb -load ~/.Xdefaults for the changes to take effect.
Under X11, Magic can run on a display of any depth for which there are colormap and dstyle files. Eight bit, 16 bit, 24 bit, and OpenGL files for MOS are distributed in this release. You can explicitly specify how many planes Magic is to use by prepending a number to the word "BIT" when used with Magic's "-d" option. For example, "magic -d 8BIT" runs magic on a 8 bit display and "magic -d 24BIT" runs magic on a 24 bit display. If this number is not specified, magic checks the depth of the display and picks the largest number in the set {1, 7, 8, 16, 24} that the display will support.
It is important to note a few things: Where mentioned, Magic's "7 bit" graphics actually corresponds to an 8-bit graphics visual; the 8th bit is unused due to some historical incompatibility with SunView graphics. Magic is set up to prefer 8 bit visuals over 24 bit visuals, since the 8 bit graphics are generally better-looking than the 24 bit versions, because Magic makes use of the indexed colormap to implement color blends between planes. Even with the 8 bit visuals, magic runs out of color blends after a few planes, so after the second layer of metal, Magic runs out of graphics bit planes. 24-bit graphics are not indexed color tables, and so color blends are not available at all, and all layers must be represented by stipple patterns. An alternative is the OpenGL graphics, obtained by invoking magic with the command "magic -d OGL", where color blends are hardware-supported, and so all layers can be represented with color blending. Most operating systems running graphical desktop environments use a 24-bit visual by default and cannot switch to, or display, an 8-bit window. A few graphics cards, however, implement "8-bit overlays" by using 32-bit graphics with the lower 24 bits mapped to a 24-bit display and the upper 8-bits mapped to an 8-bit indexed colormap. Magic will use the 8-bit overlay if it is available.
Almost all graphics cards support 8-bit visuals. However, if the graphical desktop is already running, it probably has already specified a 24-bit visual. To force 8-bit graphics, it is necessary to set desktop preferences to use 8-bit graphics, and it will be necessary to restart the desktop session before the 8-bit graphics will be in effect. From the UNIX/Linux terminal command line, the usual way to start X11 with a specific visual depth is to use the command "startx -depth depth".
Another way to force the display type is to set an environment variable called MAGIC_COLOR to one of the strings "8bit", "16bit", or "24bit".
X11 remote usage note:
When running Magic remotely on an X11 terminal, the colormap allocation
may differ for the local machine compared to the remote machine. In
some cases, this can cause the background of magic to appear black,
usually with a black-on-black cursor. This is known to be true of
X11 drivers for Windows (such as PC-XWare), due to the way the Windows
8-bit PseudoColor colormap is defined. This behavior can be corrected
by setting two environment variables on the remote machine as follows:
setenv X_COLORMAP_BASE 128
setenv X_COLORMAP_DEFAULT 0
This causes Magic to avoid trying to allocate the first color in the colormap, which under Windows is fixed as black.
From this point on, you should be sitting at a Magic workstation so you can experiment with the program as you read the manuals. Starting up Magic is usually pretty simple. Just log in and, if needed, start up your favorite window system. Then type the shell command
magic tut1
Tut1 is the name of a library cell that you will play
with in this tutorial.
At this point, several colored rectangles should appear
on the color display along with a white box and a cursor.
A ">" prompt should appear, and a message will
be printed on the title bar of the display
telling you that the "edit cell" is tut1. If the
title bar also reports that it isn't writable
("[NOT BEING EDITED]"), then you should follow the
advice at the beginning of the section "", and copy all the files in the tutorial
install directory to your current working directory. Magic's
default search path for cells starts with the current working
directory and ends with the tutorial directory, so if you
copy the cells and run "magic tut1", you will load the
local copy of tut1 (which is writable), not the
copy from the installed tutorial directory (which is not).
If everything has happened as described above, then you can
skip the rest of this section (except for the note below) and
go directly to The Box and the Cursor.
Note: in the tutorials, when you see things printed in boldface,
for example, magic tut1 from above, they refer to things
you type exactly, such as command names and file names. These
are usually case sensitive (A is different from a).
When you see things printed in italics, they refer to classes of
things you might type. Key macros are distinguished from commands
in the tutorials by having the command as a hypertext link to the
web page explaining that command. This replaces the original
notation of printing the colon character before the command.
Arguments in square brackets are optional. For example, a more
complete description of the shell command for Magic is
You could type any file name for file, and
Magic would start editing that file. The name tut1
is just a file (tut1.mag) in Magic's cell library.
If you didn't type a file name, Magic would load a new blank
cell.
If things didn't happen as they should have when you tried to
run Magic, any of several things could be wrong. If a message
of the form "magic: Command not found" appears on your screen
it is because the shell couldn't find the Magic program. The
default install location of Magic is the directory
/usr/local/bin. You should make sure that this
directory is in your shell path. If this sounds like gibberish,
find a Unix hacker and have him or her explain to you about paths.
If worst comes to worst, you can invoke Magic by typing its full name:
Another possible problem is that
Magic might not know what kind of display you are using.
To solve this, use magic's -d flag:
Try invoking Magic with different display types and note the difference
in the way the layout of file tut1 is displayed. In cases where
the display type is not available, magic may not display any window at
all. If so, quit by typing "exit".
Note that the use of the mouse buttons described above is a
functional binding. Magic has a number of different
"tools", each of which has its own set of mouse button bindings.
In Magic, a "tool" is defined by a specific set of mouse
button bindings. The bindings described above define the "box
tool". If the crosshair cursor is not displayed, then
it is likely that a tool other than the "box tool" is in
effect, and the mouse button bindings won't work as described.
If this happens (which is rather easy, as the space bar is used
to switch between tools, and is easy to press by accident), then
keep tapping the space bar until the crosshair cursor appears
again, showing that Magic is back in the "box tool" mode. Or
you can type the command
"tool box" to force
Magic to switch immediately to the box tool mouse bindings.
Sometimes it is convenient to move the box by a corner other
than the lower left. To do this, move the cursor to a different
place on the screen. Hold down the Shift key, then click the
right mouse button. The box should move so that its lower right
corner is at the cursor position. Try using this feature to
move the box so that it is almost entirely off-screen to the
left. Try moving the box by each of its corners.
You can also reshape the box by corners other than the upper
right. To do this, move the cursor to some other position
on the screen. Press the Shift key and hold it down, then press
the left mouse button. The box will reshape so that the selected
corner is at the cursor position but the diagonally opposite corner
is unchanged. Try reshaping the box by each of its corners.
Usually it suffices to use only the standard (without the Shift
key) bindings to perform box placement and reshaping. It is
important to understand that, unlike many layout tools where the
fundamental layout elements are "wires" and "shapes", Magic is
based on the concept of "paint" and "erase", where the paint and
erase functions are done on the area inside the box. A few
functions (especially the interactive ones) depend on the location
of the cursor, but most depend on the position of the box. A
very common error message in magic is:
A common error message related to the cursor is something like
the following:
To see how commands can be invoked from the buttons, first
position the box over a small blank area in the middle of the
screen. Then move the cursor over the red rectangle and
press the middle mouse button. At this point, the area of the
box should get painted red. Now move the cursor over empty space
and press the middle button again. The red paint should go away.
Note how this command uses both the cursor and box locations
to control what happens. If the Shift key is held down while the
middle mouse button is clicked, the area inside the box is always
erased. Once again, these are the mouse button bindings that
apply specifically to the "box tool".
As an example of a macro, type the g key on
the text keyboard. A grid will appear on the color display, along
with a small black box marking the origin of the cell.
If you type g again, the grid will go away. You
may have noticed earlier that the box corners didn't move to
the exact cursor position: you can see now that the box is
forced to fall on grid points.
Since both key macros and long commands require typing on the
keyboard, it helps to understand the difference between the way
Magic processes keystrokes. On startup, Magic brings up two
windows: The layout window, and the terminal window.
Depending on how Magic is compiled or invoked (e.g., compiled
with or without Tcl interpreter support), the terminal window
may be the X11 terminal (e.g., "xterm") from which magic was
started. Or it may be a separate window on the display (the
Tk Console, or "tkcon"). In either case, if the terminal window
has keyboard focus, commands will be written into the
terminal window and executed at the end-of-line ("Enter" or
"Return"), as they would on a UNIX command line. If the layout
window has keyboard focus, then single keystrokes are
interpreted, one at a time, as key macros. However, moving
the mouse cursor between the layout window and the terminal
window can seriously impact the efficiency of drawing layout
(read: it slows you down). So Magic implements one special
key macro, the "long command macro" (normally bound to the
keys ":" (colon) or ";" (semicolon)). When this
key is pressed, magic transfers keyboard focus automatically
from the layout window to the terminal window. Subsequent
keystrokes are redirected to the terminal window. Upon a
"Enter" ("Return") key stroke, the typed command is executed,
and keyboard focus is automatically returned to the layout window.
Note that while typing is being redirected to the terminal
window, it is still possible to execute mouse button functions.
It is also possible to move the mouse to the terminal window to
override the automatic keyboard focus redirection, and finish
typing the command there.
Window managers in X11 usually have an option for keyboard
focus model. There are two standard models: "click to focus",
and "focus on enter". In the first case, keyboard focus changes
only when the mouse button is clicked on the window title. In
the second case, a window takes keyboard focus whenever the mouse
cursor is inside the window, and loses keyboard focus when the
mouse cursor leaves the window. This second method works better
with Magic, due to the two-window setup with layout and terminal
windows. Regardless of the focus model, automatic change of
keyboard focus when the "long command macro" is invoked is the
same (it overrides the window manager's keyboard focus model).
Long commands are invoked by typing a colon (":") or
semi-colon (";") into the layout window, as a key macro. After you
type the colon or semi-colon, the ">" prompt on the text
screen will be replaced by a ":" prompt. This indicates
that Magic has redirected keyboard focus to the terminal window
and is waiting for a long command to be typed. At this point
you should type a line of text, followed by Return.
When the long command has been processed, the ">" prompt
reappears on the text display. Try typing semi-colon followed by
return to see how this works. Occasionally a "]" (right bracket)
prompt will appear. This means that the design-rule checker is re-verifying
part of your design. For now you can just ignore this and treat
"]" like ">".
Each long command consists of the name of the command followed
by arguments, if any are needed by that command. The command
name can be abbreviated, just as long as you type enough
characters to distinguish it from all other long commands.
For example, h and he may be used as abbreviations for
help. On the other hand,
u may not be used as an abbreviation for
undo because there is
another command,
upsidedown, that
has the same abbreviation. Try typing u on the command line.
As an example of a long command, put the box over empty space on
the color display, then invoke the long command
The box should fill with the red color, just as if you had
used the middle mouse button to paint it. Everything you can
do in Magic can be invoked with a long command. It turns out that
the macros are just conveniences that are expanded into long
commands and executed. For example, the long command equivalent
to the g macro is
Magic permits you to define new macros if you wish. Once you've
become familiar with Magic you'll almost certainly want to add
your own macros so that you can invoke quickly the commands you
use most frequently. See the description of the command
macro.
One more long command is of immediate use to you. It is
In the version of Magic with Tcl interpreter support, the
Magic commands, including
"quit"
are registered with
the interpreter after the program performs its initial
startup. Certain errors, like the failure to find a supported
graphics display type, will leave magic in this pre-initialized
state. If that is the case, the
quit command will not
be recognized! When this happens, use the Tcl exit
command to end Magic.
Last updated: February 13, 2006 at 2:38pm
magic [file]
/usr/local/bin/magic tut1
magic -d display tut1
The Box and the Cursor
Two things, the box and the cursor, are used
to select things on the layout display. As you move the
mouse, the cursor moves on the screen. The cursor starts out
with a crosshair shape, but you'll see later that its shape
changes as you work to provide feedback about what you're
doing. The left and right
mouse buttons are used to position the box. If you press the
left mouse button and then release it, the box will move so
that its lower left corner is at the cursor position. If
you press and release the right mouse button, the upper right
corner of the box will move to the cursor position, but the
lower left corner will not change. These two buttons are
enough to position the box anywhere on the screen. Try using
the buttons to place the box around each of the colored rectangles
on the screen.
The box isn't in a window on the edit cell.
This means that the box isn't drawn on the layout window where
you are trying to invoke some function like painting that depends
on the presence of the box. Usually the solution is just to click
the mouse button on the layout window to force the box to be
created.
Unknown command: 'paint' 'm1' at (460, -11)
This error message happens because Magic can have more than one
layout window present at a time, with different layouts in each,
and Magic needs to know definitively which window is the
intended recipient of each command. Usually the problem that
causes this particular error message is that the cursor has drifted
out of the drawing part of the layout window (even though it may
still be inside the scrollbars or other sub-windows of the layout
window).
Did you point to the correct window?
Invoking Commands
Commands can be invoked in Magic in four ways: By pressing
buttons on the mouse, by typing single keystrokes on the
text keyboard (these are called macros), by typing
longer commands on the text keyboard (these are called long
commands), or by selecting a function from a button on the
frame of the layout (either a menu button at the top or a button
in the layer toolbar on the right side, when the toolbar option is
selected). Magic is set up such that the most critical common
functions are bound to mouse buttons, other common functions are
bound to key macros, and less often-used functions are left as
commands. This setup facilitates the quickest layout generation.
paint red
grid
quit
R. Timothy Edwards
2006-02-17