VHDL Metaprogramming with Combinators

This repository contains examples from the paper Metaprogramming with Combinators. All measurements were performed under Ubuntu 16.04 using Vivado 2018.3. You may need to install the packages libgmp-dev and libncurses-dev using apt in order to compile all examples.

Reproducing results from the paper

Running the synthesis tools produces a number of output files. LUT and FF resource usage can be found in the file post_route_util.rpt. To compute $f_\textrm{max}$, find the clock period ($t$) and WNS ($t_\textrm{WNS}$) in the file post_route_timing_summary.rpt and use the equation $f_\textrm{max} = 1/(t-t_\textrm{WNS})$.

Incrementer resource usage and $f_\textrm{max}$ (Tables 1 and 2):

C$\lambda$ash:
1. Change to the directory incrementer/clash.
2. Type make to generate VHDL files.
3. For serial results, cd to syn/serial and type make.
4. For parallel results, cd to syn/parallel-bubble-squeeze and type make.
5. Reports are produced in two directories: outputs_u8_8 and outputs_u16.
Kansas Lava:
1. Change to he directory incrementer/kansas-lava.
2. Type make to generate the code generator, bin/incrementer.
3. Invoke bin/incrementer to generate VHDL files.
4. For serial results, cd to syn/serial and type make.
5. For parallel results, cd to syn/parallel-bubble-squeeze and type make.
6. Reports are produced in 4 directories: outputs_u8_8, outputs_u8_8_rtl (RTL version), outputs_u16, and outputs_u16_rtl (RTL version).
MWC:
1. Change to the directory incrementer/vhdl-codegen.
2. Type make to generate VHDL files.
3. For serial results, cd to syn/serial and type make.
4. For parallel results, cd to syn/parallel-bubble-squeeze and type make.
5. Reports are produced in two directories: outputs_uq8_8 and outputs_uq16.

IP Comparisons (Table 3)

Comparisons are located in the directory ip-comparisons. For each IP core there are two directories: ip, which contains the Xilinx IP, and vhdl-codegen, which contains the MWC implementation.

Xilinx IP:
1. cd to the ip subdirectory.
2. Type make.
3. Outputs are in the outputs directory.
MWC
1. cd to the vhdl-codegen subdirectory.
2. Type make to generate VHDL files in the rtl subdirectory.
3. cd to the syn directory and type make.

Lines of code (Table 4)

LOC counts were performed using cloc (available via apt or at https://github.com/AlDanial/cloc).

Each approach's pipeline implementation is container in a file Pipeline.hs in the incrementer/loc directory.

Using `vivadostats`

The vivadostats script uses the Vivado tools to estimate the maximum frequency at which a VHDL module can be run. It can be installed into a virtualenv by running the following commands in the top-level directory (where this README is found):

virtualenv -p python3 venv
. venv/bin/activate
pip install -e tools/vivadostats

The tool can then be invoked as vivadostats as long as the virtualenv venv is active. A typical invocation would be:

vivadostats -d rtl/incrementer.vhd --top main --clock-period 2 -o stats

This would determine $F_\textrm{max}$ and resource utilization for the VHDL module main in rtl/incrementer.vhd and output CSV files containing statistics to the directory stats. Three CSV files would be generated by this particular invocation:

File	Contents
incrementer_clock.csv	Attempted clock periods with corresponding WNS, WHS, and WPWS
incrementer_timing.csv	Timing information for final run
incrementer_util.csv	Utilization for final run

Acknowledgments

This material is based upon work supported by the National Science Foundation under Grant No. CCF-1717088. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

mainland/vhdl-combinators-examples