NETGEN:  VERSION 1.2

NETGEN is a general-purpose netlist management system.  It can read
and write several netlist formats, including NTK (Caltech, CMU),
WOMBAT (Berkeley), SIM (Berkeley), ACTEL (Actel Inc., Sunnyvale), and
SPICE (Berkeley).  In addition, a C-language embedded interface exists
for specifying netlists directly.  Please see the documentation file
NETGEN.DOC

NETGEN was intended as an efficient specification language for
hierarchical systems.  Secondary features, such as testing isomorphism
between two netlists, have been added over time.  As netgen has
primarily been used in its capacity as a netlist comparator, this
has essentially become the primary useful feature of netgen.

Version 1.2 (Mar. 2003) takes the original netgen and recasts it
as a Tcl extension in the same manner as magic version 7.2 and
IRSIM version 9.6, while retaining the option to compile the original,
non-interpreter-based version(s).  Under Tcl, all of the single-character
commands have been recast as complete function names.  The syntax has
been changed to match Tcl generally-accepted syntactical norms.  The
X11 GUI has been scrapped and may eventually be replaced by a Tk GUI.

REVISION HISTORY:
-----------------
Revision 0: December 29, 2002  (first cut of port to Tcl).
	1) New command-line interface with full-word commands.
	2) The usual "toolscript" stuff with printf() functions
	   passed to Tcl's "eval" function, support for and use
	   of the TkCon console, compilation as a Tcl shared-object file.
	3) New "make config" script to match magic's.

Revision 1: January 10 2003.
	1) Improved "nodes" and "elements" commands so they return relevant
 	   information about specific points in the network.
	2) Added position information to ".sim" file elements, so this can
	   be used to trace back problems to a layout and/or schematic.
	3) Fixed errors in the printing routines.
	4) Improved some horribly inefficient code; speeds up some node
	   printing commands and causes the "compare" command to become
	   nearly instantaneous.
	5) Removed regular-expression matching from the code.  It is
	   intended that Tcl's built-in regular expression matching will
	   suffice, although it will be necessary to rewrite some functions
	   to return Tcl lists instead of just dumping text to the screen.
	   The main effect this has is that arrayed nodes in magic retain
	   their names, simplifying the (intended) interface to magic.

Version 1.2, Revision 0: March 10 2003.
	1) Fixed and extended the log file capability through the Tcl
	   command "log".  Includes the ability to turn screen echo on
	   and off while logging.
	2) Implemented Control-C interrupts during lengthy procedures,
	   both for the TkCon console window and for the terminal-based
	   mode.
	3) Created the scripted command "lvs" to do what the standalone
	   program "netcomp" used to do.

BUILDING NETGEN:
----------------
NETGEN version 1.2 uses the same "make" procedure as Magic version 7.2
and IRSIM version 9.6.  The "make config" stage will prompt for choices,
which are described below.  Generally speaking, the make method is:

   make config
   make
   make install

Or, for the Tcl interpreter-based version:

   make config
   make tcl
   make install-tcl
   
MAKE CONFIG OPTIONS:
--------------------

- Choice of interpreter:
  Choosing "1" will build the original (non-interpreter-based) version
  of netgen, with separate executables for netgen, netcomp, and ntk2adl.
  In addition, a new executable "inetcomp" has been added which incorporate
  the features of the interactive netlist comparator without the rest of
  "netgen".

- Choice of graphics:
  If Tcl is chosen as the interpreter, the choices are Tk graphics or
  no graphics.   At the moment, there is no real difference between the
  two;  in the future, this will affect whether or not the program
  starts with a GUI interface.
  
  If no interpreter is selected, graphics are either X11 or none.  With
  X11, the configure script will attempt to determine the widget set to
  use (Motif if it exists, otherwise Athena.  Xw is largely nonexistant
  except for a mutated version embedded in xcircuit).  With "none"
  selected, netgen is a purely command-line driven program.  With "X11"
  selected, netgen is operated via a GUI interface.  Currently, these
  two modes are mutually exclusive (hopefully this will be fixed
  shortly).

- Choice of OS:
  Select the correct operating system for your machine, or "none" if
  there is no exact match (netgen will attempt to compile with
  default flags, but some hand-editing of "defs.mak" may be necessary
  for an error-free compilation).

- Choice of hardware:
  Select the correct machine type, or "nothing special" if there is
  no exact match.

IN CASE OF FAILURE
-------------------
Please contact me (tim@bach.ece.jhu.edu) to report compile-time and
run-time errors.  The website at

	http://bach.ece.jhu.edu/~tim/programs/

should be updated in the near future to incorporate information about
netgen version 1.2.

RUNNING NETGEN UNDER TCL
------------------------
The normal procedure for doing a netlist comparison (LVS) is the following:

1) Build ".sim" files for the two netlists to be compared (e.g., run
   "exttosim" on the magic layout, and generate sim output on an xcircuit
   schematic.
2) Run netgen.
3) Do the following commands:

	readnet sim <filename1>
	readnet sim <filename2>
	compare <filename1> <filename2>
	permute
	run converge

   Note that "permute" equates port type ID's on the existing database, so
   running "permute" before reading a network has no effect.

4) As of version 1.2, netgen has a script-level procedure "lvs" which
   takes care of the above sequence of commands, as well as dumping the
   majority of the output to an output file, and reporting only the
   final analysis in the console window.  The syntax of this command is:

	lvs <filename1> <filename2> [<logfilename>]

   If "logfilename" is not specified, then the default filename "comp.out"
   will be used.

5) Interpreting the output:

   The feedback from netgen is still rather crude but improving in each
   generation.  Illegal fragments are generated around areas where the
   netlists cannot be resolved.  The worst matches will be listed at the
   top, which is usually the place to start looking.

   Connectivity of elements and nodes is much easier to trace now, with
   commands:
	
	nodes <element_name> <cellname>
	elements <node_name> <cellname>

   Where "cellname" is the filename (one of the two files loaded for
   comparison).  The "elements" command prints all of the elements
   (transistors, capacitors, resistors, etc.) connected to a specific
   named node.  The "nodes" command prints the node names for each
   pin of the specified element.  For ".sim" netlists containing
   position information for each transistor, all transistor elements
   (and some non-transistor elements such as poly-poly capacitors and
   rpoly resistors extracted from magic) will have names like
   "n@45,376" indicating an n-type transistor at position x=45, y=376
   on the layout.  This naming convention permits tracing errors back
   to the layout and schematic.

