Provided by:
magic_7.5.214-1_i386 
NAME
magic - format of .mag files read/written by Magic
DESCRIPTION
Magic uses its own internal ASCII format for storing cells in disk
files. Each cell name is stored in its own file, named name.mag.
The first line in a .mag file is the string
magic
to identify this as a Magic file.
The next line is optional and is used to identify the technology in
which a cell was designed. If present, it should be of the form
tech techname
If absent, the technology defaults to a system-wide standard, currently
nmos.
The next line is also optional and gives a timestamp for the cell. The
line is of the format
timestamp stamp
where stamp is a number of seconds since 00:00 GMT January 1, 1970
(i.e, the Unix time returned by the library function time()). It
should be the last time this cell or any of its children changed. The
timestamp is used to detect when a child is edited outside the context
of its parent (the parent stores the last timestamp it saw for each of
its children; see below). When this occurs, the design-rule checker
must recheck the entire area of the child for subcell interaction
errors. If this field is omitted in a cell, Magic supplies a default
value that forces the rechecks.
Next come lines describing the contents of the cell. There are three
kinds of groups of lines, describing mask rectangles, subcell uses, and
labels. Each group must appear contiguously in the file, but the order
between groups is arbitrary.
Each group of mask rectangles is headed with a line of the format
<< layer >>
where layer is a layername known in the current technology (see the
tech line above). Each line after this header has the format
rect xbot ybot xtop ytop
where (xbot, ybot) is the lower-left corner of the rectangle in Magic
(lambda) coordinates, and (xtop, ytop) is the upper-right corner.
Degenerate rectangles are not allowed; xbot must be strictly less than
xtop, and ybot strictly less than ytop. The smallest legal value of
xbot or ybot is -67108858, and the largest legal value for xtop or ytop
is 67108858. Values that approach these limits (within a factor of 100
or 1000) may cause numerical overflows in Magic even though they are
not strictly illegal. We recommend using coordinates around zero as
much as possible.
Rectangles should be non-overlapping, although this is not essential.
They should also already have been merged into maximal horizontal
strips (the neighbor to the right or left of a rectangle should not be
of the same type), but this is also not essential.
The second kind of line group describes a single cell use. Each cell
use group is of the following form:
use filename use-id
array xlo xhi xsep ylo yhi ysep
timestamp stamp
transform a b c d e f
box xbot ybot xtop ytop
A group specifies a single instance of the cell named filename, with
instance-identifier use-id. The instance-identifier use-id must be
unique among all cells used by this .mag file. If use-id is not
specified, a unique one is generated automatically.
The array line need only be present if the cell is an array. If so,
the X indices run from xlo to xhi inclusive, with elements being
separated from each other in the X dimension by xsep lambda. The Y
indices run from ylo to yhi inclusive, with elements being separated
from each other in the Y dimension by ysep lambda. If xlo and xhi are
equal, xsep is ignored; similarly if ylo and yhi are equal, ysep is
ignored.
The timestamp line is optional; if present, it gives the last time this
cell was aware that the child filename changed. If there is no
timestamp line, a timestamp of 0 is assumed. When the subcell is read
in, this value is compared to the actual value at the beginning of the
child cell. If there is a difference, the ``timestamp mismatch''
message is printed, and Magic rechecks design-rules around the child.
The transform line gives the geometric transform from coordinates of
the child filename into coordinates of the cell being read. The six
integers a, b, c, d, e, and f are part of the following transformation
matrix, which is used to postmultiply all coordinates in the child
filename whenever their coordinates in the parent are required:
a d 0
b e 0
c f 1
Finally, box gives an estimate of the bounding box of cell filename
(covering all the elements of the array if an array line was present),
in coordinates of the cell being read.
The third kind of line group in a .mag file is a list of labels. It
begins with the line
<< labels >>
and is followed by zero or more lines of the following form:
rlabel layer xbot ybot xtop ytop position text
Here layer is the name of one of the layers specified in the technology
file for this cell. The label is attached to material of this type.
Layer may be space, in which case the label is not considered to be
attached to any layer.
Labels are rectangular. The lower-left corner of the label (the part
attached to any geometry if layer is non-space) is at (xbot, ybot), and
the upper-right corner at (xtop, ytop). The width of the rectangle or
its height may be zero. In fact, most labels in Magic have a lower-
left equal to their upper right.
The text of the label, text, may be any sequence of characters not
including a newline. This text is located at one of nine possible
orientations relative to the center of the label's rectangle. Position
is an integer between 0 and 8, each of which corresponds to a different
orientation:
0 center
1 north
2 northeast
3 east
4 southeast
5 south
6 southwest
7 west
8 northwest
A .mag file is terminated by the line
<< end >>
Everything following this line is ignored.
Any line beginning with a pound sigh (``#'') is considered to be a
comment and ignored. Beware, however, that these comments are
discarded by Magic when it reads a cell, so if that cell is written
again by Magic, the comments will be lost.
NOTE FOR PROGRAMS THAT GENERATE MAGIC FILES
Magic's incremental design rule checker expects that every cell is
either completely checked, or contains information to tell the checker
which areas of the cell have yet to be examined for design-rule
violations. To make sure that the design-rule checker verifies all the
material that has been generated for a cell, programs that generate
.mag files should place the following rectangle in each file:
<< checkpaint >>
rect xbot ybot xtop ytop
This rectangle may appear anywhere a list of rectangles is allowed;
immediately following the timestamp line at the beginning of a .mag
file is a good place. The coordinates xbot etc. should be large enough
to completely cover anything in the cell, and must surround all this
material by at least one lambda. Be careful, however, not to make this
area too ridiculously large. For example, if you use the maximum and
minimum legal tile coordinates, it will take the design-rule checker an
extremely long time to recheck the area.
SEE ALSO
magic(1)