Fixed issue in setup.py

documentation/README.txt

@@ -0,0 +1,20 @@
+These files were written by Marco Merlini (marco.merlini@utoronto.ca), who is
+not the official maintainer of this repository. They are a summary of his
+personal notes from using Galapagos.
+
+For Galapagos users:
+
+	galapagos_flow.txt explains the design flow of using Galapagos
+
+
+For Galapagos developers:
+
+	file_reference.txt tries to disambiguate the utility of each script
+	packaged in this reposiitory
+
+	adding_vivado_versions.txt gives a general method for extending Galapagos
+	to work with new versions of Vivado. Your mileage may vary.
+
+	shell_development.txt explains how to add support for new boards in
+	Galapagos
+

documentation/galapagos_flow.txt

@@ -0,0 +1,122 @@
+===========================
+DEFINITIONS AND ASSUMPTIONS
+===========================
+
+In this file, $GALAPDIR will refer to the root directory of the Galapagos 
+repository. (Note: this is not an environment variable used by Galapagos; it is 
+a placeholder for you to replace yourself)
+
+$BOARD will refer to the name of the currently targeted board. 
+
+All commands are assumed to be run from inside $GALAPDIR (unless otherwise 
+stated).
+
+A "kernel" means a single user module in the Galapagos cluster, analogous to a 
+Rank in MPI.
+
+
+========
+OVERVIEW
+========
+
+The following numbered list explains the brief details of using Galapagos. More 
+details are provided in the later sections of this document. There is also a 
+quick blurb on writing kernels in HLS.
+
+When first installing Galapagos, 
+
+    1) Run `$GALAPDIR/build.sh` and answer all its questions
+
+For each board you wish to use,
+
+    2) Use `galapagos_update_board <your board name>` to select the board, and 
+
+    3) Run `make hlsmiddleware` from inside $GALAPDIR
+
+To create a Galapagos project,
+
+    4) Package kernels as IPs and place them in $GALAPDIR/hlsBuild/$BOARD/ip, 
+       where $BOARD is the board that the IP is targeted for. 
+       -> Use this directory even if your kernel is not written in HLS
+
+    5) Write a logical file and a mapping file (details provided below)
+
+    6) Set the LOGICALFILE and MAPFILE environment variables to be the full 
+       path of your logical file and mapping file (repsectively). Also set the 
+       PROJECTNAME environment variable to be the desired project name
+
+    7) Run `make middleware` from inside $GALAPDIR
+
+    8) If there were no errors, Galapagos will have created a directory called 
+       $GALAPDIR/projects/$PROJECTNAME which contains a number of TCL scripts 
+       and a bash script called createCluster.sh. Simply run this shell script 
+       and wait for Vivado to produce your bitstream(s).
+
+
+===============================
+WHEN FIRST INSTALLING GALAPAGOS
+===============================
+
+For the time being, Galapagos works by reading a number of environment 
+variables. Run
+
+    $ cd $GALAPDIR
+    $ source build.sh
+
+This will bring up a snazzy menu. Answer its questions. Don't worry about 
+making a mistake; you can always try this again if it doesn't work.
+
+Once you have finished answering the questions, Galapgos will have created a 
+new file in your home folder. You can take a look at it:
+
+    $ less ~/.galapagos
+
+This file simply sets Galapagos's environment variables using the answers you 
+provided earlier. It also defines two bash shell functions: 
+galapagos-update-board and galapagos-update-version. The first function allows 
+you ask Galapagos to target a different board without re-running build.sh, and 
+the second lets you select a different Vivado version.
+
+Finally, note that build.sh adds a line to your .bashrc:
+
+    $ less ~/.bashrc
+
+This ensures that .galapagos is called whenever you open a new bash shell. 
+
+
+==============================
+FOR EACH BOARD YOU PLAN TO USE
+==============================
+
+Galapagos uses a number of custom IP cores written in HLS. These must be 
+synthesized and packaged as IPs before you can start making your own projects.
+
+Run the following from inside $GALAPDIR:
+
+    $ galapagos-update-board <your board name>
+    $ make hlsmiddleware
+
+Currently, Galapagos supports the following choices for <your board name>:
+
+    - zynq-p2
+    - zedboard
+    - sidewinder
+    - adm-8k5
+    - adm-8k5-debug
+
+
+======================
+WRITING KERNELS IN HLS
+======================
+
+Include the header file in $GALAPDIR/middleware/include/galapagos_packet.h
+
+The following is a skeleton of an HLS Galapagos kernel:
+
+    (TODO)
+
+
+=====================
+CREATING YOUR PROJECT
+=====================
+

