INTRODUCTION

	s2ibis2 is the latest version of the SPICE-to-IBIS conversion
	utility from North Carolina State University.  It produces IBIS
	files which conform to the IBIS v2.1 specification.

	s2ibis2 is a departure from s2ibis v1.2 in a couple of ways.
	First, it has its own command language, which is similar to the
	IBIS language in many respects, and can be easily extended to
	include new functionality.  Second, its mode of operation is
	different: rather than producing its output "on the fly", as in
	earlier versions of s2ibis, s2ibis2 creates a full IBIS model in
	an internal data structure, and then writes the resulting
	information to the output file after all processing is done.
	As a result, s2ibis2 can easily be extended to comply with
	future versions of the IBIS specification.

	(Note, however, that s2ibis2 still creates lots of spice input,
	output and message files, unless you have used the [Cleanup]
	command in your command file!)

	This document will mostly describe the s2ibis2 command language
	and how to properly use it.  I would strongly suggest examining
	the file test/tryme.s2i to get a feel for how these commands are
	used.

	Note that the command parser ignores case when it reads the
	command file, so you may specify the commands in upper or lower
	case, or a mix of the two.

	Also note that s2ibis2 has several reserved words:

		NA	specifies that the value is undefined
		NC	specifies no connection; can be used as model name
		POWER	reserved model name for power pins
		GND	reserved model name for ground pins
		+	line continuation character when found in first
			column of line


THE COMMAND LANGUAGE

	Commands are passed to s2ibis2 in a command file.  This file can
	be specified on the command line when s2ibis2 is invoked:

		% s2ibis2 tryme.s2i

	If the file is not specified on the command line, s2ibis2 will
	ask you for the command file name:

		% s2ibis2
		s2ibis2 v0.9BETA -- North Carolina State University

		input file: tryme.s2i
	
	The command file consists of two main sections: the header and
	the component description.


