********************************************************************************
                     s2ibis Frequently Asked Questions 
********************************************************************************

This file contains the answers to the most common questions asked by users of
NCSU's SPICE-to-IBIS program, s2ibis.  The following questions are answered in
this file:

QUESTIONS

(1) "Why won't s2ibis run on my machine?"
(2) "s2ibis runs, but no .out files are created, and the model is
     incomplete.  What is the matter?"
(3) "We don't have SPICE2, SPICE3, PSPICE, or HSPICE! Can we use s2ibis?"
(4) "Tables are missing.  What is the matter?"
(5) "s2ibis runs, but I'm having convergence problems. What can I do?"
(6) "How does s2ibis generate tables?"
(7) "I'm having trouble getting s2ibis to deal with my open-drain I/O pin!?!"


********************************************************************************
ANSWERS

QUESTION (1) "Why won't s2ibis run on my machine?"

ANSWER: 
       There are several common problems that cause s2ibis to fail to run.
The most common problem is that your PATH environment variable does not
include the directory in which you have the s2ibis executable located.
To check for this on UNIX systems, type:

                 which s2ibis

at the command prompt in the directory in which you want to invoke s2ibis.
If the system responds with: 

                 s2ibis: Command not found.

then this is your problem.  Move s2ibis to a directory in your PATH.  

       If your operating system can find s2ibis, and you get any error
message that does not start with:

                 s2ibis:

then there is a really big problem.  Either your executable is for
the wrong type of computer or it has been corrupted somehow.  Go to 
the directory that the executable is in and type:

                 file s2ibis

If you get something like:

    s2ibis: mipsel demand paged executable - version 2.10

or:
 
    s2ibis: sparc demand paged dynamically linked executable 

or:

    s2ibis: executable (RISC System/6000 V3.1) or object module

it should work OK, so if it doesn't it must be corrupted.  If you get
something like:

    s2ibis:  data

your operating system doesn't think s2ibis is a program, so it is 
probably an executable for another type of computer.  Copy the correct
executable from the S2IBIS/bin directory into a file named s2ibis in
a directory listed in your PATH environment variable.  The executables
are in the S2IBIS/bin directory, and have the machine they are intended
for in the suffix.  Thus s2ibis.sparc is for Sun SPARCstations, etc.

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

QUESTION (2) "s2ibis runs, but no .out files are created, and the model is
              incomplete.  What is the matter?"

ANSWER:

        s2ibis is probably having trouble locating your SPICE program.  If
you do not put one of the following lines in your s2ibis input file header,
s2ibis will try to use Berkeley SPICE 2 (using the call spice infile outfile):

          *[Spice] 3
          *[Spice] P
          *[Spice] H

These lines cause s2ibis to try to call SPICE3, PSPICE, and HSPICE, 
respectively.  

       If you have specified the correct version of SPICE, and 
s2ibis still can't find it, it may be because your PATH does not include
the directory that your SPICE executable is in, or because the name of the
executable is non-standard.  s2ibis expects to be able to call SPICE using
one of the following calls:

                    spice inputfile outputfile
                    spice3 -b inputfile >outputfile 2>messagefile
                    pspice inputfile outputfile /D0
                    hspice inputfile >outputfile 2>messagefile

UNIX systems are case-sensitive; every letter in the command you type 
must match the corresponding letter in the name of the executable exactly.
Thus if your SPICE executable is:

                           /bin/SPICE3

s2ibis will not be able to find it.  If you can go to the directory from
which you intend to run s2ibis and invoke SPICE using one of the calls
listed above, s2ibis should work.  (Note that the spice3 and hspice calls
will only work in Bourne shells. In c-shells [csh] or tc-shells [tcsh]
leave off the 2>messagefile )   If these calls do not work you can fix the 
problem by adding the appropriate directory to your PATH, changing the name of
the executable, or adding a soft link that points to the executable in
one of the directories that is in your PATH.    If this explanation does
not make sense to you, talk to your system administrator.  He or she will
probably be able to make it work fairly quickly.

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

QUESTION (3) "We don't have SPICE2, SPICE3, PSPICE, or HSPICE! Can we use 
              s2ibis?"

ANSWER: 
       Probably.  You may not even have to change the code.  If your version of
