_____________________   _____ ____________________ 
\______   \_   _____/  /  _  \\______   \______   \
 |       _/|    __)_  /  /_\  \|     ___/|       _/
  |    |   \|        \/    |    \    |    |    |   \
   |____|_  /_______  /\____|__  /____|    |____|_  /
           \/        \/         \/                 \/ 

REAPR: Reconfigurable Engine for Automata Processing
Authors: Ted Xie, Vinh Dang, Chunkun Bo, Jack Wadden, Kevin Skadron, and Mircea Stan
Contact: {ted.xie, vqd8a, cb2yy, jackwadden, skadron, mircea}@virginia.edu

Center for Automata Processing
University of Virginia
Charlottesville, VA

Copyright 2017 T. Xie et al.

ABSTRACT
========
Finite automata have proven their usefulness in high-profile domains ranging
from network security to machine learning. While prior work focused on their
applicability for purely regular expression workloads such as antivirus and
network security rulesets, recent research has shown that automata can optimize
the performance for algorithms in other areas such as machine learning and even
particle physics.  Unfortunately, their emulation on traditional CPU
architectures is fundamentally slow and further bottlenecked by memory.  In this
paper, we present REAPR: Reconfigurable Engine for Automata PRocessing, a
flexible framework that synthesizes RTL for automata processing applications as
well as I/O to handle data transfer to and from the kernel. We show that even
with memory and control flow overheads, FPGAs still enable extremely
high-throughput computation of automata workloads compared to other
architectures.

T. Xie, V. Dang, J. Wadden, K. Skadron, and M. Stan, "REAPR: Reconfigurable
Engine for Automata Processing," in International Conference on Field
Programmable Logic, Ghent, Belgium, 2017.

INTRODUCTION
============ 
REAPR (Reconfigurable Engine for Automata Processing) is a tool developed by
researchers at the University of Virginia's Center for Automata Processing
(CAP), designed to accelerate automata processing applications using FPGA
boards. Specifically, this tool accelerates non-deterministic finite automata
(NFAs) by exploiting the similarities between the spatial distribution of
automaton states and transitions with the spatial distribution of FPGA circuit
resources. For more information, see our paper published in the proceedings of
the 2017 International Conference on Field Programmable Logic, Ghent, Belgium.

REQUIREMENTS
============
REAPR currently only works with Xilinx tools and utilizes the SDAccel run-time.
You will need access to SDAccel 2017.1 and all of its affiliated software such
as Vivado and Vivado HLS. An SDAccel-compatible board such as the Alpha Data
ADM-PCIE-KU3 is also necessary to run the accelerator kernels.

* python3.6+
* virtualenv
* pip
* Xilinx Vivado HLS 2017.1
* Xilinx SDAccel 2017.1
* Synopsys VCS-MX (any version) for testbench simulation

FILE HIERARCHY
==============
REAPR/
  a2h/
    a2h.py # Automata-to-HDL conversion script
    Classes.py # define the behavior for all automata components
    OutputFiles/ # where all generated files will go
    Resources/ # directory for storing VHDL implementations of automata components
    Templates/ # Jinja 2.0 templates to generate HDL for automata
    Examples/ # contains some example ANML files
  pcie_integration/
    copy_kernel.c/h # basic memory-copying kernel that is modified by integration scripts
    python_tools/ # Contains scripts to modify memory-copying kernel and integrate automata HDL code
    vhls_prj/ # directory that contains Vivado HLS project
    vv_prj/ # directory that contains Vivado project

SETUP
=====
The only setup necessary is to run the source_me.sh script in the root directory
of this project.  This script will set up the REAPR_HOME environment variable
that the compilation scripts depend upon and also generate a python virtual
environment with Jinja2 pre-installed.

$ source source_me.sh

USAGE
=====
To generate a REAPR automaton accelerator kernel with naive I/O (every report
from every cycle is stored), navigate to pcie_integration/rtl_prj and modify
rtl.sh to reflect your application requirements. Parameters available to modify
are the source ANML file, number of reporting elements, input data size, etc.
Then, simply run ./rtl.sh and wait for the FPGA compiler to finish running.

"REAPR" ASCII art generated by http://patorjk.com/software/taag/.