Magic VLSI Layout Tool Version 8.2 *

Magic Tutorial #9: Format Conversion for CIF and GDS

John Ousterhout

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

(Updated by others, too.)

This tutorial corresponds to Magic version 7.

Tutorials to read first:

Magic Tutorial #1: Getting Started
Magic Tutorial #2: Basic Painting and Selection
Magic Tutorial #4: Cell Hierarchies

Commands introduced in this tutorial:

gds, cif

Macros introduced in this tutorial:



CIF (Caltech Intermediate Form) and GDSII (GDS) Stream Format are standard layout description languages used to transfer mask-level layouts between organizations and design tools. This tutorial describes how Magic can be used to read and write files in CIF and GDS formats. The version of CIF that Magic supports is CIF 2.0; it was at one time the most popular layout language in the university design community. The GDSII Stream format, version 3.0, corresponds to GDSII Release 5.1. This has become the most popular layout description language for integrated circuit layouts. The "II" in "GDSII" means "2" (not like the "II" in "ASCII"). Since whatever corresponded to version "I" has long since been forgotten, the terms "GDS" and "GDSII" tend to be used interchangeably. Both terms, used in the tutorial, refer to the GDSII Stream format. The name "GDS" refers to the company that introduced the GDS format (a subsidiary of General Electric; to my knowledge, the company no longer exists). The name is rarely encountered anymore.

To write out a CIF file, place the cursor over a layout window and type the command


This will generate a CIF file called name.cif, where name is the name of the root cell in the window. The CIF file will contain a description of the entire cell hierarchy in that window. If you wish to use a name different from the root cell, type the command

cif write file

This will store the CIF in file.cif. Start Magic up to edit tut9a and generate CIF for that cell. The CIF file will be in ASCII format, so you can use Unix commands like more and vi to see what it contains.

To read a CIF file into Magic, place the cursor over a layout window and type the command

cif read file

This will read the file file.cif (which must be in CIF format), generate Magic cells for the hierarchy described in the file, make the entire hierarchy a subcell of the edit cell, and run the design-rule checker to verify everything read from the file. Information in the top-level cell (usually just a call on the "main" cell of the layout) will be placed into the edit cell. Start Magic up afresh and read in tut9a.cif, which you created above. It will be easier if you always read CIF when Magic has just been started up: if some of the cells already exist, the CIF reader will not overwrite them, but will instead use numbers for cell names.

To read and write GDS-format files, use the commands

gds read gds write
These commands have the same effect as the CIF commands, except that they operate on GDS files (usually with .gds extensions). GDS is a binary format, so you can't examine .gds files with a text editor. There is a set of utilities called "stream_utils-0.11" (last known version) containing formatting tools "sf2ascii" and "ascii2sf". These are recommended for viewing and manipulating (to a limited extent) GDS format files. The command name in Magic was originally "calma" instead of "gds"; the commands are equivalent, and either form may be used.

GDS files do not identify a top-level cell, so you won't see anything on the screen after you've used the gds read command. You'll have to use the load command to look at the cells you read. However, if Magic was used to write the GDS file being read, the library name reported by the gds read command is the same as the name of the root cell for that library. Since after loading a GDS file, you may not necessarily know what the top-level cell is, you can query the cell hierarchy using the "cellname top" command.

GDS format places some limitations on the names of cells: They can only contain alphanumeric characters, "$", and "_", and can be at most 32 characters long. If the name of a cell does not meet these limitations, "gds write" converts it to a unique name of the form n, where n is a small integer. To avoid any possible conflicts, you should avoid using names like these for your own cells.

