CAPI SNAP Support (#10)

* CAPI SNAP support tested on ADKU3 * Add Echo platform that uses STDIO for debugging * Moved software builds to CMake * Temporary fix for issue #4 * Fixes #6 * Update docs
abs-tudelft · Feb 26, 2018 · 88bd8d3 · 88bd8d3
1 parent 0b6f745
commit 88bd8d3
Show file tree

Hide file tree

Showing 111 changed files with 5,618 additions and 52,205 deletions.
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,7 @@ platforms/aws-f1/cl_arrow/software/runtime/regexp/output\.txt
 platforms/aws-f1/cl_arrow/software/runtime/regexp/output\.csv
 
 *.dat
+
+platforms/aws-f1/regexp/design/ip/axi_interconnect_top/axi_interconnect_top\.xml
+
+platforms/snap/regexp/sw/snap_regexp
diff --git a/README.md b/README.md
@@ -62,9 +62,9 @@ following features:
 
 ### Platform support:
 * Our hardware descriptions are vendor independent; we don't use any vendor IP.
-* There is an example project for Amazon EC2 F1 instances
+* There is an example project for the Amazon EC2 F1 and CAPI SNAP FPGA platforms.
 * Our bus interface speaks AXI, so it should be easy to integrate in many existing 
-  platforms
+  platforms.
 * Upcoming: OpenCAPI support
 
 ## Credits
@@ -78,4 +78,5 @@ If you would like to contribute, open issues, make pull requests, or drop us an
     * For the current state of the project, this would be your starting
       point in hardware design.
   * [How to use the host-side run-time library](runtime).
-  * [Regular Expression matching example on Amazon EC2 F1](platforms/aws-f1/cl_arrow)
+  * [Regular Expression matching example on Amazon EC2 F1](platforms/aws-f1/regexp)
+  * [Regular Expression matching example on CAPI SNAP](platforms/snap/regexp)
diff --git a/env.sh b/env.sh
@@ -5,6 +5,5 @@ export FLETCHER_RUNTIME_DIR=$FLETCHER_DIR/runtime
 export FLETCHER_CODEGEN_DIR=$FLETCHER_DIR/codegen
 export FLETCHER_HARDWARE_DIR=$FLETCHER_DIR/hardware
 export FLETCHER_PLATFORM_DIR=$FLETCHER_DIR/platforms
+export FLETCHER_EXAMPLES_DIR=$FLETCHER_DIR/examples
 
-# Library dir
-export LD_LIBRARY_PATH=$FLETCHER_RUNTIME_DIR:$LD_LIBRARY_PATH
diff --git a/..._arrow/software/runtime/regexp/.gitignore → examples/regexp/.gitignore b/..._arrow/software/runtime/regexp/.gitignore → examples/regexp/.gitignore
diff --git a/examples/regexp/README.md b/examples/regexp/README.md
@@ -0,0 +1,80 @@
+# Regular Expression Matching example hardware description
+
+This is an example in which some [ColumnReaders](../../../hardware) are
+used to read a column with UTF8 strings. The config string for the 
+columns is therefore "listprim(8)", to generate an interface to a 
+non-nullable list of non-nullable 8-bit wide elements.
+
+The design instantiates N of these ColumnReaders, attached to 
+N regular expression matching units, that can all work in parallel.
+
+N depends on the platform, how much room there is in the FPGA, etc.
+Currently, for AWS EC2 F1 instances N=16 and for CAPI SNAP on a ADKU3 N=8.
+
+The ColumnReaders are attached to our internal bus arbiter/interconnect,
+but we inserted an `axi_read_converter` to convert the `bsize` 
+(Burst Size) signal properly to match the AWS Shell requirement of 
+setting this to 2^6=64 bytes fixed burst beat size. This is because 
+the ColumnReaders bus data width is 32-bits. `axi_read_converter` also 
+converts our internal bus burst lengths to AXI specification. Furthermore, 
+it includes a read response FIFO as we don't want to lock up the arbiter
+dumping bursts into the ColumnReaders, which are less wide.
+
+## Design files description
+
+### Hardware implementation:
+
+| File                            | Description                                                                                                                |
+| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------- |
+| hardware/animals/*.vhd          | The regular expression matchers generated using [VHDRE](../../codegen/vhdre). They all match to some names of pet animals. |
+| hardware/arrow_regexp.vhd       | The top-level for this platform-independent design. |
+| hardware/arrow_regexp_unit.vhd  | One regular expression matching unit which is instantiated N times to work in parallel. |
+| hardware/arrow_regexp_pkg.vhd   | The package for this example containing some constants and definitions. |
+| hardware/axi_read_converter.vhd | A helper unit that converts internal bus signals to AXI spec and converts wide bus interfaces to smaller bus interfaces. |
+
+### Software implementation:
+
+| File                            | Description                                                                                                                |
+| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------- |
+| software/regexp.cpp             | The main file for this example |
+| software/RegExUserCore.cpp      | The implementation of the UserCore abstract class |
+| software/RegExUserCore.h        | Header for previous item |
+
+
+# Build
+
+### 1. First build the [runtime library](../../../runtime).
+
+### 2. Build the example
+
+You have to pick a run-time platform to build the example host-side software for.
+
+Currently you can choose the CMake option RUNTIME_PLATFORM to be:
+
+* 0 : Echo platform: just uses the STDIO to simulate the FPGA
+* 1 : [AWS EC2 F1](../../platforms/aws-f1/)
+* 2 : [CAPI SNAP](../../platforms/snap/)
+
+Make sure to compile the run-time library with support for that platform first.
+
+Proceed to build this application:
+
+    $ cd $FLETCHER_EXAMPLES_DIR/regexp/software
+    $ mkdir build
+    $ cd build
+    $ cmake .. -DRUNTIME_PLATFORM=?
+    $ make
+
+Make sure to replace ? with your chosen platform.
+
+### 3. Run the example:
+
+* Note: you probably need sudo rights for most platforms:
+
+    $ ./regexp 
+
+Optional parameters:
+
+    $ ./regexp <no. strings> <no. repeats> <experiment mask> <num. threads>
+
+
diff --git a/platforms/aws-f1/cl_arrow/design/bird.vhd → examples/regexp/hardware/animals/bird.vhd b/platforms/aws-f1/cl_arrow/design/bird.vhd → examples/regexp/hardware/animals/bird.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/bunny.vhd → examples/regexp/hardware/animals/bunny.vhd b/platforms/aws-f1/cl_arrow/design/bunny.vhd → examples/regexp/hardware/animals/bunny.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/cat.vhd → examples/regexp/hardware/animals/cat.vhd b/platforms/aws-f1/cl_arrow/design/cat.vhd → examples/regexp/hardware/animals/cat.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/dog.vhd → examples/regexp/hardware/animals/dog.vhd b/platforms/aws-f1/cl_arrow/design/dog.vhd → examples/regexp/hardware/animals/dog.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/ferret.vhd → examples/regexp/hardware/animals/ferret.vhd b/platforms/aws-f1/cl_arrow/design/ferret.vhd → examples/regexp/hardware/animals/ferret.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/fish.vhd → examples/regexp/hardware/animals/fish.vhd b/platforms/aws-f1/cl_arrow/design/fish.vhd → examples/regexp/hardware/animals/fish.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/gerbil.vhd → examples/regexp/hardware/animals/gerbil.vhd b/platforms/aws-f1/cl_arrow/design/gerbil.vhd → examples/regexp/hardware/animals/gerbil.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/hamster.vhd → examples/regexp/hardware/animals/hamster.vhd b/platforms/aws-f1/cl_arrow/design/hamster.vhd → examples/regexp/hardware/animals/hamster.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/horse.vhd → examples/regexp/hardware/animals/horse.vhd b/platforms/aws-f1/cl_arrow/design/horse.vhd → examples/regexp/hardware/animals/horse.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/kitten.vhd → examples/regexp/hardware/animals/kitten.vhd b/platforms/aws-f1/cl_arrow/design/kitten.vhd → examples/regexp/hardware/animals/kitten.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/lizard.vhd → examples/regexp/hardware/animals/lizard.vhd b/platforms/aws-f1/cl_arrow/design/lizard.vhd → examples/regexp/hardware/animals/lizard.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/mouse.vhd → examples/regexp/hardware/animals/mouse.vhd b/platforms/aws-f1/cl_arrow/design/mouse.vhd → examples/regexp/hardware/animals/mouse.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/puppy.vhd → examples/regexp/hardware/animals/puppy.vhd b/platforms/aws-f1/cl_arrow/design/puppy.vhd → examples/regexp/hardware/animals/puppy.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/rabbit.vhd → examples/regexp/hardware/animals/rabbit.vhd b/platforms/aws-f1/cl_arrow/design/rabbit.vhd → examples/regexp/hardware/animals/rabbit.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/rat.vhd → examples/regexp/hardware/animals/rat.vhd b/platforms/aws-f1/cl_arrow/design/rat.vhd → examples/regexp/hardware/animals/rat.vhd
diff --git a/platforms/aws-f1/cl_arrow/design/turtle.vhd → examples/regexp/hardware/animals/turtle.vhd b/platforms/aws-f1/cl_arrow/design/turtle.vhd → examples/regexp/hardware/animals/turtle.vhd