Layout Verification Using MASKAP

What is MASKAP?

MASKAP is a software package residing on the VAX and VAXStations on the CIE 6th floor. To run the package on the VAX, you want to telnet . You can either do this using your "darpa" account, provided by Dave King, or using the group account (for more information on the group account, contact the keeper of the keys, currently Cliff Maier).

MASKAP is a product dating back to 1982 from Phoenix Data Systems, which was, at the time, on Wolf Rd. MASKAP itself consists of several programs, each of which is designed to help you verify your layout. The package as a whole is designed to check to make sure that the layout for a circuit identically matches its schematics. The design verification process follows:

  1. Generate schematics, using SPICE, ORCad, Workview / Powerview, Compass, or some combination of the above
  2. Simulate these schematics, using PSPICE, HSPICE, or a digital simulator to ensure that your schematics are functionally correct
  3. Generate layout to match the schematics, either manually, using the Compass Layout Editor or the Compass Composition Editor, or "automatically," using the Compass Chip Compiler
  4. Run a DESIGN RULE CHECK ON THE LAYOUT!!!!!! Currently this is done using the Compass Terminal or Compass VLSIShell, but hopefully we will soon have Cadence Dracula on-line.
  5. Convert the netlists and layout to MASKAP format
  6. Generate a list of correspondance points which act as known starting points for MASKAP
  7. ftp the whole mess over to a VMS account
  8. Run MASKAP!
The important point to remember here as the whole purpose of this process is to make sure that your layout matches known good schematics. NEVER change schematics to match the layout, unless you are certain that there is actually a problem with the schematics. (Ask the keeper of the keys for MASKAP folklore involving someone who did just that...)

Where do schematics and layout come from?

Before explaining how to use MASKAP, it is important to explain where schematics and layout come from, how one is generated from the other, and how to convert back and forth from one file format to another. This is probably the biggest conceptual problem for people trying to learn to use MASKAP, probably because this task is usually assigned to people who haven't yet used the other CAD tools to design any circuits.


As a rule, our chips are built up of smaller subcircuits known as "cells." Cells come in a variety of flavors including standard cells, which are generally things such as logic gates and latches, and macro cells which are things such as I/O pad cells, RAM blocks, PLL's, VCO's, and special handcrafted circuits.

Whenever a new cell is created, it, too, must go through the MASKAP process. This makes MASKAPing finished chips much easier, as a single flawed cell may occur dozens of times in one chip.

The netlist for standard and macro cells is generally found in SPICE format. Hans Greub, Sam Steidl, Cliff Maier, Bob Philhower, and K.S. Nah have designed a variety of cells using tools such as ORCad and Workview. The cells are simulated in Spice, and this is the best format for transporting the netlists to other formats. In fact, it is fairly common to create a new cell from an old one by loading a netlist into a text editor and hand modifying it.

For information on the Spice netlist format, see the various manuals available in CII 6111. Spice netlists typically end in .CIR.

The layouts for cells are always created by hand, using the COMPASS Composition Editor. The native file format for the Composition Editor is .cp. This file format contains all of the geometric layout information, as well as logical connectivity information, and net name information. Important points:

  1. The net names as entered onto the layout frequently differ from the netnames in the schematics.
  2. There is a method of converting a .cp file to a netlist format. NEVER do this for MASKAP purposes. You are defeating the purpose if you do this, because the netlist you generate has not been simulated and shown to be correct. Even if you DO simulate it you will not be proving anything because the netlist you create may not accurately reflect the actual layout (we have found cases where this has happened.) The moral is: just because it can be done doesn't mean you should do it.


Chips are created using a variety of tools. The schematics for a chip will invariably originate from a variety of locations. Cells will probably come from Spice netlists, and there will typically be several layers of digital hierarchy which are created in the COMPASS Logic Assistant. The MAIN file format used by the Logic Assistant is the .la file format. Aside from connectivity information, this file format contains information about how the symbols appear visually on the screen. An alternative file format is the .nls file format which can be created from the .la file using various COMPASS tools. .la files are invariably hierarchical. When creating a .nls file you may choose to flatten it, or leave it as a hierarchical tree of file formats. When you are MASKAPing a cell, this is not an issue, since you will have only one level of hierarchy, anyway... (sort of).