THE HEADER

	The header contains information that is applicable to the entire
	file, such as the type of SPICE simulator to use, the IBIS
	version, etc.  It can also contain global specifications.  For
	example, if you want a particular temperature range to apply to
	all models in your file, specify it in the header.  Note,
	however, that global definitions are overridden by local
	definitions; in this way, you can specify (e.g.) a global
	temperature range, but override it for a particular component or
	model where necessary.

	The following commands can be used in the header:

	[IBIS Ver]	version

		version = 1.1 or 2.1
		
		Required.
		
		THIS MUST BE THE FIRST COMMAND IN THE COMMAND FILE.  (It
		may be preceded by comments.)  This describes the
		version if IBIS to produce.  Legal version values are
		1.1 and 2.2.

		Note that this currently makes no difference in how
		s2ibis2 processes the model.

	[File name]	filename

		filename = name of IBIS file to produce
		
		Optional. 	
		Default: First 8 chars of command filename followed by
		".ibs".
		
		This tells s2ibis2 what the output file name should be.
		NOTE:  this must conform to DOS conventions, i.e. it
		must be in the form "xxxxxxxx.xxx".  If this command is
		not used, s2ibis2 creates the output file name by taking
		the first part of the command file name, and appending
		".ibs" to it.  So, for the command file name
		"tryme.s2i", the output file name would be "tryme.ibs".

	[File rev]	rev

		rev = revision number
		
		Optional.
		Default: none.

		This describes the current file revision.  Note that
		s2ibis2 will accept any legal string for the revision
		number.

	[Date]		date

		date = file date
		
		Optional.
		Default: Current system date.

		Gives the file date.  If this command is not present,
		s2ibis2 will use the current system date as the file
		date.

	[Source]	source

		source = file source
		
		Optional.
		Default: none.
		
		Describes the file source.  Truncated if longer than
		1K byte in length.

	[Notes]		notes

		notes = file notes
		
		Optional.
		Default: none.
		
		Describes any optional notes that may be necessary.
		Truncated if longer than 1K byte in length.

	[Disclaimer]	disclaimer

		disclaimer = file disclaimer
		
		Optional.
		Default: none.
		
		This is where you put the legalese.  Truncated if longer
		than 1K byte in length.

	[Copyright]	copyright

		source = file copyright
		
		Optional.
		Default: none.
		
		Describes the copyright info.  Truncated if longer than
		1K byte in length.

	[Spice type]	spicetype

		spicetype = HSpice, PSpice, Spice2, Spice3, or Spectre

		Required.
		
		Describes which flavor of Spice to use when simulating
		the circuits.

	[Spice command]	command

		command = command to use when invoking Spice.

		Optional.
		Default: specified in s2istrng.h
		
		BE VERY CAREFUL WITH THIS COMMAND.  The default command
		string is dependent upon the flavor of Spice you use.
		This string specifies, in C syntax, how you would call
		Spice from the command line.  It has three "%s" printf
		conversion characters, one each for the spice input
		file, the spice output file and the spice message file
		(this last is optional if necessary), IN THAT ORDER.
		See the string variable defaultSpiceCommand in the file
		src/s2istrng.h for an example of the correct format.

	[Iterate]

		Optional.
		Default: none.
		
		This works the same way as the *[Iterate] command in
		s2ibis v1.2.  If a Spice output file for the curve in
		question already exists, s2ibis2 will read the data from
		that file without re-running the simulation.  In this
		way, you can make incremental changes to your s2ibis2
		files without having to re-simulate the whole thing over
		and over.

	[Cleanup]
	
		Optional.
		Default: none.
		
		This is sort of the "converse" of the [Iterate] command.
		When this command is specified, s2ibis2 will delete all
		of the spice input, output and message files as it
		proceeds.  This is good to use when you think the IBIS
		file is done and you want to clean up the working
		directory.

	[Temperature range]	T_typ	T_min	T_max

		T_typ = temperature for TYP curves
		T_min = temperature for MIN curves
		T_max = temperature for MAX curves

		Optional.
		Default: T_typ = 50C, T_min = 0C, T_max = 100C.

		Specifies the temperature, in degrees C, under which to
		run the TYP, MIN and MAX simulations.

	[Voltage range]		V_typ	V_min	V_max

		V_typ = supply voltage for TYP curves
		V_min = supply voltage for MIN curves
		V_max = supply voltage for MAX curves

		Optional.
		Default: V_typ = 5.0V, V_min = 4.5V, V_max = 5.5V

		Specifies the supply rail voltage.  See the IBIS v2.1
		specification for a thorough treatment of this.

		NOTE:  You MUST specify a voltage range for all
		models, either with this command or with ALL FOUR of the
		following commands.

	[Pullup reference]	V_typ	V_min	V_max

		V_typ = pullup supply voltage for TYP curves
		V_min = pullup supply voltage for MIN curves
		V_max = pullup supply voltage for MAX curves

		Optional.
		Default: none.

		Specifies the pullup reference supply.  See IBIS v2.1
		specification for details.

	[Pulldown reference]	V_typ	V_min	V_max

		V_typ = pulldown supply voltage for TYP curves
		V_min = pulldown supply voltage for MIN curves
		V_max = pulldown supply voltage for MAX curves

		Optional.
		Default: none.

		Specifies the pulldown reference supply.  See IBIS v2.1
		specification for details.

	[POWER clamp reference]	V_typ	V_min	V_max

		V_typ = power clamp supply voltage for TYP curves
		V_min = power clamp supply voltage for MIN curves
		V_max = power clamp supply voltage for MAX curves

		Optional.
		Default: none.

		Specifies the power clamp reference supply.  See IBIS
		v2.1 specification for details.

	[GND clamp reference]	V_typ	V_min	V_max

		V_typ = ground clamp supply voltage for TYP curves
		V_min = ground clamp supply voltage for MIN curves
		V_max = ground clamp supply voltage for MAX curves

		Optional.
		Default: none.

		Specifies the ground clamp reference supply.  See IBIS
		v2.1 specification for details.

	[R_pkg]		r
	
		r = parasitic pin resistance

		Optional.
		Default: 0

		Describes the default pin resistance for the package.

	[L_pkg]		l
	
		l = parasitic pin inductance

		Optional.
		Default: 0

		Describes the default pin inductance for the package.

	[C_pkg]		c
	
		c = parasitic pin capacitance

		Optional.
		Default: 0

		Describes the default pin capacitance for the package.

	[C_comp]	C_typ	C_min	C_max
	
		C_typ = silicon die capacitance for TYP curves
		C_min = silicon die capacitance for MIN curves
		C_max = silicon die capacitance for MAX curves

		Optional.
		Default: C_typ = 5pF, C_min = 5pF, C_max = 5pF

		Describes the silicon die capacitance.

	[Rload]		r

		r = load resistance for VI curves

		Optional.
		Default: r = 50 ohms.

		Describes the load resistance to use when performing the
		simulations for the VI curves.

	[Sim time]	t

		t = Spice transient simulation time

		Optional.
		Default: t = 10ns.

		Describes the transient simulation time to be used by
		Spice.

	[Derate VI]	x

		x = percent to derate VI curves

		Optional.
		Default: x = 0%

		Describes the percentage to derate the VI curves, as
		described in the IBIS v2.1 spec.  Note that x should be
		expressed as a percentage, not a fraction.  For example,
		to derate 15%, use [Derate VI] 15, _not_ [Derate VI] 0.15.
		
	[Derate ramp]	y

		y = percent to derate ramp rates

		Optional.
		Default: y = 0%

		Describes the percentage to derate the ramp rates, as
		described in the IBIS v2.1 spec.  Note that y should be
		expressed as a percentage, not a fraction.  For example,
		to derate 15%, use [Derate VI] 15, _not_ [Derate VI] 0.15.
		

