IPOFIX, By Jeff Winston.  Help File.  Rev. 1.1  1/14/00.
Copyright (C) 1999, 2000

---------------------------------------------------------------------
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
USA.  or check out http://www.gnu.org/copyleft/gpl.html
---------------------------------------------------------------------

HOW TO COMPILE:

gcc ipofix.c -traditional -lm -o ipofix
gcc  trans.c -traditional -lm -o trans

INTRODUCTION:

IPOFIX is a program used to fix timing problems.  It performs the
following functions:

1) Given the report files from the Synopsys IPO functions, it applies
the upsize changes listed in the report, and renames the gates (which
forces Primetime to re-calculate delays based on R C loads and/or 
wireload models).  Note that the report file format used by Synopsys
is simple enough to be re-created by hand for applying user-specified
changes, or changes generated by some other method. 

2) Given a worst-case Primetime report file, IPOFIX upsizes and
renames gates whose delays exceed user-specified values.

3) Given a worst-case Primetime report file, or a transition report
file generated by VLSI's DCALC tool, IPOFIX attempts to fix transition
violations by upsizing gates.  (Upsized gates are renamed as above). 

4) Given a min-delay Primetime report file, or an explicit list,
IPOFIX inserts hold buffers where needed.

Ipofix can also write out and read back in its changes database for
external processing.

HOW TO USE IPOFIX:

The basic command line looks like:

Usage: IPOFIX [< -h|-t|-d|-c >] <input filename> [<report filename>] 
<output filename> [<database filename>] 
	Where -h prints help and exits  (use of | more recommended)
	      -t generates a database to <output filename> and exits
 	      -d enables diagnostic mode
	      -c enables normal processing until all the changes are 
	         processed, then the program writes the change database 
		 to the output file in tabular form and exits.

The input filename is the complete filename of your netlist.

The report filename is the complete filename of the report file which
specifies the changes to the netlist.  One report file can contain
multiple types of reports.

The output filename is the complete name of the output netlist or 
database file.

The database filename is the complete name of a file generated by
IPOFIX.  The file contains the module reference database. Since it
takes IPOFIX a while to generate this database, and the database is
the same for every run on the same netlist, it is faster to create the
database file once and then use it on subsequent passes of the
program.  The -t qualifier is used to generate this database.  If the
-t qualifier is not used, and no database filename is specified,
IPOFIX generates a database but does not write it out.


THE REPORT FILE

All of the commands given to IPOFIX are contained in the report file.
These commands are discussed below:

The report file is made up of one or more sections.  Each section
begins with a unique command line, and ends with the string $
END_CHANGES_FILE (this was adopted from Synopsys - which uses this in
its IPO report file).

There are 5 types of sections to the report file:

1) Synopsys IPO Output
2) Primetime delay-related output
3) Primetime hold-related output
4) Primetime transition-related output
5) VLSI DCALC transition-related output
6) IPOFIX changes database native format

Section type 1: Synopsys IPO output.

Synopsys IPO output looks like this...