You shouldn't need to know much more than what's above in order to read and write CIF and GDS. The sections below describe the different styles of CIF/GDS that Magic can generate and the limitations of the CIF/GDS facilities (you may have noticed that when you wrote and read CIF above you didn't quite get back what you started with; Section 3 describes the differences that can occur). Although much the discussion centers around the CIF format, the same features and problems apply to GDS.


Magic usually knows several different ways to generate CIF/GDS from a given layout. Each of these ways is called a style, and is defined in the technology file loaded on startup. Different styles can be used to handle different fabrication facilities, which may differ in the names they use for layers or in the exact mask set required for fabrication. Different styles can be also used to write out CIF/GDS with slightly different feature sizes or design rules. CIF/GDS styles are described in the technology file that Magic reads when it starts up; the exact number and nature of the styles is determined by whoever wrote the technology file. There are separate styles for reading and writing CIF/GDS; at any given time, there is one current input style and one current output style.

The standard SCMOS technology file provides an example of how different styles can be used. Start up Magic with the SCMOS technology (magic -T scmos). Then type the commands

cif listall ostyle
cif listall istyle
cif ostyle
cif istyle

The first command will print out a list of all the styles in which Magic can write CIF/GDS (in this technology) and the second command prints out the styles in which Magic can read CIF/GDS. The third and fourth forms print out the style currently being used. You use the cif command to change the current input or output style, but the styles are used for both CIF and GDS format conversion. The SCMOS technology file provides several output styles. The initial (default) style for writing CIF/GDS is lambda=1.0(gen). This style generates mask layers for the MOSIS scalable CMOS process, where each Magic unit corresponds to 1 micron and both well polarities are generated. See the technology manual for more information on the various styles that are available. You can change the output style with the command

cif ostyle newStyle

where newStyle is the new style you'd like to use for output. After this command, any future CIF or GDS files will be generated with the new style. The cif istyle command can be used in the same way to see the available styles for reading CIF and to change the current style.

The Tcl/Tk-based version of Magic has a pop-up window called the "Technology File Manager". To access it, choose the menu button "Options" followed by the button "Tech Manager". The popup window tells you which technology has been loaded, including any version information and the description given in the first few lines of the file. It also tells you the current CIF/GDS input and output styles. The style name is a button: If you click on the style name and hold down the mouse button, you will get a selectable drop-down menu list of all the available styles, from which you can choose a new style.

Each style has a specific scalefactor; you can't use a particular style with a different scalefactor. To change the scalefactor, you'll have to edit the appropriate style in the cifinput or cifoutput section of the technology file. This process is described in "Magic Maintainer's Manual #2: The Technology File.".


The units used for coordinates in Magic are generally different from those in CIF files. In Magic, most technology files use lambda-based units, where one unit is typically half the minimum feature size. In CIF files, the units are centimicrons (hundredths of a micron). When reading CIF and GDS files, an integer scalefactor is used to convert from centimicrons to Magic units. If the CIF file contains coordinates that don't scale exactly to integer Magic units, Magic may do one of several things. If the input resolves itself to an integer unit eventually (CIF boxes are given by centerpoint, width, and height; a box with an odd-valued height and odd-valued centerpoint Y coordinate will resolve to a box in magic with corners on integer gridpoints), Magic will handle the half-lambda coordinate without comment. Otherwise, Magic will rescale its own internal grid as needed to handle the input coordinate. The scaling operation is equivalent to executing the magic command

scalegrid a b
There are cases where one may want to purposely rescale an input file to a different feature size, and may prefer that magic round the dimensions to the nearest lambda rather than rescale its internal grid. To force magic to not rescale its internal grid, use the command option
cif rescale false
gds rescale false
Because the current style has a unique scalefactor, and because the same style is used for both CIF and GDS, the two commands above are equivalent.

Technology files usually specify geometrical operations such as bloating, shrinking, and-ing, and or-ing to be performed on CIF or GDS geometries when they are read into Magic. These geometrical operations are all performed in the CIF coordinate system (centimicrons) or GDS coordinate system (usually nanometers) so there is no rounding or loss of accuracy in these operations, even when scaling is disallowed. Rounding of units occurs only AFTER the geometrical operations, at the last possible instant before entering paint into the Magic database.

Non-Manhattan Geometries

Magic supports both Manhattan and non-Manhattan features. Its representation of non-Manhattan geometry is a clever extension of the corner-stitched plane database method. A non-Manhattan tile in Magic is a rectangular tile that is split, corner to corner, into two triangles, with each triangle having its own paint type. While this representation fits well with Magic's search algorithms and paint manipulation techniques, it is unable to represent every possible non-Manhattan geometry that might be encountered in an arbitrary input file. The representation works best for simple polygons (such as octagonal pads, or beveled corners on high-frequency microstrip transmission line bends). It works least well for narrow diagonal wires and shapes with cut-outs (especially polygons that wrap around and touch themselves, like a doughnut shape). Shapes with cut-out interiors are a truly difficult problem with the algorithm Magic uses. Narrow angled wires, or angled polygons with narrow spaces between, are best handled when each is generated inside its own subcell. There is an option to do this:

cif polygon subcells yes
gds polygon subcells yes
These operations are tracked independently by Magic, and so these two commands are not equivalent; one applies specifically to CIF input, and the other specifically to GDS input.

In many cases, the difference in input due to having polygons placed in subcells or not will not be noticeable. Sometimes, there is no visible difference at all, but when the polygons are dropped into the same cell as the rest of the layout, many tiny triangles will be needed to represent the figure, and subsequent output of the same geometry will be a much larger file than the input. In the worst case, the geometry may not be represented exactly as encountered in the file, and certain points along the non-Manhattan wire or polygon may be shifted a fraction of a grid unit to force them to fit into the split corner-stitched tile representation.

Remember that non-Manhattan geometry is more of a visual aid to the designer than a reality. The generation of an actual fabrication process mask involves pixelating the input to the smallest dimension handled by the mask generation optics. While the mask turns non-Manhattan features into a stair-step approximation, the limitation of optical resolution rounds off corners of the final fabricated layers, making them end up somewhere between the Manhattan pixels of the mask and the idealized non-Manhattan layout envisioned by the designer. The bottom line is that one should not get too worked up over the fidelity of non-Manhattan features (or lack thereof) in a layout.

Other Problems with Reading and Writing CIF

You may have noticed that when you wrote out CIF for tut9a and read it back in again, you didn't get back quite what you started with. Although the differences shouldn't cause any serious problems, this section describes what they are so you'll know what to expect. Discrepancies will occur whenever the operations of a cifinput section in a technology file do not precisely invert the operations in the cifoutput section. Because it is generally assumed that layout in Magic will remain in Magic's database format until tape-out, often little attention is paid to whether or not the input and output operations are properly structured so as to be invertible.

There are three areas where discrepancies most often occur: labels, arrays, and contacts. These are illustrated in tut9b. Load this cell, then generate CIF, then read the CIF back in again. When the CIF is read in, you'll get a couple of warning messages because Magic won't allow the CIF to overwrite existing cells: it uses new numbered cells instead (this is why you should normally read CIF with a "clean slate"; in this case it's convenient to have both the original and reconstructed infromation present at the same time; just ignore the warnings). The information from the CIF cell appears as a subcell named 1 right on top of the old contents of tut9b; select 1, move it below tut9b, and expand it so you can compare its contents to tut9b.

The first problem area is that CIF normally allows only point labels. By default, where you have line or box labels in Magic, CIF labels are generated at the center of the Magic labels. The label in in tut9y is an example of a line label that gets smashed in the CIF processing. The command

cif arealabels yes

sets a switch telling Magic to use an extension to cif to output area-labels. This is not the default since many programs that take CIF as input do not understand this extension.

If you are reading a CIF file created by a tool other than Magic, there is an additional problems with labels. The CIF label construct ("94 label x y layer") has an optional layer field that indicates the layer to which a label is attached. If reading a CIF file generated by Magic, this field is always present and so a label's layer is unambiguous. However, if the field is absent, Magic must decide which layer to use. It does this by looking to see what Magic layers lie beneath the label after the CIF has been read in. When there are several layers, it chooses the one appearing LATEST in the types section of the technology file. Usually, it's possible to ensure that the right layer is used by placing signal layers (such as metal, diffusion, and poly) later in the types section than layers such as pwell or nplus. However, sometimes Magic will still pick the wrong layer, and it will be up to you to move the label to the right layer yourself.

The second problem is with arrays. CIF has no standard array construct, so when Magic outputs arrays it does it as a collection of cell instances. When the CIF file is read back in, each array element comes back as a separate subcell. The array of tut9y cells is an example of this. Most designs only have a few arrays that are large enough to matter; where this is the case, you should go back after reading the CIF and replace the multiple instances with a single array. GDS format does have an array construct, so it doesn't have this problem.

The third discrepancy is that where there are large contact areas, when CIF is read and written the area of the contact may be reduced slightly. This happened to the large poly contact in tut9b. The shrink doesn't reduce the effective area of the contact; it just reduces the area drawn in Magic. To see what's happening here, place the box around tut9b and 1, expand everything, then type

cif see CCP

This causes feedback to be displayed showing CIF layer "CCP" (contact cut to poly). You may have to zoom in a bit to distinguish the individual via holes. Magic generates lots of small contact vias over the area of the contact, and if contacts aren't exact multiples of the hole size and spacing then extra space is left around the edges. When the CIF is read back in, this extra space isn't turned back into contact. The circuit that is read in is functionally identical to the original circuit, even though the Magic contact appears slightly smaller.

There is an additional problem with generating CIF having to do with the cell hierarchy. When Magic generates CIF, it performs geometric operations such as "grow" and "shrink" on the mask layers. Some of these operations are not guaranteed to work perfectly on hierarchical designs. Magic detects when there are problems and creates feedback areas to mark the trouble spots. When you write CIF, Magic will warn you that there were troubles. These should almost never happen if you generate CIF from designs that don't have any design-rule errors. If they do occur, you can get around them by writing cif with the following command

cif flat fileName

This command creates an internal version of the design with hierarchy removed, before outputing CIF as in cif write. An alternative approach that does not require flattening is to modify the technology file in use. Read "Magic Maintainers Manual #2: The Technology File", if you want to try this approach.

Viewing Unknown GDS or CIF Files

Magic version 7.4 provides a way to quickly view any arbitrary GDS or CIF file without prior knowledge of the layer types. Of course, without knowledge of the layer types, one cannot properly define how layers interact, or what the design rules are, extract a circuit, and so forth. But it is not possible to define those things without first seeing a layout and determining how the layers are used. For this purpose, magic defines two shell scripts to be run from the UNIX command line (these are not Magic commands). They run Magic as a batch process, reading the file and collecting information from error messages about what layers were encountered in the input.
gdsquery gds_fileName [view]
cifquery cif_fileName [view]
Each tool produces a technology file that defines a mapping between layers found in the input file and Magic. gdsquery produces a technology file called "", and cifquery produces a technology file called "". If the option "view" is specified, then after generating the technology file, the script will launch Magic with the newly defined technology, re-read the input file, and display it. Otherwise, the script exits after creating the technology file. The primary drawback of these scripts is that, to prevent layers from interacting in unintended ways when read into Magic, Magic must define each layer in the file on its own plane. Magic has a limited number of planes it can handle, and this limits the total number of input CIF/GDS layers that Magic can map.

Reading Vendor GDS Cells and Libraries

Often a process has cells or libraries that are provided by the foundry, and not generated by Magic. It can be assumed that because these cells and libraries came from the vendor, they are design-rule correct, and the layers should not be altered in any way. Reading such a file into magic using the technology file's input style can only cause trouble: Layers may not be recognized, or other layers may be transformed into something unexpected. Writing the same layout with the technology file's output style can further damage the original layout. To cope with these problems, Magic has a way to mark a GDS file being read as containing "vendor cells". With each cell read, the filename of the GDS file will be saved, along with the startpoint and endpoint in the GDS stream where the cell is defined. When Magic is writing its own GDS output, and encounters that cell, instead of writing what's in its own database, Magic will instead read the original cell definition from the original GDS file, and copy it byte-for-byte to the output. The cell is then defined exactly as it was originally, without any changes. This feature allows Magic to be used to assemble chips from GDS files written by other programs. In particular, it allows Magic to make use of "P-cells" from the Cadence Design Kit for a process. Often processes make use of many different layers just to define a single device (such as a SiGe bipolar transistor). By using the vendor data for such a cell, Magic does not need to define those layers itself, which simplifies Magic's technology files.

To read a vendor's GDS file, first execute the command:

gds readonly true

The readonly option, as the name suggests, marks the cell as being "read only"; that is, Magic cannot alter the cell's layout, and cannot re-write the GDS file from which it came. Nevertheless, is is possible to alter Magic's internal representation of the cell. When the "readonly true" option is set, and is followed by a "gds read" command, Magic will still attempt to read the input to the best of its ability, given the current input style. The user may wish to "clean up" the result if layers have been mis-represented in the input process. However, be warned that the picture Magic presents of each vendor cell is a "dummy" representation. Any changes to cell boundaries can cause DRC errors between Magic's real layout and the vendor cell to be missed.

Note that for each vendor cell Magic reads, the cell retains the position in the GDS stream file of that cell only. When Magic writes the cell to the output, it then searches its own representation of the vendor cells for any subcells belonging to the vendor cell, and writes those, too. Therefore it is crucially important never to delete any subcells from Magic's representation of a vendor cell, or the resulting output may make a call to a subcell that is not defined, a fatal error!

A final caution about using vendor cells is that while Magic makes sure that every subcell definition in its hierarchy has a unique name, it cannot guarantee that every subcell definition in vendor GDS files has a unique name. Be careful when using multiple vendor GDS files that there are no overlapping cell names. When possible, combine vendor cells into a single GDS file before importing it into Magic. All tools ensure a unique namespace within a single output GDS file, but many do not ensure a unique namespace among different output files.

R. Timothy Edwards 2006-02-17

Last updated: March 7, 2020 at 12:48pm