THE COMPONENT DESCRIPTION

	The component description provides s2ibis2 with a model of
	your component.  You may have multiple component descriptions
	per file--all components will be written to the same output
	file.

	As in the header, you may have component-wide specifications of
	certain values.  Also as in the header, these component-wide
	values will be overridden by a more local definition (i.e. one
	within a particular model).  As an example, you could specify a
	component-wide voltage range, and then override this within (for
	example) an ECL model.

	The component description consists of several parts.  It starts
	with the [Component] keyword, which specifies the name of the
	component (see below).  This is followed by the component
	header, which contains information which pertains to the entire
	component.  The header is followed by the differential pin list
	(optional), pin mapping (optional), pin list (required) and
	model specifications (required).  These four need not be in any
	particular order.


THE [Component] KEYWORD

	This keyword specifies the start of the component.  It takes the
	following form:

	[Component]	name

		name = component name

		Required.

		This command specifies the start of a new component.
		The component name may contain spaces.  It will be
		truncated to 40 characters in length.


THE COMPONENT HEADER

	This is where you specify variables that will apply to the
	entire component.

	The following commands may be used in the component header:

	[Manufacturer]	name

		name = manufacturer's name

		Optional.
		Default: none.

		This describes the manufacturer's name, which may
		contain spaces.  It will be truncated to 40 characters
		in length.

	[Package model]	name

		name = package name

		Optional.
		Default: none

		This describes the package model to use for the
		component packaging--see the IBIS v2.1 specification for
		more detail.  May contain spaces.  Will be truncated to
		40 characters.

	[Spice file]	filename

		filename = name of Spice file which describes component

		Required.

		This gives the name of the Spice file which describes
		the component topology.  Must conform to DOS naming
		conventions.

	[Temperature range]	T_typ	T_min	T_max
		See section "THE HEADER" (above) for description.

	[Voltage range]		V_typ	V_min	V_max
		See section "THE HEADER" (above) for description.

	[Pullup reference]	V_typ	V_min	V_max
		See section "THE HEADER" (above) for description.

	[Pulldown reference]	V_typ	V_min	V_max
		See section "THE HEADER" (above) for description.

	[POWER clamp reference]	V_typ	V_min	V_max
		See section "THE HEADER" (above) for description.

	[GND clamp reference]	V_typ	V_min	V_max
		See section "THE HEADER" (above) for description.

	[R_pkg]		r
		See section "THE HEADER" (above) for description.

	[L_pkg]		l
		See section "THE HEADER" (above) for description.

	[C_pkg]		c
		See section "THE HEADER" (above) for description.

	[C_comp]	C_typ	C_min	C_max
		See section "THE HEADER" (above) for description.

	[Rload]		r
		See section "THE HEADER" (above) for description.

	[Sim time]	t
		See section "THE HEADER" (above) for description.

	[Derate VI]	x
		See section "THE HEADER" (above) for description.

	[Derate ramp]	y
		See section "THE HEADER" (above) for description.


THE DIFFERENTIAL PIN LIST

	This section contains the differential pin list information, as
	described in the IBIS v2.1 specification.  Note that s2ibis2
	does no processing on this information; it merely stores it an
	writes it to the output file.

	The differential pin list begins with the [Diff pin] keyword:

	[Diff pin]

		Optional.
		Default: none.

		Begins the differential pin list section.

	This keyword is followed by lines describing the differential
	pin relationships.  Each line may contain either four or six
	columns.  The acceptable formats are:

	pin_name   inv_pin   vdiff   tdelay_typ

	and

	pin_name   inv_pin   vdiff   tdelay_typ   tdelay_min   tdelay_max

	These parameters are fully described in the IBIS v2.1
	specification.


