IBIS-AMI Evaluation Toolkit - Signal Integrity Software (SiSoft)
----------------------------------------------------------------


Table of Contents
-----------------
Introduction
Toolkit contents
Quick Start
   Running a simulation
   Simulation results
   Plotting the impulse response output
   plotting waveform data output
Using your own data
   Channel impulse response
   PRBS file format
   Modifying TX equalization settings
Documentation
Model source files
Compiler options and versions
Technical Support
Additional information



Introduction
------------
IBIS Algorithmic Modeling Interface (AMI) models provide a standard mechanism for modeling
transmit / receive equalization and clock recovery algorithms for SerDes devices.  The IBIS-AMI
standard allows a serial channel to be "characterized" using circuit simulation techniques; that
channel characterization is then combined with signal processing techniques and IBIS-AMI models 
to predict the link's behavior over millions of bits of data.  IBIS-AMI models represent 
equalization and clock recovery algorithms using executable code - the use of a "black box" 
technique permits fast modeling of device behavior and also helps protect semiconductor vendor
IP.

This toolkit contains a sample IBIS-AMI 4-tap transmitter model in both binary and executable
form along with the IBIS_AMI_test utility.  IBIS_AMI_Test allows IBIS-AMI models to be run as
standalone executables from the O/S command line.  This toolkit also includes a random stimulus
generator, sample data and batch jobs - everything you need to demonstrate the speed and flexibility 
these models have to offer.

PLEASE NOTE that the primary purpose of IBIS_AMI_test is to provide a reference execution 
environment for testing IBIS-AMI model compatibility with the published standard.  IBIS_AMI_test
uses the comma separated value (.csv) format for model input and output data.  This data can loaded 
directly into SiSoft's waveform viewer (SiViewer) or plotted in any one of several spreadsheet
programs.  Time-domain simulations with these models generate large amounts of data, and the plotting
capabilities of most speadsheet programs are limited.  We expect that most people will use these
models in conjunction with a commercial EDA waveform viewer - either by loading data directly into
SiSoft's SiViewer, or using another tool that is capable of importing .csv format data.    


Changes from version 2.10
-------------------------
The AMI parsing utility ami2csv would pass the "Format" keyword into the .csv file used to drive
IBIS_ATM_TEST if the keyword was present in the .ami file.  This new version of ami2csv corrects
that problem.  The sample .ami file has been updated to include the "Format" keyword as defined
in the IBIS 5.0 specification and to fix a problem with a missing closing parenthesis.

A sample IBIS (.ibs) file is now provided in the src/ directory, to serve as an example of how the
linkage to the .dll and .ami files is declared from within the IBIS file.  Please note that 
IBIS_ATM_TEST does not make use of this file, users must provide their own impulse response data
in the .csv file passed read by IBIS_ATM_TEST. 