examples/hello_world/Makefile

@@ -0,0 +1,42 @@
+all: hello_world world middleware pick_up_vivados_dirty_socks
+
+hello_world: .hello_world
+.hello_world: hello_world.cpp
+	vivado_hls hello_world.tcl	
+	touch .hello_world
+
+world: .world
+.world: world.cpp
+	vivado_hls world.tcl
+	touch .world
+
+middleware: .middleware
+.middleware: logical.xml mapping.xml .hello_world .world
+	export LOGICALFILE=$(shell realpath logical.xml)
+	export MAPFILE=$(shell realpath mapping.xml)
+	export PROJECTNAME=hello_world
+	make -C$(GALAPAGOS_PATH) middleware
+	touch .middleware
+
+pick_up_vivados_dirty_socks:
+	# Cleaning up after Vivado... 
+	rm -rf vivado*	
+
+show_reports:
+	less $(GALAPAGOS_PATH)/hlsBuild/$(GALAPAGOS_BOARD_NAME)/ip/hello_world/solution1/syn/report/hello_world_csynth.rpt
+	less $(GALAPAGOS_PATH)/hlsBuild/$(GALAPAGOS_BOARD_NAME)/ip/world/solution1/syn/report/world_csynth.rpt
+
+clean: 
+	rm -rf $(GALAPAGOS_PATH)/hlsBuild/$(GALAPAGOS_BOARD_NAME)/ip/hello_world/
+	rm -rf $(GALAPAGOS_PATH)/hlsBuild/$(GALAPAGOS_BOARD_NAME)/ip/world/
+	rm -rf $(GALAPAGOS_PATH)/projects/hello_world
+	rm -rf .world
+	rm -rf .hello_world
+	rm -rf .middleware
+	rm -rf vivado*	
+
+
+# Very bizarre! GNU Make will silently add calls to g++ if you have cpp files
+# in your directory (even if none of your rules or dependencies mention it).
+# This is because of some implicit rules... 30 minutes I found this solution
+.SUFFIXES:

examples/hello_world/README.txt

@@ -0,0 +1,26 @@
+=====================
+GALAPAGOS HELLO WORLD
+=====================
+
+This example contains:
+
+	 - hello_world.cpp, a Galapagos HLS kernel with DEST = 1 that contantly
+	   broadcasts a message to the kernel with DEST = 2
+
+	 - world.cpp, a Galapagos HLS kernel with DEST = 2 that ignores all
+	   incoming messages
+
+	 - hello_world.tcl and world.tcl. Scripts that invoke Vivado HLS to compile
+	   hello_world.cpp and world.cpp into Verilog
+
+	 - logical.xml, the logical file
+
+	 - mapping.xml, the mapping file
+
+	 - A Makefile
+
+
+Make sure you have followed the Galapagos setup instructions (see
+documentation/galapagos_flow.txt). This Makefile will generate a Vivado project
+in projects/hello_world/0/
+

examples/hello_world/hello_world.cpp

@@ -0,0 +1,20 @@
+#include "galapagos_packet.h"
+
+using gp = galapagos::stream_packet<64>;
+
+void hello_world(hls::stream<gp> *out) {
+	#pragma HLS INTERFACE axis register both port=out
+	#pragma HLS INTERFACE ap_ctrl_none port=return
+
+	gp tmp;
+
+	tmp.dest = 2;
+	tmp.data = 0xFEEDBADBEEF2BABE;
+	tmp.id = 1;
+	tmp.last = 1;
+	tmp.keep = 0xFFFF;
+
+	if(!out->full()) out->write(tmp);
+
+
+}

examples/hello_world/hello_world.tcl

@@ -0,0 +1,23 @@
+set galapagos_path $::env(GALAPAGOS_PATH)
+set board_name $::env(GALAPAGOS_BOARD_NAME)
+set part_name $::env(GALAPAGOS_PART)
+
+set src_path_root $galapagos_path/examples/hello_world
+
+# Does this still work? We'll find out, I guess...
+cd $galapagos_path/hlsBuild/${board_name}/ip
+
+open_project hello_world
+set_top hello_world
+open_solution "solution1"
+set_part ${part_name}
+#csynth path
+add_files $src_path_root/hello_world.cpp -cflags "-I $galapagos_path/middleware/include -I $galapagos_path/middleware/CPP_lib/Galapagos_lib"
+create_clock -period 250MHz -name default
+config_interface -expose_global
+csynth_design
+export_design -format ip_catalog
+close_project
+
+quit
+

