README.txt

1. Introduction
----------------------
This archive contains the ZUMA FPGA overlay architecture system.
The folders contains a number of components needed to use ZUMA, 
as well as examples and tests.

File structure:
../example 	-- 	Contains a ZUMA preferences file, a sample verilog file, and a script to compile 
../quartus 	-- 	Contains a Quartus project for running the ZUMA system
			to an output bitstream and a generated ZUMA verilog file.
../source	-- 	Contains the code used to generate the ZUMA verilog components and bitstreams
../tests 	-- 	included scripts used to test ZUMA components
../verilog 	-- 	Verilog files used for building a ZUMA system, included platform specific and simulation files

2. Installation:
----------------------
ZUMA scripts is written in Python, and requires a valid Python install to run.
The scripts are tested with Python 2.7.
The VTR tool set must also be installed in order to compile with ZUMA. 
ZUMA does not call VTR directly, but requires files that are generated by VTR.
The variable VTR_DIR is used in scripts to find the VTR install. 
Once VTR is installed, update the file 'toolpaths' in the base directory to reference it.
For a VPR version previous to 7 you need a to activate a dump output. 
For VPR 6 a patch file can be applied to the file 'rr_graph.c' 
in the directory '$VTR_DIR/vpr/SRC/route/', by calling:
'cat (ZUMA dir)/misc/patch.txt (VTR dir)/vpr/SRC/route/rr_graph.c > (VTR dir)/vpr/SRC/route/rr_graph.c' 
The patch enables VPR to dump its routing graph to the file 'rr_graph.echo', 
which is used in the ZUMA CAD tools.
If using a different version, defining CREATE_ECHO_FILES in rr_graph.c will enable this functionality. 

3. Running the Tools:
----------------------
A. Running the Example
Calling the shell file 'compile.sh test.v' will automatically build the ZUMA system verilog, 
and a bitstream hex file, which can be used to compile a ZUMA system. 
By passing other circuit files, and modifying the ZUMA configuration file zuma_config.py, 
custom architectures and bitstreams can be generated.

A constrain of the circuit file is that the head of the model must have the following signature:
verilog-module-name ([clock],reset, [input-name-1, input-name-2 , ... ])
The clock and reset signal must have the given names and position.
The reset is treated as the first input on the fpga.
The declaration of a clock is optional.

B. Generating the ZUMA system
To generate the Verilog architecture that can be compiled to an FPGA, configuration files are generated for the VTR tools, 
which are then run to generate the global routing graph used in the ZUMA architecture.
Calling 'generate_buildfiles.py' will generate the VPR architecture files scripts used during the compilation. 
It takes in two arguments, an input folder and an output folder. The script reads each file in the input folder and 
substitutes the ZUMA parameters for specific keywords. This will generate the architecture file for VPR. 
VPR is then run (any blif file can be used), which outputs the routing graph, as well as the netlist, placement and routing files.
To generate the ZUMA system, calling 'zuma build.py' with the addresses
"python zuma_build.py -graph_file 'rr_graph.echo' -blif_file 'abc_out.blif' -place_file 'place.p' -route_file 'route.r' 
-net_file 'netlist.net' -bit_file 'output.hex' -blif_out_file 'zuma_out.blif' -verilog_file 'ZUMA_custom_generated.v' "
The filenames above are the default filenames used, and do not have to be specified if they are the same. 
The graph, blif, place, route and netlist files are all generated by earlier CAD steps, and are needed to generate the ZUMA 
configuration. 

The 'bit' file is the ZUMA bitstream in hex format, if this parameter is not specified the bitream generation is not performed.
the verilog file is the design file of the complete ZUMA system, that is used with other provided HDL files to run the ZUMA system.
The blif_out file is a blif file which corresponds to the ZUMA architecture configured to the loaded design, which can be verified 
to be equivalent to the input BLIF using ABC.

B. Compiling to the ZUMA architecture
Generating a bitstream for the ZUMA architecture is done in the same way as generating the architecture Verilog. Call 'zuma_build.py'
 as above with the correct input files, and if a name for the output hex file is specified, a new bitstream will be generated.

C. Using the ZUMA system
Once the verilog architecture is created, and a hex bitstream is generated, the ZUMA system can be compiled and used.
The generated Verilog file, along with the files in the '../verilog/generic/' and '..verilog/platform/(platform)/ directory should be 
included in a new Xilinx/Altera project. The generated hex file should be placed in the project directory, and specified as the initial 
contents of the ZUMA configuration memory.  The top level file ZUMA_TB_wrapper includes a memory block which references the hex file 
'output.hex', which should be generated by the ZUMA tools and included with the project.
Note that sequential circuits are only supported in a Xilinx project. 

If the configuration memory size changes, or the configuration width, a new memory must be created using the vendor tools. 
Configuration is performed by loading each block of memory in the hex file to the port 'config_data', along with it's adress to 
'config_addr', and asserting the 'config_en' port. Configuration completes when all data is loaded. 

The ports 'fpga_inputs' and 'fpga_outputs' provide access to the FPGA logic. The pins are located at the edges of the array and 
begin at the grid coordinate (0,1) and increase in the Y direction first. The pins can be fixed to correspond to those of the 
input verilog by specifying a pin location file when runnng VPR placement. 

If you want to use the timing analysis or want to build a blif from a hex file,
see the timing and bit to blif readme.

4. Notes
----------------------
The LUTRAMs used in the ZUMA architecture and supplied with the archive are generated using Xilinx and Altera macros. To use a 
different LUTRAM or memory, instantiate it in the file 'lut_custom.v', and define a new platform (eg PLATFORM_STRATIXIV) in
the file 'define.v' to select this LUTRAM.