THE PIN MAPPING

	The pin mapping describes which power and ground buses are
	connected to each pin's driver and receiver.  This information
	is used in the Spice simulations, if it is supplied.

	The pin mapping begins with the [Pin map] keyword:

	[Pin map]

		Optional.
		Default: none.

		Begins the pin mapping section.

	The keyword is followed by lines describing the pin mapping.
	Each line may contain either three or five columns.  Acceptable
	formats are:

	pin_name   pullup_bus   pulldown_bus

	and

	pin_name   pullup_bus   pulldown_bus   powerclamp_bus gndclamp_bus

	These parameters are fully described in the IBIS v2.1
	specification.


THE PIN LIST

	This section describes which driver/receiver models connect to
	which pins, and the correspondence of input pins with output
	pins.

	The pin list begins with the [Pin] keyword:

	[Pin]

		Required.

		Begins the pin list.

	The keyword is followed by lines which describe the pin list.
	There are six valid formats for each pin information set:

	pin_name  spice_node  signal_name  model_name

	pin_name  spice_node  signal_name  model_name  R_pin  L_pin  C_pin

		These two formats are used for a pin with no input or
		enable, i.e. an input pin, enable pin, power pin or
		ground pin.  Note that R_pin, L_pin and C_pin override
		the R_pkg, L_pkg and C_pkg specifications.

	pin_name  spice_node  signal_name  model_name
	-> input_pin

	pin_name  spice_node  signal_name  model_name  R_pin  L_pin  C_pin
	-> input_pin

		These two formats are used for a pin with an input pin,
		but no enable pin. i.e. an output-only pin.  Note that
		the input_pin_name must match a pin in the pin list.

	pin_name  spice_node  signal_name  model_name
	-> input_pin  enable_pin

	pin_name  spice_node  signal_name  model_name  R_pin  L_pin  C_pin
	-> input_pin  enable_pin

		These two formats are used for a pin with both an input
		pin and an enable pin, i.e. a tristate or I/O pin.  Note
		that both the input_pin_name and enable_pin_name must
		match pins in the pin list.

	Descriptions for each column are given below:

	pin_name:	Name of the pin.  Must be 5 characters or less.
	spice_node:	Node name in the spice file which corresponds to
			this pin.
	signal_name:	Name of the signal associated with this pin.
	model_name:	Name of the driver/receiver/terminator model
			associated with this pin.  The model name must
			match one described by the [Model] keyword (see
			below), unless the model name is one of POWER,
			GND or NC.
	R_pin:		Parasitic pin resistance.  Overrides the R_pkg
			value if defined.
	L_pin:		Parasitic pin inductance.  Overrides the L_pkg
			value if defined.
	C_pin:		Parasitic pin capacitance.  Overrides the C_pkg
			value if defined.
	input_pin:	Name of the pin which supplies the input signal
			to the current pin.  Must match the name of
			another pin in the pin list.  This name is used
			in the Spice simulations to determine where to
			apply the input stimulus.
	enable_pin:	Name of the pin which enables the current pin.
			Must match the name of another pin in the pin
			list.  This name is used in the Spice
			simulations to determine where to apply the
			enable signal.


