-------------------------------------------------------------------------------
File Name:	Overview_and_Intro.txt
Revision:	v2.1
Description: 	Gives an overview and introduces in detail the 
		Cadence IBIS AMI Evaluation Toolkit.
Author:		Ambrish Varma
(c) Cadence Design Systems, Inc.
-------------------------------------------------------------------------------

CONTENTS
1. Introduction
2. Quick Start
3. Files Description
4. Model Run Options
5. View Results and Data
6. Help and Contacts


INTRODUCTION
------------
This toolkit was created to aid the model developer (IP Vendor) to quickly build, compile 
and test Algorithmic Modeling Interface (AMI) models. These models are in the form of 
a Shared Object (SO) library that can be plugged in an EDA tool. These compiled models
encapsulated signal processing functions that are used to encode (TX) and decode (RX) analog
signals so that they can travel long distance on the PCB or backplane (channel). 

Please note that all instructions are valid for LINUX (Red Hat Linux 3.2.3-53) and Windows XP only. 
The C programs are compiled using gcc version 3.2.3 20030502 (Linux) and MS Visual Studio .NET 2003 (Windows).

Users of this toolkit are expected to have gone through the introductory material for 
Algorithmic modeling that is available on IBIS website. A good starting point is the 
introduction to the algorithmic modeling presented by IBIS ATM subcommittee to IBIS 
Open Forum on August 24th. The pdf for that presentation can be found at - 
http://www.eda.org/ibis/docs/AMI_BIRD_Intro_082407_v7.pdf 

Links to additional material on Algorithmic modeling is listed in the Help and Contacts section below. 

QUICK START
------------

To run the model present in the /MODELS dir using Cadence Tester Program:
(for Linux)
	%CDNS_AMI_TESTER  <AMI_Model.dll>

(for Windows)
	%CDNS_AMI_TESTER.exe  <AMI_Model.dll>

	where:

	<AMI_Model.dll> is the name of the AMI model.
	-For Linux, providing the *FULL* path might be required for proper functioning.
	-The control file, ibisamictrl.txt can be present in the directory containing
	 the model (AMI_Model.dll). Alternatively, the control file can be located where 
	 the test is intended to be run with proper pointers to the required files. All 
	 the output from the TESTER will be stored in the same directory as the control file. 
	 The contents of the ibisamictrl.txt file are described in the next section.
	-The model also requires a seperate file containing the parameters for the model.
	 This file needs to be with an extension .ami and should have the same name as
	 the model (AMI_Model.ami). The parameter file (.ami) is also discussed in the
	 next section.


To modify the data rate, change the 'data_rate' parameter in the control (ibisamictrl.txt) file.


FILES DESCRIPTION
------------------

a) Shared Object (SO) Compiled Executable Model (AMI_Model.dll)
   This is the model itself. 
   
   To Compile the SO executable model in Linux:

	a) gcc -c IBIS_AMI_RX.c
	b) gcc -shared -o IBIS_AMI_RX.dll IBIS_AMI_RX.o

  For Windows, use the project file in the /src directory to open the project in Visual Studio .NET 2003
   
b) Model Parameter File (AMI_Model.ami)
   This is the model parameter file. it contains the values of the parameters that the
   model accepts. For the example provided below, the model accepts 2
	parameters, fwd and bwd. The AMI_Model.ami is in tree format as shown here:
	
	(amictfparams
	(fwd -0.169324 1.40308 0.330246 )
	(bwd -0.738358 -0.293473 -0.0691206 -0.0703122 -0.0586222 )
	)
   The model parameter file must be of the same name as the dll with a '.ami' file extension and must 
   be located in the same directory as the (.dll) model.

