This is a simple example with the goal of getting first-time users of Fletcher started with a project. The core of this example is an accumulator that sums all integers in a given Arrow column.
Be sure to read the sources as well, they contain useful hints.
Note: The produced files are available in the repository, so these steps can be skipped if so desired. They also provide a reference for when the tools are updated and their output changes. The goal is to track these changes into this example as quickly as possible, but it may lag behind.
The main component of Fletcher is the ColumnReader. The column reader will transparently read rows of data from memory and provide them on its output. Multiple column readers are supported with the use of an arbiter, though only one reader is used in this example. Next to this, a controller is added, which communicates with the host software and can be used to coordinate work in more complex designs. A default controller is provided. These components, together with the user provided accelerator, are combined into one component named fletcher_wrapper.
The fletcher_wrapper component is platform independent. To communicate with target platform host software, a host-specific interface must be added. The AWS F1 and CAPI SNAP platforms use memory mapped IO and an AXI bus. For these platforms, an interface layer is added that converts the Fletcher bus requests to AXI format. For configuration and control of the hardware function from the host software, MMIO registers are used.
The above will be contained in the following files:
- sum.vhd Hardware accelerated function, provided by the user
- fletcher_wrapper.vhd Readers and associated hardware (Fletcher)
- axi_top.vhd Interface for hosts using AXI.
The core accelerator function will be implemented inside the generated template and will differ depending on the Arrow schema that is used for storing the data. The instantiation template for the accelerated function can be generated automatically from an Arrow schema by fletchgen.
- C++11 compatible compiler (tested with GCC 5.5)
- Boost development libraries
- system
- filesystem
- regex
- program_options
- A VHDL simulator (e.g. ModelSim)
Install Apache Arrow. The supported release is 0.10.0.
$ curl "https://codeload.github.com/apache/arrow/tar.gz/apache-arrow-0.10.0" \
| tar --extract --gzip
$ cd arrow-apache-arrow-0.10.0
$ mkdir cpp/build
$ cd cpp/build
$ cmake \
-DARROW_PLASMA=ON \
..
$ make install
Clone the Fletcher repository and set up the environment.
$ git clone https://github.com/johanpel/fletcher.git
$ cd fletcher
Build fletchgen as described in its README.
$ cd codegen/fletchgen
$ mkdir debug
$ cd debug
$ cmake ..
$ make install
The schema that is used for the input data must be written to a file in order for fletchgen to use it. An example of how to generate such a file using Apache Arrow can be found in schema.cpp. The provided CMake project will create the schema file and the hardware skeleton files.
$ cd examples/sum/hardware-gen"
$ mkdir build
$ cd build
$ cmake ..
$ make
To create a schema manually after compiling:
$ ./schema
With the schema file (sum.fbs) from the previous step, generate the skeleton files. The files will already have been generated if you used the CMake project in the previous step. This will produce fletcher_wrapper.vhd and axi_top.vhd.
To run fletchgen manually:
$ fletchgen --quiet \
--input sum.fbs \
--output fletcher_wrapper.vhd \
--axi axi_top.vhd
Design the hardware accelerated function, using the component description of sum in the generated fletcher_wrapper.vhd. The design will need a simple state machine, control signals, and status signals. The finished design is included (hardware/sum.vhd) in the repository.
TODO: Generate SREC file and run platform-independent simulation.
If the tests pass, pick a supported platform to synthesise the design for. An example exist for AWS F1 instances.