examples/hello_world/logical.xml

@@ -0,0 +1,51 @@
+<cluster>
+
+	<!-- Describe the packet format. I doubt this does anything, since the
+	values are "hardcoded" in middleware/include/packet_size.h-->
+	<packet>
+		<data> 64 </data>
+		<keep> 1  </keep> <!-- Why is this 1? -->
+		<last> 1  </last>
+		<dest> 16 </dest>
+		<!-- What about id? -->
+	</packet>
+
+	<!-- Describe the hello_world kernel -->
+	<kernel> hello_world
+		<!-- Use the vendor and library that get applied when HLS exports your
+		ip -->
+		<vendor> xilinx.com </vendor>
+		<lib> hls </lib>
+		<version> 1.0 </version>
+		<num> 1 </num> <!-- Use kernel number 1 -->
+		<rep> 1 </rep> <!-- Only one copy -->
+
+		<!-- Tell Galapagos what our ports are called -->
+		<clk> ap_clk </clk>
+		<aresetn> ap_rst_n </aresetn>
+		<m_axis>
+			<scope> global </scope>
+			<name> out_r </name>
+		</m_axis>
+	</kernel>
+
+	<!-- Describe the world kernel -->
+	<kernel> world
+		<!-- Use the vendor and library that get applied when HLS exports your
+		ip -->
+		<vendor> xilinx.com </vendor>
+		<lib> hls </lib>
+		<version> 1.0 </version>
+		<num> 2 </num> <!-- Use kernel number 2 -->
+		<rep> 1 </rep> <!-- Only one copy -->
+
+		<!-- Tell Galapagos what our ports are called -->
+		<clk> ap_clk </clk>
+		<aresetn> ap_rst_n </aresetn>
+		<s_axis>
+			<scope> global </scope>
+			<name> in_r </name>
+		</s_axis>
+	</kernel>
+
+</cluster>

examples/hello_world/mapping.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<cluster>
+	<node>
+		<!-- node details -->
+		<type> hw </type> <!-- Request FPGA -->
+		<comm> raw </comm> <!-- not that it matters... -->
+		<board> sidewinder </board>
+		<mac> 01:23:45:67:89:AB </mac>
+		<ip> 10.10.84.234 </ip>
+
+		<!-- Place both kernels on this board -->
+		<kernel> 1 </kernel>
+		<kernel> 2 </kernel>
+
+	</node>
+
+</cluster>

examples/hello_world/world.cpp

@@ -0,0 +1,11 @@
+#include "galapagos_packet.h"
+
+using gp = galapagos::stream_packet<64>;
+
+void world(hls::stream<gp> *in) {
+	#pragma HLS INTERFACE axis register both port=in
+	#pragma HLS INTERFACE ap_ctrl_none port=return
+
+	gp tmp;
+	if (!in->empty()) in->read(tmp);
+}

examples/hello_world/world.tcl

@@ -0,0 +1,23 @@
+set galapagos_path $::env(GALAPAGOS_PATH)
+set board_name $::env(GALAPAGOS_BOARD_NAME)
+set part_name $::env(GALAPAGOS_PART)
+
+set src_path_root $galapagos_path/examples/hello_world
+
+# Does this still work? We'll find out, I guess...
+cd $galapagos_path/hlsBuild/${board_name}/ip
+
+open_project world
+set_top world
+open_solution "solution1"
+set_part ${part_name}
+#csynth path
+add_files $src_path_root/world.cpp -cflags "-I $galapagos_path/middleware/include -I $galapagos_path/middleware/CPP_lib/Galapagos_lib"
+create_clock -period 250MHz -name default
+config_interface -expose_global
+csynth_design
+export_design -format ip_catalog
+close_project
+
+quit
+

middleware/Makefile

@@ -24,7 +24,7 @@ python_path = $(middleware_path)/python
 all: middleware hlsmiddleware
 
 middleware: guard-LOGICALFILE guard-MAPFILE guard-PROJECTNAME ${LOGICALFILE} ${MAPFILE}
-	python3.5 ${python_path}/globalFPGAParser.py --logicalFile=${LOGICALFILE} \
+	python ${python_path}/globalFPGAParser.py --logicalFile=${LOGICALFILE} \
 		--mapFile=${MAPFILE} --projectName=${PROJECTNAME}
 	chmod +x $(GALAPAGOS_PATH)/projects/$(PROJECTNAME)/createCluster.sh