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

Welcome to FSIM !

FSIM is a fault simulator for combinational circuits. 
It employs the parallel pattern single fault propagation technique.

FSIM has been developed in the Bradley Department of Electrical 
Engineering, Virginia Polytechnic Institute & State University (VPI&SU) 
and the copy right belongs to VPI&SU.
The source code is released for teaching and research use only.
Any publication in which FSIM was used to obtain the results should 
cite the reference given below. (Please do not say that a public domain 
tool was used in this research.) 
This program, or any derivative thereof, may not be reproduced
nor used for any commercial product without the written permission.

For commercial use of FSIM or if any bugs found,
please contact to

        Dr. Dong S. Ha
        Department of Electrical Engineering
        Virginia Tech
        Blacksburg, VA 24061

        Ph.: (540) 231-4942
        Fax: (540) 231-3362
        E-Mail: ha@vt.edu
        Web: http://www.ee.vt.edu/ha

************************************************************************
REFERENCE: H. K. Lee and D. S. Ha, "An Efficient Forward Fault
           Fault Simulation Algorithm Based on the Parallel
           Pattern Single Fault Propagation," Proc. of the 1991
           International Test Conference, pp. 946-955, Oct. 1991.


/**************************** HISTORY **********************************

	fsim: version 1.0

	Original: H. K. Lee, 8/15/1990
	Updated: H. K. Lee, 8/15/1991

	fsim: version 1.1

        Changed the parser and hash functions: H. K. Lee, 1/15/1994
        Added on-line help: H. K. Lee, 3/15/1994

    ********************** Important Note **********************
    *                                                          *
    *  FSIM reads circuits in ISCAS89 netlist format           *
    *  rather than the original ISCAS85 netlist format.        *
    *  This is done so, since ISCAS89 netlist format is more   *
    *  flexible, and the manual generation of netlists is      *
    *  possible for ISCAS89 netlist format.                    * 
    *  In order to read ISCAS85 circuits in its original       *
    *  netlist format, use the option -I.                      *
    ************************************************************

***********************************************************************/



----------------- Installation Procedure -----------------------------

I.  To install fsim, follow the procedures described below.

    1. To install fsim, make a bin directory under your home
       directory. Suppose that the home directory is ~cad and
       the source code of fsim is under the directory
       ~cad/etg/fsim.

    2. Go to the directory fsim.
       "cd ~cad/etg/fsim".

    3. To compile fsim, type "make".
       An execution file "fsim" will be created.

    4. Copy fsim or link symbolically to the directory ~cad/bin.
       "cp fsim ~cad/bin" or 
       "ln -s fsim ~cad/bin/fsim".


II. Before using fsim, each user should set the following
    two environment variables as described below.
 
    1. Set  your path (or PATH) environment variable to include
       ~cad/bin in your search path. This variable, in general,
       can be fould in your ".cshrc" file. For example, the line

       set path = (. ~ ~/bin $lpath /usr/bin /usr/etc ~cad/bin)

       includes ~cad/bin to your search path.

    2. Set the FSIM_MAN environment variable to indicate the
       directory fsim, where the on-line manual of fsim is 
       located, using the setenv command as shown below.
 
       "setenv FSIM_MAN ~cad/etg/fsim"
 
       If you use fsim frequently, add the above command to your
       ".cshrc" file.
 

Run fsim as described below.



----------------- User's Guide for FSIM --------------------------


NAME:    fsim --- parallel pattern single fault simulator for
		  combinational circuits.

SYNOPSIS: fsim [options] circuit_file [> outfile]

OPTIONS: Several options are available for fsim.
         If an option is not specified, the default value is used.

-f fn    Faults are read from the file fn.
	 This option is available only for ISCAS89 netlists.
         Faults are not collapsed under this option.
         (default: faults are generated internally.)
-h g     Displays the on-line user's guide.
-h n     Displays an example netlist format.
-h t     Displays an example test pattern file.
-h a     Displays the entire on-line manual file.
         (default: no manual is displayed)