SPICE is compatible with any of the standard SPICE packages directly supported,
you can probably just put a soft link into one of the directories in your PATH
that points to your version of SPICE.  For instance, if your package, MYSPICE,
can understand a SPICE3 netlist (and control cards), you can probably just 
issue the command:

      ln -s /directory_myspice_is_in/MYSPICE spice3

in a directory that is in your PATH.  This assumes that MYSPICE has a similar
calling sequence to SPICE3:  spice3 -b input_file > output_file. 

If your package doesn't meet one of these criteria, you may need to change
s2ibis' calling sequence, or do more serious surgery.  Changing the calling 
sequence is quite easy.   Using the *[Spice_Command] directive, you can
specify the calling sequence that s2ibis uses to anything you want.
Here is an example for a package named MYSPICE that is compatible with SPICE3 
but uses the calling sequence:

             MYSPICE -input input_file -output output_file 

Just put the line

             *[Spice_Command] MYSPICE -input %s -output %s 

just before or after the *[Spice] 3 line in your input file.  Any call that
allows the input, output, and message files to be called in that order
can be accommodated similarly.  Calls that cannot be accommodated require
changing the callspice() routine in the source file src/models.c.  This is
fairly straightforward.

     If your package is not compatible with any of the standard packages, you 
will need to change the routines that make up the SPICE decks and/or the 
routines that interpret the results as well.   This could be quite simple, or 
very complicated, depending on how big the differences are.  If your package can 
accept standard SPICE decks, but has a different output format, it may be pretty 
easy to deal with.  The routines that read in the SPICE output data are fairly 
simple. They are called getspicedata() and getrampdata(), and they are also in 
the file models.c.  The routine getspicedata() reads in the data for all the DC 
simulations.  The part that reads in SPICE3 outputs is about 50 lines long, so 
it may be pretty easy to modify.  The getrampdata() routines are not much more 
complicated.  If you need to change the SPICE decks, it will be more work, but 
it may still be pretty easy.  The problem there is that the code for generating 
the SPICE decks is spread out over a large routine called makemodel() (about 
3000 lines...).  It was written that way to make it easy to customize each 
simulation type if the need arose.  If your SPICE has a different format for its
.PRINT statement, for instance, you could just search through the makemodel() 
routine for all the .PRINT cards and edit them to do the right thing. 

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

QUESTION (4) "Tables are missing.  What is the matter?"

ANSWER: 
       Missing tables result for two different reasons: aborted SPICE 
simulations and low clamp currents.  

       The second case is the simplest.  s2ibis checks the typ column of all
clamp tables for low currents.  If none of the entries in the typ column exceed
the [Clamp_Tolerance] limit, the table is suppressed.  (Please note: for pins of
[Model_type] Output, no clamp tables are ever generated.) The [Clamp_tolerance]
limit can be changed by putting the following line in the s2ibis header:

                *[Clamp_Tolerance] amps

where amps is a floating point number specifying the new limit in Amperes.  Any
number may be used, so you can disable checking by specifying a large negative
number.  *[Clamp_Tolerance] -1.0 should disable checking in all practical cases. 

       Aborted SPICE simulations are more complicated.  s2ibis tries to make a
syntactically-correct IBIS model even when SPICE simulations abort.  The 
strategy is fairly straightforward.  For DC simulations, [Pullup], [Pulldown],
etc., s2ibis will always generate a syntactically correct table if the typ
simulation works.  If s2ibis detects an aborted min and/or max simulation for a 
table for which the typ simulation  completed, it will use the IBIS reserved
word NA in the appropriate column(s).  s2ibis reports all aborted simulations
on stderr.   s2ibis checks the number of points in the output decks of min and 
max simulations against the number of points in the associated typ simulations.  
If the number disagrees, the min or max simulation is considered aborted and the 
entire column is assigned NAs.  If the typ simulation aborts,  The resulting 
table will not meet the IBIS specification, but it will contain a comment
explaining that the associated simulation has aborted, and it is possible to
make it acceptable to IBIS by replacing two NA entries with floating point
numbers.

        Transient simulations, which are used to generate [Ramp] tables,