c) Control File	 (ibisamictrl.txt)
   This is the file that contains all the control parameters that the EDA tool uses. 
   If there is no control file in the directory from where the test is run,    
   default values for all the control options will be used.
   The control file must be located in the directory where the test is intended to run. 
   All the output files will be stored in this directory as well. 
   The ibisamictrl.txt file looks like this:

       (ibisamictrl
	(data_rate 5e9)
	(stimulus_bits_cnt 5000) ; no of bits to be simulated 
	(imp_file ibisimp_10g_32.txt) ; if this file is not in the same directory, correct path needs to be included 
	; outputfiles
	(stim_file stimin.txt)
	(wave_out_file waveout.txt)
	(wave_in_file wavein.txt)
	;(bits_file bits_file.txt) 				;OPTIONAL
	;(dll_name /home/../IBIS_AMI_RX.dll)			;OPTIONAL
	;(dll_parameter_file_name /home/../IBIS_AMI_RX.ami)	;OPTIONAL
	; output control
	(waveform_start_time 120e-9) ; output the waveform after 120ns
       )

   Where
      data_rate:		The data rate at which the AMI model is to be simulated.
           		      	Data Rate is mentioned in exponential form (for ex, 6 Gbps = 6e9)
           		      	Default: 6.25e9

      stimulus_bits_cnt:	Number of bits in this simulation run. If the
			        stimulus_bits_cnt is less than 1000, the TESTER runs a 1000
				bits simulation.
			      	Default: 5000

      imp_file:			The impulse response file. This file should have 2 columns, 
      				the first should be time, the second should be voltage.
			      	Default: ibisimp_10g_32.txt

      bits_file:		Bits file provided by the user. If no bits file is provided, 
      				the tester will	generate a random bitstream.


      stim_file:		Wavefile going in. The waveform is a generated by the TESTER program 
      				using either the bits_file provided by the user, or if not, random 
				bits generated by the TESTER.

      wave_in_file:		Wavefile going in the Getwave call of the AMI model.
			      	Default: wavein.txt


      wave_out_file:		Wavefile coming out of the Getwave call of the AMI model.
			      	Default: waveout.txt


      waveform_start_time:	Initial time that the tester ignores in the waveform.
			      	Default: 120e-9
      			
     dll_name 			Name of the Shared Object Library (dll). If using Linux,
     				complete path may be required. putting dll_name in the
				ibisamictrl.txt file is optional. dll_name can also be supplied as
				an argument to the TESTER.
				
     dll_parameter_file_name	Name of the Parameter file that contains the values of the 
     				parameters for the Shared Object (dll). This is required if the
				dll_name is used in the ibisamictrl.txt. If the dll_name is
				supplied as an argument to the TESTER, the parameter file name is
				not required in the ibisamictrl.txt file.

MODEL RUN OPTIONS
------------------
The user can run the AMI model with the provided TESTER in the following ways:

a) For Linux:
	%CDNS_AMI_TESTER  <AMI_Model.dll>
   
	OR

  For Windows:  
  %CDNS_AMI_TESTER.exe  <AMI_Model.dll>

   The ibisamictrl.txt file should be in the directory from where the test is run. If there 
   is an AMI_Model.ami file, the parameters are read from it, otherwise, the default
   parameters from the model are used.


b) %CDNS_AMI_TESTER or %CDNS_AMI_TESTER.exe for Windows

   
   The dll and the parameter file names can be hardcoded in the ibisamictrl.txt file 
   itself. The user does not have to type the dll name as an argument to the TESTER. 
   The hardcoded dll has a precendence over the argument to the TESTER on the command line.

VIEW RESULTS AND DATA
----------------------
After a successful run of the TESTER, the following files will be generated.

stimin.txt and stimin.sim 
impin.txt and impin.sim
impout.txt and impout.sim
wavein.txt and wavein.sim
waveout.txt and waveout.sim and 
clk.txt and clk.sim

The output waveform data from the TESTER are both in .txt and .sim format.

The .sim files can be viewed in Cadence Sigwave program. To open .sim file with Cadence SigWave,
use File - Open for first one, then to overlay use File - Import, point to the sigWave file.
The .txt files can be formatted to be viewed in any spreadsheet program.


HELP AND CONTACTS
-----------------
This toolkit is provided 'AS IS' (Please read the Cadence Toolkit License.txt for full license
information) . However, any difficulty in running the toolkit or 
supporting files, bugs or issues should be reported to Cadence so that newer versions 
are error and bug free. The email address to report is ambrishv@cadence.com .

We have also established the ibis-ami-toolkit@freelists.org group for discussions 
about this and other toolkits. The ibis-ami-toolkit mailer can be joined by sending an email 
with "subscribe" in the subject line to ibis-ami-toolkit-subscribe@freelists.org .  

You can also join the discussion group through the following URL:
http://www.freelists.org/list/ibis-ami-toolkit.

For more background information on Algorithmic Modeling, you can look at the work archive for the IBIS ATM subcommittee at http://www.vhdl.org/pub/ibis/macromodel_wip/

--------------------
Ambrish Varma
ambrishv@cadence.com