-I       The netlist format of the circuit is
         the original ISCAS85 netlist format.
         (default: the netlist format is ISCAS89 netlist format)
-l fn    Log file is created.
	 (default: no logfile is created)
-r n	 Test patterns are generated internally using the random
         number generator (random()). The simulation stops when
         either n patterns are applied or all faults are detected.
	 (default: -r 224)
-s n	 Initial seed for the random number generator (random()).
	 If n=0, the initial seed is the current time.
	 (default: -s 0)
-t fn    Test patterns are read from the file "fn".
	 The simulation stops when either all test patterns
	 are applied or all faults are detected.
	 (default: random patterns are used)

OUTPUTS: In default mode, no file is created. The summary 
	 of the fault simulation is reported to the standard 
	 output. If -l option is specified, fsim
	 creates a log file. The log file contains more detailed
	 information on the fault simulation.

ON-LINE HELP: Type fsim to see the available on-line
         help command.
 
EXAMPLES:
	fsim -t c432.test c432.bench
	   --- simulates the circuit c432.bench using the test
               patterns in the file "c432.test". The fault simulation
               stops when all test patterns in the file "c432.test"
	       are simulated or all faults are detected. 
               The summary of the fault simulation is reported
               to the standard output (CRT terminal).
	fsim -s 9999 -r 20000 c432.bench > c432.out
	   --- simulates the circuit c432.bench using 20000 random
               patterns. The random pattern generator is initialized
               by 20000. The fault simulation stops when 20000
               random patterns are simulated or all faults are
               detected. The summary of the fault simulation is
               reported to the file "c432.out".
	       



NETLIST FORMAT:
 
              The default netlist format for atalanta is ISCAS89
        netlist format except for the following two cases.
        The first line should be # followed by the name of
        the circuit. The lines beginning with # excluding
        the first line are comment lines and ignored. These
        comment lines may be put into any part of the netlist.
        It should be noted that the order of gates appearing
        in the netlist is not significant.
        The name of gates can be a string of alphanumeric
        characters (0-9, A-Z or a-z).
        ISCAS85 benchmark circuits translated in ISCAS89 netlist
        format are stored in directory ISCAS85. The name of a
        circuit in ISCAS89 netlist format is circuit_name.bench.

             The original ISCAS85 netlist format is an option
        (option -I). For ISCAS85 netlist format, lines beginning
        with * are comment lines and ignored. The gates and
        fanout lines should be described first before being
        referred by other gates. For details of the netlist format,
        refer to a documentation for ISCAS85 benchmark circuits.
        Benchmark circuits in the original ISCAS85 netlist format
        is in the directory ISCAS85_orig. The name of a circuit
        in ISCAS85 netlist format is circuit_name.isc.
 
              Example netlists of the circuit c17 written in
        ISCAS89 netlist format and ISCAS85 netlist format are
        shown below.

EXAMPLE: ISCAS89 NETLIST FORMAT (c17.bench)
--------------------------------------------------------------------
# c17
# 5 inputs
# 2 outputs
# 0 inverters
# 6 gates ( 6 NANDs )

INPUT(1)
INPUT(2)
INPUT(3)
INPUT(6)
INPUT(7)

OUTPUT(22)
OUTPUT(23)

10 = NAND(1, 3)
11 = NAND(3, 6)
16 = NAND(2, 11)
19 = NAND(11, 7)
22 = NAND(10, 16)
23 = NAND(16, 19)
-------------------------------------------------------------------
 