Changes from version 2.03
-------------------------
The stimulus generator (IBIS_ATM_prbs) and reference algorithmic model (IBIS_ATM_Tx) were updated to
be consistent with BIRD 107.2.  In the 2.03 version of the toolkit, IBIS_ATM_prbs produced a "digital
waveform" that was passed into IBIS_ATM_test and the IBIS_AMI_Tx model.  BIRD 107.2 defines the input
to TX AMI_Getwave as the channel inpulse response convolved with the input bitstream (an "analog
waveform").  The versions of IBIS_ATM_prbs and the IBIS_ATM_Tx model in this toolkit were modified
accordingly.  

This has the side benefit of making it easier to test an RX model standalone with this toolkit.  The
RX AMI_Getwave call always required an analog waveform as its input.  Since IBIS_ATM_prbs generated
a digital waveform in the 2.03 toolkit, it was necessary to chain a TX model with an RX model to
test RX AMI_Getwave functionality.  This new version of the toolkit allows RX models to be tested
standalone.

The .ami file associated with the Tx model has been updated to reflect the new Reserved Parameter
"Use_Init_Output" defined in BIRD 107.2.  The value of the parameter for this model is set to "False"
because the AMI_Init and AMI_Getwave calls each represent the full equalization behavior of the model.

New executable versions of IBIS_ATM_Test are also included in the 2.10 toolkit.  The changes resulted
from code cleanup that should not affect functionality.



Changes from version 2.02
-------------------------
Some of the time values for the impulse response contained in "tx_impulse_no_eq.csv" and "tx_impulse_eq.csv"
were duplicated.  This had no effect on simulation results, as IBIS_AMI_Test uses the values for
bit_time and sample_interval to compute the time value for each impulse response waveform point ("time" 
data is present in the input file only to simplify plotting the initial impulse response).  Be advised 
that using Excel to edit the .csv control file for IBIS_AMI_Test will tend to cause these repeated 
time points, as Excel writes out scientific numbers with two decimal places of precision by default.  


Changes from Version 2.01
-------------------------
IBIS_AMI_Test no longer assumes models will pass back parameter data in the output stream.  This
has no impact on functionality other than IBIS_AMI_Test now works correctly with models that return
only waveform data.


Changes from version 2.0
------------------------
The linux batch files "run_eq" and "run_no_eq" were modifed to make them run properly under linux.
File permissions and executable names were also modified to make the linux version work properly.


Changes from Version 1.0
------------------------
After version 1.0 was released on August 30, 2007, several detailed changes were made to the
IBIS AMI specification and several usability concerns were identified. Release 2.0 brings the
evaluation tool kit up to date with the IBIS AMI BIRD as submitted to the IBIS Open Forum on
October 12, 2007, and includes new capabilities and features which make the tool kit easier to
use.  The specific changes were:

* The parameter tree parser now supports enclosing string type parameter values in double quotes.

* The format and content of the IBIS_AMI_Tx.ami file reflects the latest changes, including the
  definition of the Tap type.

* A new utility, ami2csv, has been added to convert *.ami files into a more human-readable format.
  This utility outputs a text file of the *.ami file contents in outline form and a CSV file
  suitable for incorporation into IBIS_AMI_test input files.

* A new program, IBIS_AMI_prbs, has been added to generate LFSR data patterns with register lengths 
  of 7, 15, or 22 bits.  Documentation for this utility can be found in the doc/ subdirectory.

* IBIS_AMI_test now outputs a "time" column to go along with the waveform output column, making
  it easier to interpret and plot the results.

* The parameter input format to IBIS_AMI_test has been changed from the parameter tree syntax
  which is native to the IBIS AMI API to an outline format which makes it easier for users to
  read and change input and output parameters.

* The parameter tree parser was restructured into separate lexer and parser state machine functions.
  This makes it easier for model writers or software developers to write multiple special purpose
  parsers because these functions can be re-used and only the action code needs to be written.


Toolkit contents
----------------
/:
	license.txt		- the terms under which this toolkit is distributed
	readme.txt		- this file
	version.txt		- version number of the kit

/windows:
	ami2csv.exe		- Windows version of utility which converts AMI files
				  to outline format
	cleanup.bat 		- batch job that deletes simulation results
	run_no_eq.bat		- runs a 100K bit simulation without TX equalization
	run_eq.bat  		- runs a 100K bit simulation with TX equalization
	IBIS_AMI_test.exe	- Windows version of utility program that allows IBIS-AMI models
				  to be run from the command line
	IBIS_AMI_Tx.dll		- Sample IBIS-AMI Tx model executable
	IBIS_AMI_prbs.exe	- Windows version of utility program which generates LFSR data
				  patterns suitable for input to IBIS_AMI_test.exe
	tx_impulse_no_eq.csv	- Sample channel impulse response with model parameters set for 
				  no TX equalization
	tx_impulse_eq.csv	- Sample channel impulse response with model parameters set for 
				  TX equalization 


/linux:
	ami2csv			- Linux version of ustility which converts AMI files
				  to outline format
	cleanup			- Linux script that deletes simulation results
	run_no_eq		- Linux script that runs a 100K bit simulation without TX equalization
	run_eq			- Linux script that runs a 100K bit simulation with TX equalization
	IBIS_AMI_test		- Linux version of utility program that allows IBIS-AMI models
				  to be run from the command line
	libIBIS_AMI_Tx.so	- Linux shared object library containing the IBIS_AMI_Tx model
	IBIS_AMI_prbs		- Linux version of utility program which generates LFSR data
				  patterns suitable for input to IBIS_AMI_test
	tx_impulse_no_eq.csv	- Sample channel impulse response with model parameters set for 
				  no TX equalization
	tx_impulse_eq.csv	- Sample channel impulse response with model parameters set for 
				  TX equalization
 

/doc:
	ami2csv.doc		- documentation for the ami2csv utility
	IBIS_AMI_prbs.doc	- documentation for the IBIS_AMI_prbs data generator utility
	IBIS_AMI_tx.doc		- documentation for the TX model
	IBIS_AMI_test.doc	- documentation for the IBIS_AMI_test utility
	IBIS_AMI_Validation.pdf - presentation on this toolkit to the IBIS-ATM task group

/src:
	IBIS_AMI_Tx.ami		- AMI parameter file for IBIS_AMI_Tx executable
	IBIS_AMI_Tx.ami.csv	- Extract from AMI file for incorporation into IBIS_AMI_test
				  input file
	IBIS_AMI_Tx.ami.txt	- Extract from AMI file containing outline list of file contents
	IBIS_AMI_Tx.c		- Source code for the IBIS-AMI Tx model
	IBIS_AMI_Tx.h		- Header file for the IBIS-AMI Tx model
	IBIS_AMI_tree.c		- Parameter tree parser source code for IBIS-AMI models
	IBIS_AMI_tree.h		- Header file for the parser
	IBIS_AMI.h		- Header file for both the model and the parser
	sisoft_tx.ibs		- Sample IBIS 5.0 file
	make_IBIS_AMI_Tx,	- Linux compile job and makefile
	makefile	
	IBIS_AMI_Tx.zip		- Zip file containing the Microsoft Visual Studio 2005 project
				  which builds IBIS_AMI_Tx.dll	 




Quick Start - Running Simulation
--------------------------------
The batch job "run_no_eq.bat" will run both an impulse response ("init") and a 100K bit 
waveform ("getwave") analysis with no equalization applied by the transmitter.  This batch job 
uses the channel impulse response and model settings found in the "tx_impulse_no_eq.csv" file.  
Because no TX equalization is applied, the output impulse response is the same as the input 
impulse response - except the output response has been shifted by 1 bit time.

The batch job "run_eq.bat" will run both an impulse response ("init") and a 100K bit waveform 
("getwave") analysis with equalization applied by the transmitter.  The output impulse response 
is therefore different from the impulse response.

The batch job "cleanup.bat" removes any files generated during the analysis process, leaving 
only the simulation source files.  Each of the simulation batch jobs calls "cleanup.bat" before 
analysis commences.


Quick Start - Simulation Results Files
--------------------------------------
No matter which analysis job is run, the following files are created:

	tx_impulse.csv		- original channel impulse response
	impulse_rx_pad.csv	- impulse response at receiver pad
	waveform_rx_pad.csv	- waveform at receiver pad

Results files are created in a comma separated value (.csv) format that can loaded directly into
SiViewer and is compatible with a variety of tools.  Note that Microsoft Excel 2003 has a 64K row 
limit for .csv data; waveform data created with this toolkit will be truncated if loaded into Excel 
2003 directly.


Quick Start - Plotting the impulse response output
--------------------------------------------------
The output file impulse_rx_pad.csv contains header information, followed by two columns of output
data.  The first column is time in seconds, while the second column is the output impulse 
response in volts/second.  Note that an impulse response is the first derivative of a circuit's 
step response, and because outputs switch in well under a nanosecond, the magnitude of the impulse
response will be quite high - values of 1E9 are not uncommon.  

If you don't have access to a suitable EDA waveform display tool, the two columns of the impulse response 
can be plotted directly in Microsoft Excel.  We recommend plotting results as a scatter chart, using smoothed 
lines without markers.


Quick Start - Plotting the waveform data output
-----------------------------------------------
The waveform_rx_pad.csv file contains header information, followed by three columns of data - the first 
column is the sample time. The second column is the model's output voltage at the pre-defined sampling
points.  If you don't have access to a suitable EDA waveform display tool, this file can be plotted in 
Excel using a scatter plot to chart the data.  Please note that waveform output files will generally have
more data points than Excel can read in - 800,000 samples in the files produced by this example of 100,000 
bits and 8 samples/bit, versus Excel's limit of 65,636 rows in a worksheet.  

SiSoft's SiViewer is available as a standalone product, along with other tools that are more suitable for 
processing large amounts of waveform data.  For more information, please visit www.sisoft.com or contact 
SiSoft at ibis-ami@sisoft.com.

The third column of data in waveform_rx_pad.csv contains clock "tick" output data.  This feature is
usually associated with SerDes Rx models, which detect the zero-crossing points in the input
waveform to reconstruct a clock reference used to recover the incoming data.  The clock "tick" 
column contains a list of times (in seconds) where the waveform crosses the 0V threshold.  Note that
this column simply contains a list of zero-crossing times, and the data in the second column is not
time-correlated to the data in the first column.  This is another optimization in how AMI models
communicate with EDA tools - while the format is not necessarily intuitive, it minimizes the data that
must be passed back between the simulator and model to enhance performance.  EDA platforms normally
accumulate, reformat and present this data in other ways, so the user does not see the "raw" output
data as returned from the model.  In this particular case, the clock "tick" data can be ignored - 
this feature is present in the sample Tx model for EDA platform compatibility test purposes.


Using your own data - Channel impulse response
----------------------------------------------
The impulse response contained in the sample files "tx_impulse_no_eq.csv" and "tx_impulse_eq.csv" 
can be replaced with the impulse response of another channel you wish to analyze.  Please note that 
this data is supplied in a pre-defined format with a fixed number of samples per bit time.  The 
statements

	* sample_interval <value>
	* bit_time <value>

tell the IBIS_AMI_test utility the design's bit time and the delay between samples.  Your data MUST have
an integral number of samples per bit, equal to <bit_time>/<sample_interval>.  Note that these values are 
specified in seconds.  When supplying your own channel impulse response data, be sure to carefully follow 
the format provided for the impulse response, or the analysis will not work properly.


Using your own data - PRBS file format
--------------------------------------
The utility IBIS_AMI_prbs reads control statements in the input file and generates a random stimulus sequence
in the format required by IBIS_AMI_test.  In the examples provided with this kit, the control statements are
found in the same input file that contains the channel's impulse response (tx_impulse_no_eq.csv or 
tx_impulse_eq.csv).  In these cases, the control statements for the stimulus generator are:

*	register_length	22	
*	sample_interval	2.50E-11	
*	bit_time	2.00E-10	
*	stop_time	2.00E-05

This tells the stimulus generator to generate 100,000 bits of random data.  The bit time is 200ps (5 Gbps) with 
a 25ps sample internal (8 samples/bit).  Random data is generated using a 22 bit LFSR.

IBIS_ATM_test also uses the statements

*	sample_interval	2.50E-11	
*	bit_time	2.00E-10

To tell the algorithmic model the bit times and the number of samples to be provided/generated per bit.



Using your own data - Modifying TX equalization settings
--------------------------------------------------------
The input file used by IBIS_AMI_test contains both the model settings and the channel impulse response
to be used for analysis.  The model settings in the file "tx_impulse_no_eq.csv" are:


		IBIS_AMI_Tx
			tap_filter
				-1 0
				0  1
				1  0
				2  0
			tx_swing 1.0

These statements set the main cursor EQ tap to 1, while all other cursor taps are set to 0.  The signal is 
passed through unscaled (i.e. multiplied by 1).


The model settings in the file "tx_impulse_eq.csv" are:

		IBIS_AMI_Tx
			tap_filter
				-1 -0.15
				0   0.7
				1  -0.125
				2  -0.025
			tx_swing 0.8

