GEMINI(1.VLSI) VLSI Design Tools Manual GEMINI(1.VLSI)
NAME
gemini - compare two circuit netlists
SYNOPSIS
gemini [_o_p_t_i_o_n_s] _c_i_r_c_u_i_t_1 _c_i_r_c_u_i_t_2
DESCRIPTION
_G_e_m_i_n_i compares the two circuits contained in the files cir-
cuit1 and circuit2 and determines whether they are
equivalent. If the circuits are different, Gemini reports a
set of nets and devices that it thinks are the source of the
difference. If the circuits are too different, then this
set may be too large to be helpful. In this case, the user
may _b_i_n_d corresponding nodes in the two circuits to help
Gemini find the source of error.
The circuit file format is the MIT/Berkeley SIM format,
widely used for CMOS and NMOS circuits. The algorithm used
by Gemini is based on general graph isomorphism and thus is
technology independent. For a description of this format,
refer to the Gemini User's Guide.
Gemini first reads the two circuit graphs and prints a sum-
mary containing the number of devices and nets in each.
Devices are either single transistors or chains of source-
drain connected transistors of the same type. Gemini then
executes a graph isomorphism algorithm that matches nodes
between the two circuits in a series of passes. Gemini
prints a series of digits indicating in thousands the number
of nodes that have been matched.
Many programs that produce SIM format produce accompanying
.al (alias) files containing `=' lines indicating node names
that are equivalent. Gemini automatically looks for .al
files corresponding to the circuit files specified in the
command line. The .al file is ignored if not present.
Part of the information produced by Gemini is the number of
matches that were deduced. This indicates how successful
the local matching algorithm was in matching nodes. If this
number is small with respect to the total number of nodes in
the circuits, it indicates that the circuits are very sym-
metrical.
OPTIONS
The option flags may be specified anywhere in the command
line and there need not be a space between the flag and its
argument.
Northwest LIS Release 3.L2ast change: 4/23/93 1
GEMINI(1.VLSI) VLSI Design Tools Manual GEMINI(1.VLSI)
-h Print a short description of Gemini's command line
options.
-m Do not deduce matches using the local matching algo-
rithm; rely solely on the global partitioning algo-
rithm. The default is to use both.
-f Case-fold names when reading in the two circuit
graphs. The default is not to case-fold names. How-
ever, case sensitive node names are NOT recommended.
Note: Vdd and GND are special; case is always ignored
for these two signal names.
-w_t_o_l_e_r_a_n_c_e
Compare transistor size (length and width) for each
matched pair of devices and print a warning if the
difference is greater than the tolerance. _T_o_l_e_r_a_n_c_e
sets the tolerance as a percentage. If this argument
is omitted, the default tolerance is ten (e.g. +/-
10%). The default is to ignore transistor size match-
ing. Note that devices in the circuit files must
include size information, otherwise a run-time abort
may result.
-y_t_o_l_e_r_a_n_c_e
Compare the capacitance for each matched pair of nets
and print a warning if the difference is greater than
the tolerance. _T_o_l_e_r_a_n_c_e sets the tolerance as a per-
centage. If this argument is omitted, the default
tolerance is ten (e.g. +/- 10%). The default is to
ignore capacitor size matching. All capacitances are
with respect to ground.
-z Print all nets with zero connections. These are often
extraneous items like a logo but may in fact be some-
thing more serious like an input pad that has not been
connected. The default is to not print these nets.
-c Disable the preprocessing step that Gemini uses to
collapse series transistor chains before applying the
isomorphism algorithm. The default is to collapse
chains. The cost of this step varies. Typically 0-20%
of the execution time is spent collapsing chains, but
in some cases it may be 50%.
Northwest LIS Release 3.L2ast change: 4/23/93 2
GEMINI(1.VLSI) VLSI Design Tools Manual GEMINI(1.VLSI)
-C Restrict the chain collapsing algorithm to collapse
chains only if the candidate transistors have the same
size (length and width). The default is to collapse
chains without regard to size.
-cw Enable warnings for those series transistors whose
order does not correspond in the two circuits. (Note
that -c and -cw are exclusive.) The default is no
warning other than a count of the number of series con-
nected transistors out of order.
-F Disable the preprocessing step that Gemini uses to
collapse fingered (parallel) transistors before apply-
ing the isomorphism algorithm. The default is to col-
lapse fingers.
-n_n_u_m_b_e_r
Set the threshold for inhibiting net information on
mismatched nets. If the net has fewer than _n_u_m_b_e_r con-
nections, then information is printed out for each con-
nection. Otherwise, only the net name is printed. The
default value is 10.
-v Turn on Verbose mode. This may cause more detailed
information to be printed for nets and devices.
Default mode is off.
-E _f_i_l_e_n_a_m_e
Read an equivalence file that binds corresponding nodes
in the two circuits. Each line in the file begins with
an equals sign (`=') followed by two names, the first
from the first circuit and followed a name from the
second; space or tab separate arguments. These two
nodes are bound together before the circuit graphs are
matched. Lines that begin with a semicolon (`;') are
ignored.
-D _f_i_l_e_n_a_m_e
Create a dictionary file that indicates the matching
nodes in the two circuits. The file format is the same
as the equivalence file format. Only nodes with real
names (not *) are printed in this file.
-M _s_y_m_b_o_l[:_n_u_m_b_e_r]
Create an error file in _M_a_g_i_c format, highlighting the
Northwest LIS Release 3.L2ast change: 4/23/93 3
GEMINI(1.VLSI) VLSI Design Tools Manual GEMINI(1.VLSI)
devices that appear in the error report. The SIM file
extracted from Magic must be the first circuit speci-
fied on the command line. _S_y_m_b_o_l is the name of the
root symbol of the Magic layout. The Magic output file
is produced with the name "_s_y_m_b_o_l.err.mag" and contains
both labels and rectangles on the error layer for each
device that appears in the device error list or as a
connection in the net error list. The devices from the
two lists are distinguished by the label used. A "D"
label indicates a non-matching device. An "N" label
indicates the device is connected to a non-matching net
whose name is also given. (Of course a device may have
both a D and N label.) (The -n option can be used to
control the devices listed in the net error list.) An
optional number after a colon gives the value of lambda
in CIF units. The default value is 100 (corresponding
to a 2 micron process).
If the -cw option is used, transistor chains appearing
out of order are marked. The error label given is
"SIZE". If the -w option is used, transistors with
sizes outside the tolerance are marked. The error
label indicates the size of the matching transistor in
the other circuit.
-G Use the Gemini input format instead of the default SIM
format. Note: this feature is not actively supported;
caveat emptor.
-I Run Gemini interactively. This allows the user to
give Gemini some help when it comes to matching ambigu-
ous nodes. An exclamation point (`!') as a user's
response tells Gemini to continue without asking any
more questions.
The following flags change the parameters used by the graph
isomorphism algorithm of Gemini. Users are advised to leave
these alone unless they understand what the algorithm is
doing.
-t Trace the progress of the labeling procedure. This
shows how much trouble Gemini is having with the cir-
cuit.
Northwest LIS Release 3.L2ast change: 4/23/93 4
GEMINI(1.VLSI) VLSI Design Tools Manual GEMINI(1.VLSI)
-p_n_u_m_b_e_r
Specify the number of labeling passes where no progress
is detected before trying something drastic. The
default value is 2.
-s_n_u_m_b_e_r
Specify the number of times suspect nodes are
relabeled where no progress is detected before trying
something even more drastic. The default value is 1.
-e_n_u_m_b_e_r
Gemini is allowed to stop when there are less than this
many unresolved nodes left in the two circuits. The
default value is 0. Changing this value is not recom-
mended.
ERROR REPORT
Gemini produces error reports as listings of nets and dev-
ices it thinks are at fault. The key idea is that the cir-
cuits are identical _i_f _t_h_e _g_i_v_e_n _n_e_t_s _a_n_d _d_e_v_i_c_e_s _a_r_e
_d_e_l_e_t_e_d from the circuits. Gemini has 2 different classes
of error nodes: those that it thinks are definitely in error
and those that may be OK if the nodes in the first class are
fixed. In general, it is best to examine all nodes in the
error report.
Devices and nets are printed in varying detail. Nets are
identified by name and the devices to which they are con-
nected. The -n option allows more or less detail to be
shown for nets. Devices are identified by name (if any) and
the nets to which they are connected. These connections are
listed in the same order as given in the device definitions.
For SIM file transistors, the connections are listed in the
same order as in the SIM file -- gate followed by source and
drain. For devices representing series connected transis-
tors, the gates are listed first, in the order in which they
appear between the collective source and drain.
SERIES CONNECTED TRANSISTORS
Unless the -c flag is used, series connected transistors are
merged into single devices. Gemini checks as these devices
are matched to make sure the transistors are in the same
order in both circuits and prints a warning (if -cw is used)
if they are not. In symmetrical circuits where are there
are chains with the same gate sequence, but with a different
order, Gemini may arbitrarily match the wrong chains and
print a warning. (This will be fixed in a later version of
Gemini.)
Northwest LIS Release 3.L2ast change: 4/23/93 5
GEMINI(1.VLSI) VLSI Design Tools Manual GEMINI(1.VLSI)
FINGERED (PARALLEL) TRANSISTORS
Fingered or parallel transistors share the same gate, source
and drain connections. They are equivalent to wide single
transistors. They are often used for high current struc-
tures such as clock drivers and output pads. Two transis-
tors are candidates for combining if they are primitive
types (n or p), share the same primitive type, share the
same gate, source and drain, and have the same channel
length. Unless the -F flag is used, candidate transistors
are merged into a single transistor whose width is the sum
of the widths of the uncombined transistors.
USER-DEFINED DEVICES
Starting with release 2.5, Gemini allows an extension of the
UCB/MIT SIM format for user-defined devices (see sim(5)).
User-defined devices have two parts: the type definition and
the instance declaration. The type definition has the form
DEFINE mydevice a a b c
and the instance has the form
mydevice in2 in3 out5 out7 ; XYZ
XYZ is an optional attribute list. The current version of
Gemini ignores the attribute list in user-defined devices,
but it may be considered by the matching algorithm in a
future version. The formal parameters in the type defini-
tion denote terminal classes. Repeated parameter names in
the type definition denote symmetry, i.e. class equivalence.
Many functions allow the inputs to appear in any order (e.g.
parity checking), and the matching algorithm considers all
symmetric permutations to be potential matches. User-
defined type usages that are not well-formed cause Gemini to
terminate abnormally. The line number and name of the input
file are indicated in case of error to help the user isolate
the problem.
Here are the restrictions on user-defined types. The name
of a user-defined type must contain two or more alphanumeric
characters. Type definitions must precede instance declara-
tions in the input file. Multiple definitions may appear
for the same type but they must be consistent. The number
of arguments in the instance declaration must be the same as
the number of formal parameters in the type definition.
User-defined devices are neither combined into chains nor
folded. If an attribute list is present in an instance
declaration, then whitespace is required between the last
argument and the semicolon.
Northwest LIS Release 3.L2ast change: 4/23/93 6
GEMINI(1.VLSI) VLSI Design Tools Manual GEMINI(1.VLSI)
SYMMETRIC CIRCUITS
When there is symmetry in the circuits being compared, there
are many different ways that some nodes can be matched
between the two circuits. For example, in a memory array,
the word lines and bit lines can be permuted giving an
exponential number of different ways to match the nodes in
the two circuits. When Gemini detects that its algorithm is
making no progress, it assumes that the problem is one of
symmetry. It also assumes that the partitions that it has
at that point are _a_u_t_o_m_o_r_p_h_i_s_m partitions so that _a_n_y match
between nodes in matching partitions is valid. If this
assumption is invalid, then Gemini may, in its arbitrary
choice of two nodes, pick nodes that do not match and then
erroneously conclude that the circuits are different. If
this happens, Gemini throws up its hands and refuses to con-
clude anything about the circuits. The user must then use
the equivalence file to remove the symmetry causing the
problem. In the memory example, this can be done by binding
the address inputs and the data outputs. Although removing
symmetry is not often required, it can speed up the execu-
tion time.
FINDING DIFFERENCES
When two circuits are different, Gemini attempts to pinpoint
the source of the difference. This is a very hard problem
in general, and sometimes Gemini does not give very accurate
feedback, especially if there are many differences or if
there is a lot of symmetry. Here are some hints on how to
proceed in this situation.
Northwest LIS Release 3.L2ast change: 4/23/93 7
GEMINI(1.VLSI) VLSI Design Tools Manual GEMINI(1.VLSI)
DOUBLECHECKING GEMINI
Old versions of Gemini have been known to report differing
circuits as being the same. The way to ensure that this is
not the case is to create a dictionary file using the -D
option and then rerun Gemini using the -E option with this
file. There have been no reported instances of this type of
error with this version of Gemini. PLEASE send a bug report
if you suspect that this has happened to you.
RUN-TIME ERRORS
Gemini checks the internal consistency of its algorithm as
it executes, using run-time assertions. If an assertion
fails, the program is unable to continue and it aborts. If
the -D option is used, Gemini writes out all the equivalence
information it had deduced before the error was encountered.
This allows the user to iterate the process; using the
equivalence information will avoid the consistency error on
subsequent passes. Failed assertions under previous ver-
sions of Gemini sometimes caused a core-dump or an infinite
loop, and no dictionary file was produced.
Run-time failures should be rare. Send a bug report for any
input set that causes a run-time abort, especially those
that fail without printing the message "Assertion failed."
SEE ALSO
sim(5)
The Gemini User's Manual
AUTHOR
Carl Ebeling, University of Washington
ebeling@cs.washington.edu
MAINTAINERS
Neil McKenzie, University of Washington
mckenzie@cs.washington.edu
Larry McMurchie, University of Washington
larry@cs.washington.edu
BUGS
The Gemini file format is not actively supported.
Gemini sometimes thinks that isomorphic circuits are dif-
ferent because it does not backtrack on the guess it makes.
Northwest LIS Release 3.L2ast change: 4/23/93 8
GEMINI(1.VLSI) VLSI Design Tools Manual GEMINI(1.VLSI)
Old versions of Gemini have been known to think that dif-
ferent circuits were isomorphic. The -E/-D checking method
described above can be used to doublecheck.
Discrepancies between circuits are sometimes not pinpointed
well enough.
In rare cases, run-time errors may occur if the circuits are
different.
Northwest LIS Release 3.L2ast change: 4/23/93 9