Usage Guide:

Summary:
The LU generator automatically generate hardware to solve a linear system
of equations. The linear system is expressed as a dense matrix and LU
factorization is performed on it. The dense matrix is stored in off-chip memory.

The generator reads parameters from a file to create a customized hardware
that is portable and scalable for any FPGA.

For more detail on the generator and how to execute the hardware can be found
at http://www.eecg.utoronto.ca/~jayar/software/LUgen/

Setup:
1. unzip files
2. compile using Makefile
3. execute program, the program takes one parameter: 
   the filename of a text file containing the parameters
   -  output files created in a subdirectory
   -  project file has to be created manually 
      (.sdc file are created by program)

Parameter file:
Assign the value for a parameter using the following format:
"parameter_name=parameter_value"
The "=" separates the parameter name with its value. Everything after
the parameter_value is ignored. Only one parameter can be assigned a value
per line. If the same parameter is assigned values multiplie times in the 
parameter file, the parameter has the value of the last assign statement. 
The "#" character can be used to add comments to the parameter file. 
Everything after the "#" is ignored.

There are two types of parameters that can be assigned values in the 
parameter file: core and advanced parameters. The core parameters have to 
be assigned a value or the program will return an error. The advanced 
parameters do not have to be assigned a value and default values will be 
set for these parameter if not assigned in the parameter file.

The core parameters are listed below, with the description of the 
parameter in parenthesis:
k              (number of Processing Elements (PE)
		approx resources used per PE:
		single precision - 700 ALMs, 1000 reg, 4 DSP 9x9 mult
		double precision - 1400 ALMs 2200 reg, 10 DSP 9x9 mult)
mdivk          (internal block size in multiple of number of PEs
		aprrox memory bits used: 5*mdivk*k*mdivk*k*precision)
ddrwidth       (ddr2 sdram datawidth)
ddrsizewidth   (ddr2 sdram total address width)
ddrrowwidth    (ddr2 sdram row address width)
ddrburstlen    (ddr2 sdram burst length)
addlat         (output latency of subtraction operator)
multlat        (output latency of multiplier)
divlat         (output latency of divider, multi-clocked)
precision      (number of bits of floating point precision)
DQperDQS       (number of DQ per DQS)
diffDQS        (1 if ddr2 sdram memory controller uses differential DQS; 
                0 otherwise)

The advanced parameters are listed below, with the description of 
the parameter in parenthesis:
Nmax             (maximum problem matrix size)
fifosize         (size of dual-clock FIFOs)
meminputdelay    (number of pipeline registers added to input port 
                  of current/left block)
memoutputdelay   (number of pipeline registers added to output port 
                  of current/left block)
topinputdelay    (number of pipeline registers added to input port 
                  of top block)
topoutputdelay   (number of pipeline registers added to output port 
                  of top block)
name             (name of top module for compute engine)
addname          (name of subtraction operator module)
multname         (name of multiplier module)
divname          (name of divider module)
memcontname      (name of ddr2 sdram memory controller module)

Core library files:
Additional core files are needed for the subtraction operator, multiplier,
divider and off-chip memory controller. The files for each of these cores
are located in a separate directory in the CoreLib directory. They are created
from Altera MegaCore IP and are targeted for the Stratix III FPGAs with ddr2
SDRAM as off-chip memory. The addname, multname, divname and memcontname 
parameters specify the module name for these components as well as the directory
it is in within the CoreLib directory. For example, if the multname parameter 
is assigned "mult", the files for the "mult" module will be located in the 
directory "CoreLib/mult/". The files in the directory specified by these 
parameters are copied into the final output directory. Note, subdirectories 
and its files inside the core library directory will not be copied.

Already generated core files are included in the CoreLib directory under the 
following naming format, which is the defaulted if no value for the parameters
are assigned in the parameter file. There cores are created from Altera MegaCore
IP and targeted for Stratix III. By default, the subtraction operator is named 
"sublatXX", with XX representing the latency of the operator, which is specified 
by parameter addlat. Similarly, the multiplier is named "multlatXX", with XX
representing the multipliler latency specified by parameter multlat. The divname 
is defaulted to "div". The memcontname is defaulted to "ddr2_XXxYY_ZZ" with XX is 
the value of parameter ddrsizewidth, YY is the value of the parameter ddrwidth and
ZZ is the value of DQperDQS. For example, if the ddrsizewidth=24, ddrwidth=48 and 
ZZ=8, the memcontname is defaulted to "ddr2_24x48_8". 

Adding new library files:
The user can create their own core files to be used in the hardware. The files 
should be placed in a directory in the "CoreLib" directory. The directory name should
be the top module name of the core. The corresponding core name parameter to indicate
the location/name of the new core files in the parameter file. For example, if a new 
multiplier is added with a top module called "multnew". The core files for this new 
multiplier should be in "CoreLib/multnew" and the multname parameter should be 
specified as "multnew".

Currently, new core files are needed for the design to be used on FPGAs other than
the Altera Stratix III as the available cores are targeted for that specific FPGA.

Output:
After successfully executing the program, the files for the LU factorization compute 
engine will be created in a directory that has the same name as the top module, which 
is specified by parameter name. By default, the value of the parameter name is "LUXXPEEng",
where XX represent the number of PEs, which is specified in the parameter k. All the
necessary files, including the core library files, will be contained inside the newly
created directory. If no such directory exists, the program will create a new directory; 
however, if a directory with the same name exists, only the files with the same identical
names will be overwritten.

To compile the design, just create a new project and set the "LUXXPEEng.v" as the top level module.