THE MODEL SPECIFICATION

	The model specification is used to describe a model and its
	attributes.  There must be a model specification for each model
	specified in the pin list, with the exception of the reserved
	model names POWER, GND and NC.

	Each model specification begins with the [Model] keyword:

	[Model]		name

		name = model name

		Required.
		
		Begins a model specification.  The model name may not
		contain spaces, and will be truncated to 20 characters.

	The [Model] keyword may be followed by these commands:

	[Model type]	type

		type =  Input, Output, I/O, 3-State, Open_drain,
			I/O_open_drain, Open_sink, I/O_open_sink,
			Open_source, I/O_open_source, Input_ECL,
			Output_ECL, I/O_ECL or Terminator

		Required.

		Specifies the model type.

	[Polarity]	polarity

		polarity = Inverting or Non-Inverting

		Optional.
		Default: Non-Inverting.

		Defines the model polarity.

	[Enable]	enable

		enable = Active-High or Active-Low

		Optional.
		Default: Active-High.

		Defines how the model is enabled.

	[Vinl]		v

		v = low input threshold voltage

		Optional.
		Default: 0.8V for non-ECL, -1.475V for ECL

		Defines the low input threshold voltage.

	[Vinh]		v

		v = high input threshold voltage

		Optional.
		Default: 2.0V for non-ECL, -1.165V for ECL

		Defines the high input threshold voltage.

	[Vmeas]		v

		v = reference voltage level

		Optional.
		Default: none

		Defines the reference voltage level for board-level
		timing simulation.

	[Cref]		c

		c = capacitive load for timing analysis

		Optional.
		Default: none

		Defines the capacitive load used when specifying the
		propagation delay or output switching time.

	[Rref]		r

		r = resistive load for timing analysis

		Optional.
		Default: none

		Defines the resistive load used when specifying the
		propagation delay or output switching time.

	[Vref]		v

		v = load voltage for timing analysis

		Optional.
		Default: none

		Defines the load voltage used when specifying the
		propagation delay or output switching time.

	[Rgnd]		R_typ   R_min   R_max

		R_typ = terminator ground resistance for TYP curves 
		R_min = terminator ground resistance for MIN curves 
		R_max = terminator ground resistance for MAX curves 

		Optional.
		Default: none.

		Defines the terminator ground resistance.  Only valid
		for models of type Terminator.

	[Rpower]	R_typ   R_min   R_max

		R_typ = terminator power resistance for TYP curves 
		R_min = terminator power resistance for MIN curves 
		R_max = terminator power resistance for MAX curves 

		Optional.
		Default: none.

		Defines the terminator power resistance.  Only valid
		for models of type Terminator.

	[Rac]		R_typ   R_min   R_max

		R_typ = terminator RC resistance for TYP curves 
		R_min = terminator RC resistance for MIN curves 
		R_max = terminator RC resistance for MAX curves 

		Optional.
		Default: none.

		Defines the terminator RC resistance.  Only valid
		for models of type Terminator.

	[Cac]		C_typ   C_min   C_max

		C_typ = terminator RC capacitance for TYP curves 
		C_min = terminator RC capacitance for MIN curves 
		C_max = terminator RC capacitance for MAX curves 

		Optional.
		Default: none.

		Defines the terminator RC capacitance.  Only valid
		for models of type Terminator.

	[Model file]	F_typ	F_min	F_max

		F_typ = filename for model file for TYP curves
		F_min = filename for model file for MIN curves
		F_max = filename for model file for MAX curves

		Optional.
		Default: none.

		Specifies model files to be used for Spice simulations.
		Note that the model files may include any valid Spice
		constructs--s2ibis2 simply copies the named file into
		the Spice input file before calling Spice.

	[Rising waveform]  R_f  V_f  V_f_min  V_f_max  L_f  C_f  R_d  C_d  L_d
	[Falling waveform] R_f  V_f  V_f_min  V_f_max  L_f  C_f  R_d  C_d  L_d

		R_f =     test fixture resistance
		V_f =     test fixture load voltage
		V_f_min = test fixture load voltage for MIN curve
		V_f_max = test fixture load voltage for MAX curve
		L_f =     test fixture inductance
		C_f =     test fixture capacitance
		R_d =     package parasitic resistance
		L_d =     package parasitic inductance
		C_d =     package parasitic capacitance

		Optional.
		Default: none.

		These keywords specify that s2ibis2 is to generate a
		rising or falling waveform using the parameters listed.
		Note that _all_ columns must be filled, although only
		R_f and V_f must be specified.  Please use the reserved
		word NA to fill a column whose value you do not wish to
		specify.  You may have up to 100 rising waveforms and
		100 falling waveforms per model.

	[Temperature range]	T_typ	T_min	T_max
		See section "THE HEADER" (above) for description.

	[Voltage range]		V_typ	V_min	V_max
		See section "THE HEADER" (above) for description.

	[Pullup reference]	V_typ	V_min	V_max
		See section "THE HEADER" (above) for description.

	[Pulldown reference]	V_typ	V_min	V_max
		See section "THE HEADER" (above) for description.

	[POWER clamp reference]	V_typ	V_min	V_max
		See section "THE HEADER" (above) for description.

	[GND clamp reference]	V_typ	V_min	V_max
		See section "THE HEADER" (above) for description.

	[R_pkg]		r
		See section "THE HEADER" (above) for description.

	[L_pkg]		l
		See section "THE HEADER" (above) for description.

	[C_pkg]		c
		See section "THE HEADER" (above) for description.

	[C_comp]	C_typ	C_min	C_max
		See section "THE HEADER" (above) for description.

	[Rload]		r
		See section "THE HEADER" (above) for description.

	[Sim time]	t
		See section "THE HEADER" (above) for description.

	[Derate VI]	x
		See section "THE HEADER" (above) for description.

	[Derate ramp]	y
		See section "THE HEADER" (above) for description.
