Odin II - Version 1.0 - User's Manual

INSTALL
------------

1. libarchfpga

This library needs to be built for your platform.  The Makefile for
Odin will link the libarchfpga library located in:
../libarchfpga_5 or ../libarchfpga_6

By default Odin II uses libarchfpga_6. To compile it, change directory to 
../libarchfpga_6 and type "make". 

Note: 
- for WIN32 compilation you'll have to edit the ezxml.c files
to "#define WIN32" or not.

2. Odin II

Odin is compiled with a standard Makefile.  For the first time
I would suggest a:
make clean && make

Note: 
- that Odin relies on ctags, bison, and flex.  These details are not 
included in this install and are left to the user. (On linux systems, 
these packages are generally available through your distribution's package 
management system.)
- the default make targets VRP 6.0. For VPR 5.0 you can either
change the Makefile variable "BUILD=" to VPR5 or you can type:
make clean && make BUILD=VPR5

USAGE
-------------

After you build Odin, please run the included verify_microbenchmarks.sh 
script. This will automatically compile, simulate, and verify all of the
included microbenchmark circuits to ensure that Odin is working 
correctly on your system. 

To use Odin II, invoke it from the command line as ./odin_II.exe.
./odin_II.exe -h will give you a list of the possible options. Commonly 
used options are -V to supply a verilog file to compile, -a to supply 
an FPGA arch file to map to, and -o to supply a blif output filename. 

You can specify a configuration file with the -c
option, as it ./odin_II.exe -c config.xml. A config file looks
like the following:
<config>
	<verilog_files>
		<!-- Way of specifying multiple files in a project! -->
		<verilog_file>verilog_file.v</verilog_file>
	</verilog_files>
	<output>
		<!-- These are the output flags for the project -->
		<output_type>blif</output_type>
		<output_path_and_name>./output_file.blif</output_path_and_name>
		<target>
			<!-- This is the target device the output is being built for -->
			<arch_file>fpga_architecture_file.xml</arch_file>
		</target>
	</output>
	<optimizations>
		<!-- This is where the optimization flags go -->
	</optimizations>
	<debug_outputs>
		<!-- Various debug options -->
		<debug_output_path>.</debug_output_path>
		<output_ast_graphs>1</output_ast_graphs>
		<output_netlist_graphs>1</output_netlist_graphs>
	</debug_outputs>
</config>

You may specify multiple verilog files for synthesis. The 
fpga_architecture_file.xml format is specified from VPR. output_ast_graphs set 
to 1 will give you abstract syntax tree graphs which can be viewed using 
GraphViz. The output_netliet_graphs does the same, except it visualizes the
netlist synthesized by Odin II.

The -g x flag will simulate the generated netlist with x clock cycles using 
pseudo-random test vectors. These vectors and the resulting output vectors are
written to "input_vectors" and "output_vectors" respectively. You can supply 
a predefined input vector file by replacing the -g option with the -t option. 
The output vectors can also be verified against a predefined output vector 
file via the -T option. 

A test vector file is as follows:
# Example vector file
intput_1 input_2 output_1 output_2 output_3
# Comment 
0 0XA 1 0XD 1101
-------------

Each line represents a vector. Each value must be specified in binary or hex. 
Comments may be included by placing an # at the start of the line. Blank lines 
are ignored. Values may be separated by non-newline whitespace. (tabs and spaces)
Hex values must be prefixed with 0X. 

Each line in the vector file represents one cycle, or one falling edge and one 
rising edge. Input vectors are read on a falling edge, while output vectors are 
written on a rising edge. 

Hard blocks can be simulated; given a hardblock named "block" in the 
architecture file with an instance of it named "instance" in the verilog file,
write a C method with signature defined in SRC/sim_block.h and compile it with
an output filename of "block+instance.so" in the directory you plan to invoke 
Odin-II from. When compiling the file, you'll need to specify the following 
arguments to the compiler (assuming that you're in the SANBOX directory):
"`cc -I../../libarchfpga_6/include/ -L../../libarchfpga_6 -lvpr_6 -lm --shared -o 
block+instance.so block.c". When compiling against VPR5, adjust the arguments
accordingly. 

If the netlist generated by Odin II contains the definition of a hardblock which
doesn't have a shared object file defined for it in the working directory,
Odin II will not work if you specify it to use the simulator with the -g or -t
options.

Use of static memory within the simulation code necessitates compiling a 
distinct shared object file for each instance of the block you wish to simulate.
The method signature the simulator expects contains only int and int[] 
parameters, leaving the code provided to simulate the hard blokc agnostic of the
internal Odin II data structures. However, a cycle parameter is included to 
provide researchers with the ability to delay results of operations performed by
the simulation code.

DOCUMENTING ODIN II
-------------------

Any new command line options added to Odin II should be fully documented by
the print_usage() function within odin_ii.c before checking in the changes.  

TESTING ODIN II
----------------

The verify_microbenchmarks.sh and verify_regression_tests.sh scripts 
compile and simulate the microbenchmarks and a larger set of benchmark 
circuits. These scripts use simulation results which have been verified 
against ModelSim. 

After you build Odin II, run verify_microbenchmarks.sh to ensure that 
everything is working correctly on your system. Unlike the 
verify_regression_tests.sh script, verify_microbenchmarks.sh also 
simulates the blif output, as well as simulating the verilog with and 
without the architecture file.

Before checking in any changes to Odin II, please run both of these 
scripts to ensure that both of these scripts execute correctly. If there 
is a failure, use ModelSim to verify that the failure is within Odin II 
and not a faulty regression test. The Odin II simulator will produce 
a test.do file containing clock and input vector information for ModelSim. 

When additional circuits are found to agree with ModelSim, they should 
be added to these test sets. When new features are added to Odin II, new 
microbenchmarks should be developed which test those features for 
regression.  Use existing circuits as a template for the addition of 
new circuits. 

USING MODELSIM TO TEST ODIN II
-------------------------------

ModelSim may be installed as part of the Quartus II Web Edition IDE. Load
the Verilog circuit into a new project in ModelSim. Compile the circuit, 
and load the resulting library for simulation. 

Simulate the circuit in Odin II using the -E option to ensure that Odin II
outputs both edges of the clock. You may use random vectors via the -g option, 
or specify your own input vectors using the -t option. When simulation is 
complete, load the resulting test.do file into your ModelSim project and 
execute it. You may now directly compare the vectors in the output_vectors
file with those produced by ModelSim. 

To add the verified vectors and circuit to an existing test set, move the 
verilog file (eg: test_circuit.v) to the test set folder. Next, move the 
input_vectors file to the test set folder, and rename it test_circuit_input. 
Finally, move the output_vectors file to the test set folder and rename 
it test_circuit_output. 

CONTACT
-------------

jamieson dot peter at gmail dot com
ken at unb dot ca
- We will service all requests as timely as possible, but
please explain the problem with enough detail to help.