This statement sets the precursor tap to -0.15, the main tap to 0.7 and the first and second post-cursor 
taps to -0.125 and -0.025, respectively.  The signal is scaled by 80%.

You can edit the AMI_dll_parameters statement to reflect your own tap and scale settings.


Documentation
-------------
The doc/ directory contains more detailed documentation on the arguments and data formats used by the 
IBIS_AMI_Tx model and the different executables (IBIS_AMI_test / IBIS_AMI_prbs).


Model source files
------------------
The src/ directory contains the source, header and makefile for the IBIS_AMI_Tx model.


Compiler options and versions
-----------------------------
The IBIS_AMI_test and model executables in this kit have been compiled under the following conditions:

Windows: (additional info in src/IBIS_AMI_Tx.zip)

	Microsoft Visual Studio
	Version 8.0.50727.762 (SP 050727-7600)

Linux: (additional info in src/make_IBIS_AMI_Tx.txt)

	Configured with: ../configure --enable-threads=posix --prefix=/usr --with-local-prefix=/usr/local 
                 --infodir=/usr/share/info --mandir=/usr/share/man --libdir=/usr/lib --enable-languages=c,c++,f77,objc,java,ada 
                 --disable-checking --enable-libgcj --with-gxx-include-dir=/usr/include/g++ --with-slibdir=/lib --with-system-zlib 
                 --enable-shared --enable-__cxa_atexit i586-suse-linux
	Thread model: posix
	gcc version 3.3.1 (SuSE Linux)


Technical Support
-----------------
Since this is supplied as a free toolkit, no formal technical support is provided.  We have established
an email discussion group at:

ibis-ami-toolkit@freelists.org 

so that users can share their experiences with this toolkit.  We will participate in these discussions as possible, and 
hope to gain insight that will allow us to make improvements to this toolkit.  To join this discussion group, send an email 
with "subscribe" in the subject line to ibis-ami-toolkit-request@freelists.org.  You can also join the discussion group through 
the following URL:

http://www.freelists.org/list/ibis-ami-toolkit

Future releases of this toolkit will be announced on the ibis-ami-toolkit mailer.


Additional information
----------------------
For more information on this kit, other IBIS AMI models and other IBIS-AMI data management tools, please contact:

	Signal Integrity Software, Inc. (SiSoft)
	6 Clock Tower Place, Suite 250
	Maynard, MA     01754
	(978) 461-0449 
	www.sisoft.com
	email: ibis-ami@sisoft.com.
