Gemini

Gemini compares two netlists and reports whether they describe the same circuit. It is the engine behind Glade's LVS, and it can also be run on its own from the command line.

Gemini is based on the Gemini II graph-matching program by Carl Ebeling (University of Washington). It labels the devices and nets of both netlists, refining the labels iteratively until every device and net in one netlist is paired with one in the other, or until no further progress can be made. Net and device names are not needed to find a match, so a layout extracted with arbitrary net names can be compared with a schematic netlist. Where names are known to correspond, they can be given to Gemini as starting points.

Glade runs Gemini from Verify->LVS->Run, whose Gemini Options tab sets most of the options described below. This page covers the standalone program.

Input netlists

Gemini always compares exactly two files. Each file may be:

A flat SPICE/CDL netlist (the default format). MOS transistors (M), resistors (R), capacitors (C), inductors (L), diodes (D) and bipolar transistors (Q) are read, with their properties (W, L, R, C and so on) for property checking. .SCALE and .GLOBAL lines are honoured, and device dimensions may be given in mixed units.
A one-level hierarchical CDL netlist. If the file contains subcircuit instances (X lines), it is read as its top .subckt, and each instance becomes a black box device whose type is the instantiated cell. The top cell is the one named by -T, or otherwise the last .subckt that has X lines and is not itself instantiated. The bodies of the other subckts are not compared; their port lists give the pin names of the cells. A cell that is instantiated but not defined in the file has positional pins (1, 2, 3, ...). To compare down to the transistors instead, flatten the netlist first with cdlflatten.
A DEF file. A file whose name ends in .def (any case), or whose first keyword is VERSION, NAMESCASESENSITIVE, DIVIDERCHAR, BUSBITCHARS or DESIGN, is read as DEF. See Comparing DEF.
A gate-level Verilog netlist. A file whose name ends in .v, .vg, .gv, .vm, .sv, .vlg or .verilog (any case), or whose first word is module or a compiler directive such as `timescale, is read as structural Verilog. See Comparing Verilog.

The two files may be in different formats. Typical uses are layout-extracted CDL against schematic CDL (transistor level), and a placed and routed DEF against the hierarchical CDL or gate-level Verilog netlist of the design (cell level).

Comparing DEF

Gemini reads the connectivity of a DEF file, so a placed and routed block can be checked against its netlist with the standard cells treated as black boxes. Only the COMPONENTS, PINS, NETS and SPECIALNETS sections are used; geometry and routing are ignored, so no LEF is needed.

Cells. Each component becomes a black box device whose type is its master cell. A cell's pins are the pins connected to it in either netlist. When the other file is a hierarchical CDL netlist, the .subckt port list of the cell is used instead, so pins are matched by name. A pin connected in DEF that is missing from the cell's .subckt gives a warning, except on supply nets, where it is taken to be an implicit global connection.
Connections. Both regular and special nets are read, including ( * pin ) wildcard connections and component-name patterns. A component pin that is connected to two different nets shorts them together, with a warning. MUSTJOIN connections are ignored. Unconnected pins are each given their own net, named instance/pin.
Ports. The nets of the design PINS, and nets with a ( PIN name ) connection, are the ports of the design. With -L they are used as initial matches against the ports of the CDL top cell.
Supply nets. Nets with USE POWER or USE GROUND, nets of power and ground design pins, CDL .GLOBAL nets, and nets named with -V are supply nets.
Physical-only cells. Instances connected only to supply nets (fillers, tap cells, decaps, end caps) have no counterpart in a logical netlist, so they are dropped and their number is reported. Use -k to keep them. The same rule applies to X instances in a hierarchical CDL file.

For example, to compare a routed block with its netlist:

gemini -f -L -T top -V VDD,VSS top.def top.cdl

If the netlist does not show supply connections to cells (for example a CDL written from Verilog with implicit power), add -W so that the cells' supply pins are ignored in both files.

Comparing Verilog

Gemini reads structural (gate-level) Verilog, such as the output of logic synthesis, and compares it at the cell level like a DEF file. Modules defined in the file are flattened, from the top module down to instances of cells that are not defined in the file (the library cells). Each of those becomes a black box device whose type is its cell, as for DEF components, so a Verilog netlist can be compared with a DEF file, a hierarchical CDL netlist or another Verilog netlist. No Liberty or LEF file is needed.

Top module. The module named by -T, or otherwise the last module that has instances and is not instantiated by another.
Names. Instances and nets below the top module are named by their instance path, for example u_core/u_alu/n42, as in a flattened DEF. A net that crosses a module port takes the name it has in the highest module. Escaped identifiers lose their backslash, so \count_reg[0] is named count_reg[0].
Cell pins. A cell's pins are the ports named in its instances. A connection of more than one bit to a cell port gives one pin per bit, named port[n]. Positional connections to a library cell are taken in the order its pins were first named, or in the order of its .subckt ports when the other file is a hierarchical CDL netlist.
Constants. 1'b1 is connected to the tie-high net and 1'b0 to the tie-low net, VDD and VSS unless set with -H. Synthesis tools tie unused inputs this way, and place and route connects them to power and ground, so a tie-off in Verilog matches the same pin on the supply net in DEF. Wider constants such as 4'b1010 are split into bits; x and z bits are left unconnected. Nets declared supply1 and supply0 are the tie-high and tie-low nets.
Supply pins. Verilog netlists do not connect power and ground pins. A cell pin that is not connected in an instance and has the name of a supply net (for example a VDD pin learned from the DEF file) is connected to that net, so -W is not needed when comparing with DEF. The tie-high and tie-low nets are supply nets.
Assignments. assign a = b; (and wire a = b;) joins the two nets. When nets are joined the name kept is a supply net, then a port of the top module, then the name nearest the top.
Ports. The ports of the top module, one per bit (for example data[3] to data[0]), are the ports of the design for -L.
Physical-only cells. As for DEF, instances with only supply connections are dropped unless -k is given.

The reader supports both styles of module port list, input, output, inout, wire and supply0/1 declarations with numeric ranges, assign, named (.A(n1)) and positional connections, bit and part selects, concatenation ({a, b}), replication ({4{1'b0}}) and sized constants. Parameters, delays, attributes, specify blocks and functions are skipped. Behavioural code (always, initial, generate), instance arrays, port expressions in module headers and ranges given by parameters are not supported and stop the comparison with an error.

For example, to check a routed block against the synthesised netlist it was built from:

gemini -L top.v top.def

The DEF has VDD and VSS design pins that the Verilog top module has no ports for, so -L reports two unmatched ports. This does not affect the comparison.

Command line

gemini {-[SCFIPWabcfhkmotvz]} {-[DE]filename} {-[enpsw]number} {-T cell} {-V nets} {-H high,low} file1 file2

Options may appear anywhere on the line. An option that takes a value accepts it either attached (-e5) or as the next argument (-e 5). The first file named is netlist 1 and the second is netlist 2; error reports and equivalence files refer to them in that order. gemini -h prints a summary of the options.

Input

Option	Meaning
`-S`	Read SPICE/CDL netlists (the default).
`-G`	Read the original Gemini netlist format instead of CDL.
`-f`	Case-insensitive net, cell and pin names (`CLK` is the same as `clk`).
`-i`	Ignore capacitors, for example parasitic capacitors in an extracted netlist.
`-T` cell	Top cell of a hierarchical CDL file, or top module of a Verilog file. Without it, the last `.subckt` or module with instances that is not instantiated by another is used.
`-H` high,low	Nets that Verilog `1'b1` and `1'b0` connect to. The default is `VDD,VSS`. Both are supply nets.
`-V` net,net,...	Comma-separated supply net names, in addition to DEF power and ground nets and CDL `.GLOBAL` nets. May be given more than once.
`-k`	Keep black box instances that have only supply connections (fillers, decaps, taps). By default they are dropped.
`-W`	Ignore black box connections to supply nets, in both netlists.

Netlist reduction

Before matching, Gemini reduces both netlists so that equivalent but differently drawn circuits compare equal: parallel devices are merged, series resistors, capacitors and inductors are combined, and chains of series MOS transistors are collapsed. These options turn the reductions off.

Option	Meaning
`-a`	Do not reduce series resistors, capacitors and inductors.
`-b`	Do not reduce parallel resistors, capacitors and inductors.
`-c`	Do not reduce series MOS transistor chains.
`-cw`	Reduce series chains, but warn when matched chains have their gates in a different order.
`-C`	Do not reduce series transistors of different sizes. Implies property checking (`-w`).
`-F`	Do not merge parallel (fingered) MOS transistors. Normally they are merged into one device whose width is the sum of the finger widths.

Matching

Option	Default	Meaning
`-L`		Use the ports of the two netlists (`.subckt` pins, DEF design pins, or the bits of the Verilog top module's ports) as initial matches. An error is reported if the ports differ in number or name. Helps with symmetric circuits.
`-P`		Use device properties when matching, to separate devices that are otherwise symmetric. Use with `-w`.
`-E` file		Read an equivalence file of nets known to match. Each line is `=` name1 name2, where name1 is a net in netlist 1 and name2 a net in netlist 2. Lines not starting with `=` are ignored. Wrong equivalences give wrong results.
`-m`		Do not use local matching (deduction of matches from matched neighbours). Rarely needed.
`-o`		Do not optimise node labelling. Must be used with `-m`. Rarely needed.
`-N` n		Neighbourhood size for local matching.
`-p` n	2	No-progress limit: the number of passes without a new match before Gemini gives up.
`-s` n	1	Suspect-node limit.
`-e` n	0	Error limit: the number of errors allowed.

Checking and output

Option	Default	Meaning
`-w` [percent]	10	Check the properties of matched devices (W, L, R, C, ...) and warn when they differ by more than percent. Without `-w`, properties are not checked.
`-n` n	10	Net size limit: the most connections printed for a mismatched net. Mismatched supply nets can otherwise print very long reports.
`-D` file		Write an equivalence (dictionary) file of the matched nets, in the format read by `-E`.
`-g` file		Write a Glade error file with markers at the locations of mismatched devices and nets.
`-z`		Report nets with no connections.
`-v`		Verbose: print extra information while running, including the size of each DEF or Verilog design read.
`-t`		Trace execution.
`-h`		Print a summary of the options and exit.

Results

Gemini prints a summary of each netlist after reduction (devices, nets and ports), then either The netlists match or a list of mismatches for each netlist:

nets and devices that do not match;
nets and devices that could not be matched, possibly because of other mismatches (suspect);
nets and devices left unmatched because of symmetry. These are not necessarily errors; -L, -P or an equivalence file (-E) can resolve them.

For each mismatched device the nets on its terminals are printed, one per line, and for each mismatched net the devices connected to it, up to the -n limit. With -w, property differences of matched devices are reported after the comparison. When run from Glade, mismatches are also written as error markers on the extracted view.

When fixing a mismatch, start with the nets that do not match: the suspect and symmetric nets often match once the real error is fixed.