=======================================
[ stuff IPOFIX doesn't care about]

$ Design:  <module_name>

[ stuff IPOFIX doesn't care about]

$ MODIFIED_CELLS
# <cell_name> (<new_ref>) : original lib_cell (<old_ref>)
SG190 (an03d3) :  original lib_cell (an03d1)
SG191 (in01d3) :  original lib_cell (in01d1)
SG192 (an03d3) :  original lib_cell (an03d1)
SG193 (in01d3) :  original lib_cell (in01d1)

$ END_CHANGES_FILE
=======================================
There must be a skipped line betwen $MODIFIED_CELLS and the
first modified cell.  Each modified cell line must have the
syntax
<cell_name> (<new_ref>) : original lib_cell (<old_ref>)



Section type 2:  Primetime delay-related output

The first line of Primetime delay-related output looks like this...
$ Primetime <top_module_name> <low_lim> <mid_lim> <hi_lim>

The rest of the section has lines IPOFIX won't care about, interleaved
with lines of the form
 
  <hierarcharical instance name> (<gate type>)         <delay> [<other stuff>]

(for example..

  ucore/cpu/hdw_regs/u13a/SG72/zn (in01d1)                0.24 *    17.56 r
)

On the $ Primetime command line you must give it the module name of
your chip.  Also, at the top of the source code in IPOFIX you must
enter the instance name of the top-level module for all gates (here it
is ucore).  The program does simple parsing.  Any line that starts
with a hierarchical name beginning with the specified top-level
instance name (e.g., ucore) is parsed for upsizing.  The upsizing
algorithm is as follows:

if delay > low_lim, upsize by 1x (up to max allowed size)
if delay > mid_lim, upsize by 2x (up to max allowed size)
if delay > hi_lim,  upsize by 3x (up to max allowed size)


Generally speaking, you can feed your entire worst case max_delay
(Path Type: max} Primetime file to IPOFIX and it will process it.
However, because you may have stuff in your file you don't want fixed
(like min delays) it is probably good practice to cut only a section
out of your PT output for IPOFIX.

At the end of your Primetime section you must add 

$ END_CHANGES_FILE

Section type 3: Primetime hold-violation-related output

For fixing hold violations, the first line of the first section of
this type in your report file must look like:

$ Primehold <top module name> <hi_limit> <lo_limit> <buffer_delay> <starting_number> \
  [<bc_sdf_rising_delay>  <bc_sdf_falling_delay>  <wc_sdf_rising_delay> <wc_sdf_falling_delay>]

(in your file this must all be on one line)

IPOFIX will fix any hold violations with hi_limit >= -slack >=lo_limit.  
Thus, limits of 1 0 will cause IPOFIX to fix all hold violations <=-1.0ns.

buffer delay is the delay that IPOFIX assumes each buffer will add.

starting_number is the number used in the hold buffer instance and
node names to guarantee uniqueness.  Make sure you advance this number
sufficiently for each subsequent run.

IPOFIX generates SDF files for all the buffers it adds.  These can be
used by Primetime and VCS as an alternative to recalculation (VCS and PT
will use the wireload model to calculate the delays of new nodes).  The
user can specify the 4 delay values for the SDF by placing them on the
$ Primehold command line.  

starting_number and the sdf values should be entered only for the first
Primehold section.  They should be omitted from subsequent sections.


For hold violations, IPOFIX parses entire paragraphs from Primetime,
an example of which is below:


  Startpoint: ucore/cbr/cbr_d_adrs_reg_6_
              (rising edge-triggered flip-flop clocked by clk)
  Endpoint: ucore/cbr/x/uc_rf0/alat5_0
            (rising edge-triggered flip-flop clocked by clk)
  Path Group: clk
  Path Type: min

  Point                                                   Incr       Path
  ------------------------------------------------------------------------------
  clock clk (rise edge)                                   0.00       0.00
  clock network delay (propagated)                        1.49 *     1.49
  ucore/cbr/cbr_d_adrs_reg_6_/cp (dfntsq1)                0.00       1.49 r
  ucore/cbr/cbr_d_adrs_reg_6_/q (dfntsq1)                 0.21 *     1.70 r
  ucore/cbr/x/U400/z (mx21d1)                             0.22 *     1.91 r
  ucore/cbr/x/uc_rf0/alat5_0/d (rlnfnb1)                  0.01 *     1.92 r
  data arrival time                                                  1.92

  clock clk (rise edge)                                   0.00       0.00
  clock network delay (propagated)                        1.92 *     1.92
  ucore/cbr/x/uc_rf0/alat5_0/en (rlnfnb1)                            1.92 r
  library hold time                                       0.27 *     2.19
  data required time                                                 2.19
  ------------------------------------------------------------------------------
  data required time                                                 2.19
  data arrival time                                                 -1.92
  ------------------------------------------------------------------------------
  slack (VIOLATED)                                                  -0.26


You should paste the paragraphs for the hold violations you want to fix 
from your PT report into your report file.  IPOFIX will ignore any hold
violations outside the limits, and any hold violations between a flop and
itself.  It will not parse the Path Type, however. 

IPOFIX adds hold buffers immediately before the d or en input of the flop.  

At the end of your Primehold section you should add 

$ END_CHANGES_FILE


Section type 4: Primetime transition-related output

Primetime transition-related output starts with a line that looks like:

$ Transitions <top-module-name> <lim1> <lim2> <lo_lim> <hi_lim>

For normal signals, gates are upsized as follows:

if violation > lim1          upsize by 1x (up to max allowed size)
if violation > lim1 + lo_lim upsize by 2x (up to max allowed size)
if violation > lim1 + hi_lim upsize by 3x (up to max allowed size)

lim2 is for special test signals that may have lower transition limits.
(The rules for this are project-specific and hard-coded into IPOFIX,
see the notes at the bottom for more details).  IPOFIX uses the same
algorithm for lim2 as for lim1.

Transition violations are output toward the end of a primetime report.
Unfortunately, most are listed referencing input pin names.  IPOFIX
cannot trace the hierarchy to find a pin driver, but Primetime can.
Thus, to generate transition input for IPOFIX, you take the transition
output (or, if you like, your entire report file) from Primetime and
feed it as input to the helper program TRANS.  This program (which 
requires a little source editing to add project-specific information)
generates a Primetime script which will take PT only a few minutes to
execute.  The output of this Primetime session must be piped to a file
which is then included in your report file (or can stand alone as a
report file).  

IPOFIX generates a report file (trans_report) showing which transition
problems were skipped.

At the end of your Transitions section you should add 

$ END_CHANGES_FILE




Section type 5: VLSI DCALC transition-related output

IPOFIX can also read the VLSI DCALC transition report.  It should be
preceded with a $ Transitions line exactly as described in the prior
section.

At the end of your Transitions section you should add 

$ END_CHANGES_FILE




Section type 6: IPOFIX changes database native format

This format is as follows:

$ START_CHANGES_DATABASE_INPUT <BC_SDF_R> <BC_SDF_F> \
                 <WC_SDF_R> <WC_SDF_F> <START SEED>
...entries...
$END_CHANGES_FILE

The tokens on the header line are defined as follows:
The first 4 are the dela values for the rising/falling default 
delays in the BC and WC SDFs generated for hold buffers.  The last 
value is the starting number used for numbering hold buffers.  
See the section above on the $ Primehold command for more details.
If no hold buffering is being performed, these values are all
don't cares but must exist.


For the entries, each entry consists of 9 tokens, each separated 
by one or more spaces, on one line, as follows:

Module Name:        The name of the module within which the 
			change applies
Instance Name:      The name of the instance to be changed
Old Type:           The name of the old instance type (or "null")
New Type:           The name of the new instance type (or "null")
Hierarchical Name:  The hierarchical name of the Module Name 
			(or "null")
Pin Name:           The name of the input pin that a hold buffer 
			is attached to (or "null")
Exact Flag:         When a 0, means to make the change only if the 
			Old Type matches. When -1, don't check type
			at all, otherwise 1.
Transition Flag:    When a 1, marks this change as transition related.  
				These changes may not be filtered out
		.		when filtering changes for certain 
				module and instance names, otherwise 0.
Buffer Count:       When non-zero, means to add this many hold buffers.

Some entries may be left as null.  The Old Type is not necessary if 
the Exact Flag is 0.  The Hierarchical Name is needed only if SDF 
files are written. Pin Name is needed only for hold-buffer insertion, 
and Old Type and New Type are not needed for hold-buffer insertion.




Important Notes:
1) When IPOFIX renames gates, it added the suffix _XQX.  These suffixes
can be removed at a later time by a global replace using sed or any
editor. 

2) IPOFIX does not uniquify.  Thus, if a module is instantiated multiple
times but has a timing problem in only one use, IPOFIX will affect all
instantiations of the module. 

3) Both IPOFIX and TRANS will require some customization.  In both programs
search for the string PROJECT-SPECIFIC and follow the instructions in the 
comments.

For TRANS, the customization is limited to a few lines which specify top
module, netlist file name, and $ Transitions command parameters.  

For IPOFIX, the customization allows you to specify certain instance types
and modules which receive special (or no) treatment. 



