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 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 all model input and output data, but does not 
really reformat model I/O data other than that.  The IBIS-AMI standard specifies how data is passed
back and forth between an IBIS-AMI model and a host EDA-platform; this interface has been designed 
to eliminate passing of redundant data and optimize performance.  This means that the data consumed
and produced by IBIS-AMI models isn't necessarily intuitive to the new user.  It also means that 
data output from IBIS-AMI models will need to be manipulated before it can be used to produce
a suitable waveform display or eye diagram.  You can either manipulate the data interactively 
(that is, using a tool like Excel) or create your own programs/scripts to reformat the data into a
style suitable for the waveform display tools you commonly use.


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

/windows:
	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 ofutility program that allows IBIS-AMI models
				  to be run from the command line
	IBIS_AMI_Tx.dll		- Sample IBIS-AMI Tx model executable
	prbs22_100K.csv		- Sample 100K bit stimulus input
	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 
        sample_impulse.xls      - sample plotted impulse response data, in Excel format
        sample_waveform.xls     - sample plotted waveform data, in Excel format


/linux:
	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
	prbs22_100K.csv		- Sample 100K bit stimulus input
	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:
	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.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
	make_IBIS_AMI_Tx.txt	- Linux model make file
	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_tx_pad.csv	- waveform at receiver pad

Results files are created in a comma separated value (.csv) format 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.  

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 output file waveform_tx_pad.csv contains data in the model output format defined by the IBIS 
AMI specification.  This is an optimized data format that minimizes the amount of data passed back 
and forth between models and the simulator.  Specifically, the time values associated with output 
voltages are omitted, because the sampling interval is specified as part of the configuration data 
sent to the AMI model.

The waveform_tx_pad.csv file contains header information, followed by two columns of data - the first 
column is the model's output voltage at the pre-defined sampling points.  The easiest way to plot this 
data in Excel is to add a new first column to the spreadsheet, containing the time points as defined by 
the sample_interval declared in the original impulse response .csv file.  In the case of the example 
provided, the bit_time is 200ps (5 Gbps) and there are 8 samples per bit, yielding a sample_interval
of 25ps.  The file sample_waveform.xls shows an example of waveform output after the time column has
been added in, using a scatter plot to chart the data.  Note that only a portion of the output
sequence has been plotted, as Excel's pan/zoom capabilities are limited.  Note also that the output
waveform file has more data points than Excel can read in - 800,000 samples in the provided example of 
100,000 bits and 8 samples/bit, versus Excel's limit of 65,636 rows in a worksheet.  Plotting eye 
diagrams in Excel is difficult at best.

In actual practice, we expect users will post-process the model data output by IBIS_AMI_Test into a 
format suitable for use with a commercial waveform viewer.  SiSoft offers its own commercial 
(i.e., not free) 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 second column of data in waveform_tx_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 file prbs22_100K.csv a 100,000 bit sequence generated using a 22 bit LFSR.  The data is supplied according 
to the IBIS AMI specification for Tx model waveform input, which calls for a fixed number of samples per bit.
Note that the included example specifies 100,000 bits at 8 samples/bit, yielding 800,000 lines of data.  Note 
also that the input values represent 1V stimulus centered around 0V (i.e. logic 0 = -0.5V, logic 1 = +0.5V). 
The statements before the "wave_in" statement are not needed and are ignored by IBIS_AMI_test - they are
repeated here from the impulse response file for clarity.  As with the raw waveform output data from IBIS AMI 
models, this data format is defined by the standard and is not intuitive - it seems wasteful to repeat the data
input values for each bit time.  The standard is written this way to provide a common interface for both TX and RX 
models.   Please note that in actual EDA tool practice, the user will specify a pattern type and length, and the EDA 
tool will generate the actual data required by the IBIS AMI models.


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:

* AMI_dll_parameters_in	(IBIS_AMI_Tx(tap_filter(tap-1 0.0)(tap0 1.0)(tap1 0.0)(tap2 0.0))(tx_swing 1.0))	
 
The statement above sets the following model parameters

		IBIS_AMI_Tx
			tap_filter
				tap-1 0
				tap0  1
				tap1  0
				tap2  0
			tx_swing 1.0

This statement sets the main cursor EQ tap to 1, while all other cursor taps are set to 0.  The signal is 
passed through unscaled (i.e. multipled by 1).


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

* AMI_dll_parameters_in	(IBIS_AMI_Tx(tap_filter(tap-1 -.15)(tap0 .7)(tap1 -.125)(tap2 -.025))(tx_swing 0.8))

The statement above sets the following model parameters

		IBIS_AMI_Tx
			tap_filter
				tap-1 -0.15
				tap0   0.7
				tap1  -0.125
				tap2  -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 IBIS_AMI_Test executable.


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.