EXAMPLE: ISCAS85 NETLIST FORMAT (c17.isc)
--------------------------------------------------------------------
*  c17 ISCAS85 circuit
*
*  total number of lines in the netlist ..............    17
*  simplistically reduced equivalent fault set size =     22
*        lines from primary input  gates .......     5
*        lines from primary output gates .......     2
*        lines from interior gate outputs ......     4
*        lines from **     3 ** fanout stems ...     6
*
*        avg_fanin  =  2.00,     max_fanin  =  2
*        avg_fanout =  2.00,     max_fanout =  2
*
    1     1gat inpt    1   0      >sa1
    2     2gat inpt    1   0      >sa1
    3     3gat inpt    2   0 >sa0 >sa1
    8     8fan from     3gat      >sa1
    9     9fan from     3gat      >sa1
    6     6gat inpt    1   0      >sa1
    7     7gat inpt    1   0      >sa1
   10    10gat nand    1   2      >sa1
     1     8
   11    11gat nand    2   2 >sa0 >sa1
     9     6
   14    14fan from    11gat      >sa1
   15    15fan from    11gat      >sa1
   16    16gat nand    2   2 >sa0 >sa1
     2    14
   20    20fan from    16gat      >sa1
   21    21fan from    16gat      >sa1
   19    19gat nand    1   2      >sa1
    15     7
   22    22gat nand    0   2 >sa0 >sa1
    10    20
   23    23gat nand    0   2 >sa0 >sa1
    21    19
--------------------------------------------------------------------


MANAGEABLE GATES:

ISCAS89 NETLIST FORMAT:
-------------------------------------------------------
   syntax                   gate type
-------------------------------------------------------
   INPUT                    primary input
   OUTPUT                   primary output
   AND                      and gate
   NAND                     nand gate
   OR                       or gate
   NOR                      nor gate
   XOR                      2 input exclusive-or gate
   BUFF or BUF              buffer
   NOT                      inverter
-------------------------------------------------------
* Gate types can be also written in lower case.


ISCAS85 NETLIST FORMAT:
-------------------------------------------------------
   syntax                   gate type
-------------------------------------------------------
   inpt                     primary input
   from                     fanout branch
   and                      and gate
   nand                     nand gate
   or                       or gate
   nor                      nor gate
   xor                      2 input exclusive-or gate
   buff or buf              buffer
   not                      inverter
-------------------------------------------------------


TEST PATTERN FILE:
 
               The line beginning with * is a comment line and
        ignored. Each test pattern begins after a colon (:).
        For an n input circuit, only the n bits following :
        are significant, and the remaining bits, if any, are
        ignored. The j'th bit of a test pattern is the value
        of the j'th input of the circuit (in terms of their
        appearance in the circuit). For example, c17 has five
        inputs named input1, input2, input3, input6 and input7
        which appear in the order in the netlist. The first bit
        of a test pattern is the value for input1, the second
        for input2, ..., and the last for input7.
 
 
EXAMPLE: TEST PATTERN FILE FOR C17
 
___________________________________________________________
* Name of circuit:  c17
 
   1: 01010
   2: 11110
   3: 10101
   4: 00111
   5: 10010
   6: 00101
__________________________________________________________
 

FAULT LIST FILE:
 
               FSIM can read the fault list file supplied
        by the user. When the option "-f fn" is specified,
        the fault list is read from the file "fn". (In default,
        the fault list is created internally.)
 
        An example of the fault list file is shown below:
 
        ------ EXAMPLE: A FAULT LIST FILE ----------------------
        gate_A->gate_B /1
        gate_A->gate_B /0
        gate_A /1
        gate_B /1
        --------------------------------------------------------
 
               In the above example, gate_A and gate_B are the name
        of gates. The first line, "gate_A->gate_B /1" describes
        the stuck-at 1 fault on the gate_B input line, which
        is connected to gate_A. Similarly, the second line,
        "gate_A->gate_B /0" describes the stuck-at 0 fault on the
        gate B input which is connected to gate_A. The third and
        fourth lines describe the stuck-at 1 faults on the gate_A
        output and the gate_B output, respectively.
 
        ******************* Note **********************************
        The option "-f fn" works only for ISCAS89 netlists. It is
        not available for ISCAS85 netlists.
        Fault collapsing is not performed under this option. Hence,
        users should provide the collapsed fault list.
        ************************************************************