The schematics you send to Maskap must flatten down to the device level. Since the Logic Assistant knows nothing about devices (the lowest level it knows about are current switch device pairs), at some point the hierarchical netlist must call a cell which originated from SPICE or some transistor aware source. (Perhaps even hand generated).

On the VMS system, there are many standard cell netlist already converted to MASKAP format and stored in the DARPA.MASKAP.DEVICES and DARPA.MASKAP.SUBCELLS subdirectories on the CIEVMS_USR2 disk partition. These cells have already been MASKAPed, and you shouldn't have to worry about them unless you modify them.

If you create your own cells, once they are verified their netlists should be placed in these directories as appropriate.

The layout for a chip is, with the notable exception of the Deskew chiplet and the High Speed VCO chiplet, accomplished using the COMPASS Chip Compiler, with additional hand modifications in the Composition Editor, vi, various scripts, and lots of luck.

The file format used by the Chip Compiler is the .cc format. It is not human readable. It contains interconnect information, geometry information, net names, routing guidance, seed placement info, and all sorts of other junk. From this format we can generate .cp's.

File Format Conversion

In order to run MASKAP on a design you generally have to provide three files:

MASKAP will, starting at the starting points you provide, analyze the geometry you provide to determine whether it matches the netlist you provide. Once again, this is only useful if the schematics are known to be correct , which is generally only accomplishable through simulation. The file format for physical geometry which MASKAP uses is the Graphical INput file .gin. This is simply a .CIF file with carriage returns at the end of each statement. The following procedures are used to generated .gin files from various file formats:

.cc From within the Chip Compiler, make a set of .cp files. First, select SETUP and set "convert standard cell area type" to ".cp" Then, simply select MISC and "Convert!" This will generate several .cp files, with names like chip_f.cp, chip_sc1_f.cp, and chip_toppads_f.cp. You use these files in CUTTER which converts from fat to thin layouts. (A lesson for another day.) In the end you will have a .cp file. From there...
.cp From within the Composition Editor select MISC and then MAKECIF. Now, you just have to convert to a .gin file...
.ly From within the Layout Editor, select MISC and then MAKECIF. Now you just have to convert to a .gin file...
.cif Unfortunately, COMPASS generates a giant, run-on CIF file with no carriage returns. Bob Philhower wrote a script to fix this, though.

Simply type the following from any of the Sun workstations:

fixcif < file.cif > file.gin

The .gin file should be ftp'd over to VMS and placed into the directory from which you intend to run maskap. One thing to note: avoid naming things with names longer than 8 characters or containing unusual characters. This makes VMS unhappy.

Your next step is to create a netlist. This is a little more complicated, and requires a little discussion.

MASKAP uses several netlist formats, including .USL, .SSL, .SDL, and .NET. The most important of these to you are .USL's and .SDL's. The .NET format is NEARLY identical to the .USL format, and is always used for the top level of the netlist.

A .net file can call many .usl, .sdl, and .ssl files hierarchically. There is a limit to the number of levels of hierarchy which MASKAP can handle before overrunning its stack, but most designs will not come close to reaching this number.

.usl and .ssl files can call other .usl files and .sdl files. .sdl files generally are flat. Gate level circuits are usually stored as .sdl's, while higher level circuits (anything composed of cells) are stored as .usl files.

When you are MASKAPing a cell you need to make a .net file and use that for your netlist. Once that is complete, you can convert it to a .usl or a .sdl as appropriate. You should then place the subcell netlist in the darpa.maskap.devices subdirectory if it is a .sdl .ssl, or the darpa.maskap.subcells subdirectory if it is a .usl. Since there is no difference between a .usl and a .ssl, if a .ssl exists in the devices library and a .usl exists in the subcells library, MASKAP will use the .ssl. BEWARE!

When running MASKAP, you will eventually become intimately familiar with the .sdl and .usl file formats. (sadly). An example .net file fragment follows:

; WARNING: circuit name translation from BS_CONTROL to BSCONTR  
LST:  TEST1-0 TEST1-1 TEST3-0 TEST3-1  
LST2: TEST21-0 TEST21-1 TEST23-0 TEST23-1  

TEST: TEST1-0 TEST1-1 K115 K114  

The $NETWORK line identifies this circuit as TESTBSC.NET. The $POWER and $GROUND lines list a bunch of global signals (not just the actual power (vdd) and ground (vss) lines.

There are three subcell calls. The first one is to a cell called LST which is to a cell of type LS13H, a high-powered level 1 to level 3 voltage shifting buffer. The second call is to another LS13H named LST2. The third call is to a cell named TEST which is a cell of type CKR1H, a high powered level 1 clock receiver I/O pad.

The SUBU on the line that identifies the CKRIH call indicates that this is a call to a .usl or .ssl file. The fact that the LS13H call does not contain a "subu" means that it is a call to a .SDL.

Remember: The .usl, .net, and .ssl file formats are essentially identical, and are handled identically by MASKAP. The distinction between the files has to do with systems where the designer would ordinarily not have access to the cell library.

Here's the ckr1h.ssl file (NOTE: We could just as easily have named the file ckr1h.usl and stored it in the SUBCELLS directory. Our convention is to place universally useful cells in the DEVICES library, though.)

;   NAME  :  ckr1h
;   SOURCE:  Spice from WorkView
;   METHOD:  Automatic Conversion
;   DATE  :  Mon Aug  9 09:40:10 EDT 1993
;   Node name key:
Q1 : O0 PAD1 N7
Q2 : O1 PAD0 N7
RL1 : VDD O0
RL2 : VDD O1
RS1 : N7 VSS

Note that instead of a "NETWORK" line, we have a SUBD line. Both .usl and .ssl files used the SUBD rather than NETWORK. Only .net files have the NETWORK line. To convert from a .usl to a .net, it is necessary only to change this one line.

Note the $INPUT and $OUTPUT lines. These lines list all of the external connections of the cell. By convention, these connectors are always listed on the OUTPUT line. Yes, even if they are inputs. In this example we have four connectors which correspond to two differential pairs: O[1:0] and PAD[1:0]. Note that the call to CKR1H contains four parameters as well. If not, we'd have a problem! The net named TEST1[1:0] in the top level netlist is wired to the O[1:0] connectors of the clock receiver named TEST. The PAD connectors of the pad are wired to top level nets which are not named. (MASKAP arbitrarily names them Kxxx.)

Note that the CKR1H .ssl file makes several calls to .sdl files. (specifically, some diodes, transistors, and resistors.)

The following is the ls13h.sdl file

;    SOURCE : [nls]ls13h
;    METHOD : Automatic Conversion from [nls] to .SDL
;    DATE   : Thu Jun 17 10:38:23 EDT 1993
;      A1[1]       : A1-1
;      A1[0]       : A1-0
;      Z3[1]       : Z3-1
;      Z3[0]       : Z3-0
$DEVICE ls13h
$OUTPUT A1-0 A1-1 Z3-0 Z3-1
;                     model: vee1  instance: U8 --> U8
HBTNPN U8D  K16  K16  U8N 
;                     model: EMFOMO(emfoh3)  instance: U6 --> U6
HBTNPN U6T3 U6N0 U6N0 Z3-0 
HBTNPN U6T4 U6N1 U6N1 Z3-1 
;                     model: DCSWMO(dcswh1)  instance: U7 --> U7
HBTNPN U7L A1-1 K18 K16 
HBTNPN U7R A1-0 K17 K16 

Converting Netlists

Key points to remember:

.la If this is a subcell containing no hierarchy, from the COMPASS Logic Assistant select MISC and MAKE NLS. If this is a chip or a complicated circuit that contains hierarchy, select MISC and MAKE NLTREE. If you make a tree, you will find your directory full of .nls files. IGNORE the .nls files for standard and macro cells. These .nls files are useless because the netlists are incorrect - the system uses them only for digital simulation purposes.
To make a .sdl: From SunOS: nls2sdl CELL.nls
To make a .usl: From SunOs: nls2usl CELL.nls

To make a .net file, simply make a .usl and rename it, and change the SUBD to NETWORK. To make a .ssl file, simply make a .usl file and rename it. If you are MASKAPing a subcell, make the .usl or .ssl or .sdl file, and then use a .net file which contains a call to that .sdl, .usl, or .ssl file. Then run MASKAP using the .net. The nls2usl and nls2sdl scripts will automatically generate this .net file.

You may have to type start_server before these scripts will work: the scripts will inform you if this is the case.

Once you have created the tree of netlists, ftp it all over to the VMS directory from where you intend to run MASKAP.

Correspondance Points

The final step is to give MASKAP a list of starting points. The idea is to look at the layout and find points which you know the name of in the netlist. You then create a file which contains the geometric location of the point, the metal layer on which it occurs, and the net name of that point.

Some important points:

If you are running MASKAP on a subcell, you may automatically generate a correspondance point file. Type maker8 CELL.cp. This script will generate a file called CELL.r8 which you can manually add to if needed. ftp this over to VMS.

Running MASKAP

MASKAP actually consists of several separate software tools. Each tool is run independantly, in sequence. Each tool requires a "run control file" (RCF) to direct it. In the old days you'd have to generate these by hand - now you have some help.

In your VMS account you should have three files: CELL.R8, CELL.GIN, and CELL.NET, plus, optionally, some .USL's, .SSL's, and .SDL's. You now have to make RCF files for each tool you plan to use.

From VMS, at the $ prompt, type MAKERCF. A typical session is show below:

MASKAP Run Control File Creator
(various junk)
Chip name: CELL                            (Enter your chip or cell name)
CIF structure name (CELL): ENTER           (Leave the default) 
LOGCAP network name (CELL): ENTER
Should CONTIN print...: YES or NO          (It's entirely up to you)
CONTIN Run Control File Generated
LOGICV Run Control File Generated
EPARM Run Control File Generated
ECHECK Run Control File Generated
Do you already have a CPOINT .R8 file? YES (Assuming you used maker8)

You should now have .R1, .R2, .R11, .R12 files. The next step is to run the various MASKAP programs:

contin This program analyzes the .gin file and produces a database in a MASKAP internal format. It is necessary to run contin before any other MASKAP program, and any time you change the .gin file. This program will take many hours on a full chip.
cpoint This program analyzes the .r8 corresponance file and checks to be sure that all of the points you specified actually point to the appropriate metal layer, that you haven't given a single node more than one name, and that you haven't given two nodes the same name. This program is particularly useful for detecting accidental shorts between nodes. This program must be run before logicv, but after contin, and any time you change the .gin or .r8 file.
logicv This program performs the actual comparison between the netlist and the geometry. HINT:When MASKAPing an entire chip, first run MASKAP with a fake, small, .gin file and .r8 file. This will enable you to syntactically check the netlist hierarchy very quickly. This program will run very quickly on a full chip if there are netlist errors, or the netlist perfectly matches the layout. Otherwise, it can take many hours.


These two programs are used to check resistor values. After running contin on a .gin file, run eparm and echeck to produce a list of resistors in the layout.
prntplot This program is used to produce graphical output from MASKAP. This can be very useful...


You will always want to run CONTIN first. In order to do this, from the VMS prompt, type MASKAP. A typical session follows.

MASKAP V204P4 1-NOVEMBER-1985....
Chip name: chip
Job name: chip_1
Enter program number....: 1
Run File Suffix, if any: ENTER
Are you starting from scratch: Y
Process name: ENTER
Syntax check only: ENTER
Run to completion: Y
Submit job to batch: see below
What queue? see below
Job chip_1 started

You may either submit the job to batch (in which case you should use LOW_BATCH) or create an executable. To run the executable, type @chip_1. In either case, CONTIN will be run. Two important files (among others) will be created: chip_1.msg and chip_1.rpt.

These files should be checked for errors.

"Unconnected polygons" can usually be ignored if the quantity of them corresponds to the number of pads on a chip, or connectors on a cell. "Device termination" or other errors are cause for concern, and are usually self-explanatory. Coordinates will be given for each error - use the ZOOM COORDINATES feature of the Composition Editor to check them out.


Once you are down to only "unconnected polygons" in CONTIN, run CPOINT. The process is the same as for CONTIN, but the program number is 8. If you change the .r8 file at any time, you must re-run MASKAP. You will want to use chip_8 as a job name. Once again, check the chip_8.rpt and chip_8.msg files for errors. The errors are always very self-explanatory (giving two names to a node, naming empty space, etc.)


After CPOINT runs successfully, run LOGICV. You run it similarly to the other two programs, except the program number is 2. Check the cell_2.rpt file, and hope that you see:


You likely won't. There is extensive documentation in the MASKAP manuals (very good documentation) on the LOGICV reports. Here are some hints, though.

At the top of the .rpt file you may see something called a BOOLEAN CONNECTIVITY DISCREPANCY REPORT. MASKAP will essentially tell you when it expects to see a certain number of connection to a node in the netlist, and doesn't see that number in the layout. This is frequently very helpful in determining miswired devices.

Next you will be given a DEVICE VERIFICATION REPORT which is sort of a scoreboard through which you can track your progress. For each type of device (transistor, diode, and resistor) you will be told how many are in the layout, how many MASKAP thinks it has correctly identified, how many it may have identified but isn't quite sure of (more correspondance points might help!) and how many it hasn't got a clue about.

Next you may see a LOGICV DEVICE MATCH REPORT which may tell you specific devices that it believes it has identified correctly but which have one or more incorrect connections. The coordinates of these devices are provided, so you may wish to check in the Composition Editor to determine if MASKAP has properly guessed what they are. If not, try adding correspondance points. If MASKAP marks devices in this report with a + sign, they are more likely to be correctly identified. An * indicates that MASKAP is only guessing, and requires more correspondance.

If you want to put a correspondance point on a node within a subcell, it will have a name with .'s in the netlist. For example, topcell.subcell.node

In order to handle this, make up a name, like topsubnode (the name is arbitrary), and use that. Then, at the bottom of your .r8 file, add the following lines:

topsubnode topcell.subcell.node
(any additional translations)


If you wish MASKAP to show you where it believes a certain node or device to be, or where all of the unsolved for nodes are, or anything else graphically, you need to use PRINT/PLOT (Maskap program 9.) You need to make your own .r9 file manually. The .r9 file should look like:



This command plots all the completely unidentified devices. You can change the 1 to a 2, 3, or 4 to see possibly matched, probably matched, and pretty definitely matched devices.


This command plots specific node numbers. If LOGICV tells you some node number is connected to something, and you want to see what that node number is, use this command. You must supply physical node numbers. There are three lines so that MASKAP plots the Metal1, Metal2, and Metal3 components of the net.

When you run MASKAP program 9, you will generate a .gou file. ftp it to UNIX (always ftp from UNIX) and rename it to the name of your chip and add a .err extension. Load the file into a text editor, goto the end, and, on the line before the "E" add a line C 1;

Now, you can load the file as a DRC error file into the Composition Editor!


Maskap programs 11 and 12, when run in sequence produce a list of resistor values in the cell. These programs must be run after CONTIN.


One of the features of the boundary scan scheme created by Bob Philhower and used in the instruction decoder, datapath, and cache controller is that the scan chain is in the pads. The actual connections between pads do not appear in the Logic Assistant schematics, because the pad ordering is not fixed until placement and routing, which occurs much later on. In order to simulate the boundary scan chain in COMPASS Sim, and in order to properly MASKAP, these connections must be properly reflected in the netlist.

Although they can be added by hand, there is an AWK script to automate the process. AFTER running nls2usl to create CHIP.USL, do the following:

scan_path_extract chip
scan2usl chip.usl

You should probably back up the .usl file first.

You may have to hand adjust the entries for pads such as SPIRT and SPORT and SPD.