/*******************************************************************
*  MINARET (for edge-triggered circuits)
*
*  BY
*
*  NARESH MAHESHWARI AND SACHIN S. SAPATNEKAR
*
*  Copyright 1998 Naresh Maheshwari and Sachin S. Sapatnekar
*  All Rights Reserved
*
*  Source Code for retiming edge-triggered circuits
*
*  ASTRA:   Refer to paper in DAC 95 by Deokar & Sapatnekar
*                       and IEEE Tran on CAD 10/1998
*  Minaret: Refer to paper in DAC 97 by Maheshwari & Sapatnekar
*                       and IEEE Tran on VLSI 10/1998
*
*  Contact Address: sachin@ece.umn.edu
*
*        Availiable on as is basis, with no support
*******************************************************************/
This file contains some general comments about the code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FILES :

README          : Information on use of the code.
Code.doc    	: This file; some comments about the code, usefull only if modifing the code
Makefile        : Unix makefile for the code

include.h       : has the include files to be added to C code
var.h           : has the global variables
declare.h       : has constant definitions
type.h          : has the data types defined

common_utils.h  : function prototyping files
function.h
main.h

bell.c          : Clock skew optimization code
bounds.c        : Code for calculating the bounds on r(v), in minarea retiming.
cnvt.c          : Code to convert between the circuit model and the C-graph model 
graph.c         : Code to construct the Phase A constraint graph (S-graph)
hash.c          : Hashing routines for input parsing
heap.c          : Heap routines for period constraint generation
io.c            : Functions to write the final circuit netlist
latch_utils.c   : Utilities to add and delete latches from the circuit
lex.l           : Lex grammer for input parsing
main.c          : Main function and top level functions for minarea and minperiod retiming
pert.c          : Code for all-pair input-output delay calculation using PERT, for Phase A
phase2.c        : Code for Phase B of ASTRA, performs the actual motion of latches (as edge weights)
postproc.c      : Code for postprocessing of the netlist to reduce number of latches (by latch sharing)
print.c         : Some print functions for debuging
slack.c         : Code to compute slack information by using PERT (both forward & backwards) 
utils.c         : Misc utility functions
wd.c            : Code to generate period constraints for minarea retiming
yacc.y          : Yacc grammer to parse the input netlist
retime.c        : Misc functions
simplex.c       : Network simplex algorithm to solve the mincost flow problem

check.c         : To remove unreachable nodes; NOT part of retiming code

**************************************************************************

Some symbols and notations that may have been frequently used in the code
no	number
inc	increment
vars	variables
verts	vertices
mem	memory
pio	primary input/output
pout	primary output
pin 	primary input
nai	number of active inputs
nao	number of active outputs
D/S	data structure

FF and latch is used interchangabily
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The code has many data structures (D/S) some of which are:

circuit	: This is the D/S in which the circuit netlist is read in.
	It is a graph structure with vertices for all gates, latches
	and primary inputs/outputs. Each vertex has a unique "id", and 
	pointers to all vertices are available in array "nodes" indexed
	by their "id". The interconnections are modeled by linked lists,
	called "fanin" and "fanout". The fanout list contains the "id" not
	pointers to the fanout. The interconnection is bidirectional, i.e.,
	if u is in fanin of v, then v is in fanout of u. More information 
	can be found in file "type.h" and "yacc.y". PERT can be  performed 
	on this D/S only.

C-graph	: This is a modified version of "circuit" above, with latches now
	being represented by edge weights, rather than vertices, much like
	the graph representation of Leiserson and Saxe.
	C-graph shares the D?S with circuit, hence only one of these two is
	available at any given time, routines to translate between the two 
	are given in file "cnvt.c".

S-graph : This is the constraint graph in Phase A of ASTRA, and is not used
	anywhere else. It contains one vertex for every latch, and one for 
	Host. Edges exist between latches that have a combinational path
	between them, see files "graph.c" and "pert.c".

Simplex Network : This is also a graph with a node for every variable (gate or
	mirror) and a edge (called arcs in the code) for every constraint in 
	the LP. It is used only to solve the minarea LP and is almost self 
	contained in file "simplex.c". 

Other minor D/S include:
o  A "SAVE_LATCH" structure to store information on latch location and skew,
	 used in "bounds.c".
o  Hashing D/S in file "hash.c" for hashing during input parsing.
o  Heap D/S used in file "heap.c" for period constraint generation.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
SOME COMMENTS:

This code was developed over more than 3 years (95-98), so at places 
things are not done in the simple ways. It was initially developed for minperiod 
retiming using ASTRA, and used only the "circuit" D/S above. Since latches 
are added and deleted during retiming, a trick was used to enable use of 
array "nodes" to hold pointer to all nodes. Another array "validnodes" is  
added to identify only valid nodes, and an array "freenodes" is used to store 
empty/invalid nodes (caused by deleted latches), when a new latch has to be added
a node was taken from "freenodes" and used. This enabled the reuse of the 
same "id" for latches. This is the reason by "maxid" changes during retiming.
Even after moving to the "C-graph" structure, where latches are maintained as
edge weights, this procedure is used to add explicit latches to the circuit in 
the end. All of this can be cleaned if PERT (in file "pert.c" and "slack.c")
an be performed on "C-graph", thus removing the "circuit" D/S.

This code was also used to compare Minaret with other methods, and 
various methods to solve the LP. this was done by using various "modes",
most of which have been cleaned but some are still there. Mainly "Red_Mode"
is still in use and should always be set to "REDUCE". Changing "Red_Mode"
to "SHENOY" will disable the key features of Minaret, and should be used
with care.

The "circuit" D/S contains some artificial gates added at primary inputs and 
primary outputs, these are removed in the end. The primary input and output nodes 
are deleted during minarea, since these artificial gates are there.
 It is possible to get rid of this mixup by not adding artificial node and not 
deleting primary inputs and outputs.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PROGRAMMING TRICKS USED

The function "get_bounds" is not currently capable of handling unconstrained
minarea retiming, and is used with a large value of target clock period to 
simulate unconstrained minarea retiming. The bounds on the r variables are of
very limited use in unconstrained minarea retiming (although some reduction
is still obtained).

In file "heap.c", the function "memset" is used to initialize the heap memory
to save CPU time. Also in function "get_bounds" the all-pair input-output 
PERT is run only once to save CPU time.

To save memory many fields in structures (e.g, level,phase,nai,nao ) are reused
 by more than one function and for more than one purpose. This can cause unwanted
side effects when modifying the code.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
WARNINGS

Handling of HOST vertex is not very good, it is broken into two before generating
the period constraints, then recombined.

A lot of global variables are used to pass information between functions. It is done
wherever the function needed to return more than one variable.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