are treated differently.  Six simulations are run: two typs, two mins, and
two maxes.  Any simulation that works results in an entry in the [Ramp] 
table.  Any simulation that fails will result in an NA entry in the [Ramp]
table.  If either typ simulation fails, the table will not meet the IBIS
specification.  s2ibis prints out a warning message to stderr in this case. 
Ramp simulations are considered aborted if no transition is detected, even if
the simulation completed without aborting.  Currently, s2ibis does not check
the size of the output transition, so nonsense results are possible if the
user does not check the output data to make sure that the transitions were of
reasonable size.  


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

QUESTION (5) "s2ibis runs, but I'm having convergence problems. What can I do?"

ANSWER:
       First, make sure you understand the operation of the *[Iterate] switch,
which is explained in the man pages.

       You can use the *[Iterate] switch to get s2ibis to read in SPICE output
files that were generated from SPICE simulations that were not initiated by
s2ibis.  Thus, you can take the SPICE input decks that are having convergence
problems, and modify them to help them converge.  Anything that you can do to
make them converge is OK, as long as the format of the output file is similar
to the output that s2ibis expects.  

       A couple of important caveats are in order.  Do not let the length of
the tables in the outputs exceed 150 points.  If you do, s2ibis will surely
bomb.  Make sure that you use any control cards necessary to keep your SPICE
outputs in scientific notation.  For instance,  use the .OPTIONS POST INGOLD
mechanism in HSPICE to keep HSPICE from putting units at the end of the numbers
in the tables.  s2ibis does not accept unit specifiers at the ends of any
numbers.  Also, s2ibis  requires certain units for all variables.  Voltages
must be specified in Volts, currents in Amperes, time in seconds.  

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

QUESTION (6): "How does s2ibis generate tables?"

ANSWER: 
      s2ibis uses the following scheme for determining what tables need to be 
generated for a particular pin:

      0) For POWER, GND, and NC pins, no tables are
         generated.

      1) For each Input pin, s2ibis automatically
         runs SPICE jobs for [GND_clamp] and [POWER_clamp] 
         tables.  If the typ column in either of the
         resulting tables exceeds the clamp tolerance
         limit (default 1 microamp, changeable by user),
         that table is printed.  

      2) For each  Output (*Not* I/O, 3-state, or 
         Open_drain) pin, s2ibis generates [Pulldown]
         and [Pullup] tables only.  Clamp simulations
         are not even attempted for Output pins.
         [Ramp] tables are generated by causing the
         output to transition while attached to the
         IBIS-specified load, reading the 20% and 80%
         points of the transition, and calculating
         the slope in between these points.

      3) For each I/O or 3-state pin, s2ibis generates
         SPICE simulations for [Pulldown], [Pullup],
         [GND_clamp], [Power_clamp], and [Ramp] tables.
         Generation of the [Ramp] tables uses exactly
         the same procedure as described above under
         Ouput pins. Generation of the  [Pulldown], 
         [Pullup], [GND_clamp], and [Power_clamp] tables
         involves a current partitioning scheme.  

         First s2ibis runs the [GND_clamp] and
         [Pulldown] simulations.  The [Pulldown] table
         is generated as follows:
 
         pulldown(-5->0):subtract the associated
         ground clamp table from the pulldown table

         pulldown(0->Vcc):just use the pull-
         down table as simulated

         pulldown(Vcc->2*Vcc):extrapolate using
         the point at Vcc and the point five points
         before Vcc in the pulldown table.

         The [GND_clamp] table is not modified.

         The [Pullup] and [POWER_clamp] tables are
         created using an analogous procedure.

         Then s2ibis runs the [POWER_clamp] and
         [Pullup] simulations.  The [Pullup] table
         is generated as follows:
 
         pullup(-5->0):subtract the associated
         power clamp table from the pullup table

         pullup(0->Vcc):just use the pull-
         up table as simulated

         pullup(Vcc->2*Vcc):extrapolate using           
         the point at Vcc and the point five points 
         before Vcc in the pulldown table. 

         The [POWER_clamp] table is not modified.


      4) For Open_drain pins, the procedure for output
         pins is followed, except no [POWER_clamp] or
         [Pullup] simulations are run, and the corres-
         ponding tables are not produced. 

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

QUESTION (7): "I'm having trouble getting s2ibis to deal with my open-drain 
               I/O pin!?!"

ANSWER:
       This is a problem with the IBIS v1.1 spec.  IBIS v1.1 sees open-drain
       pins as output only.  You need to go to a newer IBIS version.

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