Keras model accelerator targetting Amazon F2 built with hls4ml

Overview

This repository showcases an end-to-end hls4ml¹ workflow that converts a tiny TensorFlow/Keras classifier into a Vitis HLS project ready for FPGA synthesis. The driver script quick_demo.py builds the neural network, tweaks the generated HLS configuration to favour resource usage, and launches the hls4ml conversion flow.

The generated project (my_hls_prj/) contains synthesizable C++ firmware (firmware/), weight headers, TCL helpers, and a full Vitis HLS workspace (myproject_prj/) with C-simulation and synthesis reports.

Neural network snapshot

Layer	Output shape	Activation	Parameters
Input (input_layer)	(16,)	—	—
Dense (dense)	(8,)	ReLU	16×8 weights + 8 biases
Dense (dense_out)	(4,)	Softmax	8×4 weights + 4 biases

Total trainable parameters: 212. The script automatically detects the softmax layer to keep the configuration resilient to renaming.

Prerequisites

• Python 3.9+
• TensorFlow (tested with 2.14+)
• hls4ml (tested with 0.8+)
• PyYAML
• Xilinx Vitis HLS 2020.2 or newer (only required if you plan to open/rebuild the generated HLS project).

Install the Python dependencies into your environment:

pip install tensorflow hls4ml pyyaml

Quick start

1. Run the demo script from the repository root:

   python quick_demo.py

   This will:

   • build the Keras model,
   • derive an hls4ml configuration,
   • apply resource-oriented overrides (reuse factors, fixed-point precisions, softmax LUT sizes),
   • write the editable YAML snapshot to my_hls_config.yaml, and
   • generate the Vitis HLS project under my_hls_prj/ while running C-simulation and C-synthesis.

2. Inspect the generated assets:

   • my_hls_config.yaml – the modified configuration used for conversion.
   • my_hls_prj/keras_model.keras – serialized Keras model.
   • my_hls_prj/firmware/ – top-level HLS function (myproject.cpp), layer configs, and weight headers.
   • my_hls_prj/myproject_prj/solution1/ – Vitis HLS run directory with logs and reports (csim/report/, syn/report/).

Regenerating with tweaked settings

Feel free to edit my_hls_config.yaml or adjust the configuration logic in quick_demo.py (e.g., change reuse factors, precision, or target FPGA part). Re-run the script to regenerate the HLS project with your changes.

To skip synthesis (useful for rapid iteration), modify the final call in quick_demo.py:

hls_model.build(csim=True, synth=False, cosim=False, export=False)

Using the project in Vitis HLS

1. Launch Vitis HLS and open the project TCL script:

   vitis_hls -f my_hls_prj/project.tcl

2. Inside Vitis HLS you can rerun C-simulation, synthesis, or export RTL/ IP for Vivado.

Troubleshooting tips

• Missing hls4ml modules: ensure the Python environment has the hls4ml package installed (see prerequisites).
• TensorFlow ABI/compat errors: align your TensorFlow version with your Python interpreter; virtual environments help isolate dependencies.
• Vitis HLS not found: source your Xilinx/Vitis settings script so vitis_hls is on PATH before running TCL or shell helpers (build_lib.sh).

Repository structure

.
├── quick_demo.py          # Main conversion script
├── my_hls_config.yaml     # Saved configuration after script tweaks
├── my_hls_prj/            # Auto-generated HLS project and artifacts
│   ├── firmware/          # Synthesizable C++ and parameters
│   ├── myproject_prj/     # Vitis HLS workspace (solution1 reports, etc.)
│   └── ...
└── tb_data/               # Simulation outputs (generated by Vitis HLS)

Next steps

• Experiment with deeper/wider Keras models and observe the effect on resource utilisation.
• Extend the TCL scripts (build_prj.tcl, vivado_synth.tcl) to automate RTL export or Vivado synthesis.

Footnotes

1. FastML Team. fastmachinelearning/hls4ml. Zenodo, 2025. Version v1.1.0. doi:10.5281/zenodo.1201549. https://github.com/fastmachinelearning/hls4ml ↩