aws-fpga-f2-vitis-to-afi-poc

A proof-of-concept repository that helps FPGA software engineers bridge an AMD/Xilinx Vitis HLS RTL export into an AWS EC2 FPGA F2 HDK Customer Logic (CL) project, which can then be packaged into an AFI using the standard AWS flow.

Note: Despite the repository name, this repo generates an AWS F2 HDK CL project from a Vitis HLS RTL export.
AFI creation is performed using the standard AWS HDK CL → DCP → AFI flow.

Contents

• Overview
• Repository contents
• Platform
• Quickstart and tutorial
• High-level integration flow
• Project disclaimer
• Maintainer disclaimer
• Third-party code and licenses

Overview

This repository provides a lightweight, opinionated bridge from Vitis HLS RTL export to a buildable AWS EC2 F2 HDK CL project. Once generated, you can proceed with the standard AWS tooling to produce an AFI via CL → DCP → AFI.

Status note (as of 2025-12-25): AWS F2 Vitis documentation indicates that Vitis-based AFI generation is not supported on F2 instances. Please verify the latest status in the AWS docs:
https://awsdocs-fpga-f2.readthedocs-hosted.com/latest/vitis/README.html

What this repo does

Given a Vitis HLS synthesis/export output directory, the generator automates the following:

1. Create a new CL project using AWS FPGA HDK tooling/templates.
2. Import HLS outputs into the project (RTL plus required collateral).
3. Validate the HLS top-level interfaces in the generated CL:
   • Requires exactly one s_axilite control interface
   • Allows zero or one m_axi memory-mapped master interface
   • Rejects designs with multiple s_axilite and/or multiple m_axi
4. Patch the CL template sources to integrate the HLS RTL top module into the AWS CL wrapper.
5. If m_axi is present, include DDR crossbar in the CL project.
6. Update CL build scripts so all imported RTL sources are picked up during synthesis/implementation.
7. Print next-step commands to run the AWS flow for CL → DCP → AFI.

What this repo does not do

• It does not generate an AFI end-to-end by itself.
• It does not support multiple HLS kernels, multiple m_axi, or multiple s_axilite.
• It does not attempt to cover all AWS shell configurations. The initial release targets a single, well-defined CL template path.

Expected inputs and outputs

Input

• A Vitis HLS synthesis/export output folder containing RTL plus metadata required to identify the top module and interfaces.

Output

• A complete AWS HDK CL project directory, ready for users to build into a DCP and package into an AFI using AWS-provided tools.
• (Experimental) regs.py: a helper file containing extracted register/address metadata from the synthesized RTL (Verilog), intended to simplify host-side integration.

Repository Contents

• hls_to_cl.py
  Main generator script that:
  • Creates a new AWS HDK CL project from the official template
  • Copies HLS synthesis/export outputs into the CL project
  • Validates top-level interfaces (exactly one s_axilite, at most one m_axi)
  • Modifies CL template sources to integrate the HLS RTL design
  • Optionally imports DDR/crossbar collateral when m_axi is detected
  • Updates CL build scripts to compile all HLS RTL sources
  • Prints next-step commands for CL → DCP → AFI using AWS tooling
• TUTORIAL.md
  Step-by-step guide covering:
  • Running HLS synthesis/export for the provided examples
  • Generating a CL project with hls_to_cl.py
  • Building the CL into a DCP using AWS HDK scripts
  • Creating/ingesting an AFI using AWS commands
  • Instance-side runtime testing using the provided Python host tests
• examples_hls/
  • README.md: how to run HLS synthesis/export for each example, and where the generator expects outputs.
  • vadd_ocl/: example HLS design with s_axilite only
    • Interfaces: s_axilite (required), no m_axi
    • Use case: simplest “hello world” integration into an AWS CL project
  • vadd_ocl_ddr/: example HLS design with s_axilite + m_axi
    • Interfaces: s_axilite + m_axi
    • Use case: demonstrates memory-mapped transactions and the DDR/crossbar integration path
• examples_cl/
  • README.md: how these CL folders were generated, what they correspond to, and how to validate outputs.
  • cl_vadd_ocl/: reference CL generated by running hls_to_cl.py on examples_hls/vadd_ocl/
  • cl_vadd_ocl_ddr/: reference CL generated by running hls_to_cl.py on examples_hls/vadd_ocl_ddr/ (includes the m_axi path)
• cl_python_runtime/
  • (internal files): used by the runtime test flow; refer to the TUTORIAL.
• hls_to_cl_resources/
  • (internal files): helper RTL/Tcl/script fragments (e.g., DDR integration components).
  • Note: this directory is not intended for direct user modification; the generator copies from here as needed.

• FAQ.md
  Common questions, limitations, and troubleshooting notes for the scripts and integration flow.

• LICENSE.md
  Repository license (see also Third-party code and licenses).

• README.md
  This document.

Platform

• Target: AWS EC2 FPGA F2
• Shell: F2 Small Shell (0x10212415)
• Status: Experimental / proof-of-concept

Tested environments

This workflow has two stages with different environment requirements:

A) Vitis HLS (RTL export stage)

• Vitis HLS: 2025.1, 2025.2
• Tested on: Windows 11
• Note: RTL export should work on any OS supported by Vitis HLS.

B) AWS F2 HDK (CL build + DCP/AFI stage)

• Recommended: AWS FPGA Developer AMI (includes Vivado and AWS FPGA build/AFI tooling)
• AWS HDK: aws-fpga (F2 branch) with hdk_setup.sh sourced in each shell
• Python: 3.10+ (for build scripts and helper tooling)

Note: The generator can run anywhere, but building DCP/AFI requires an AWS HDK-capable environment (recommended: AWS FPGA Developer AMI).

AWS Shell interface notes (F2)

• AppPF BAR0: 64 MiB prefetchable BAR mapped to the OCL AXI-Lite interface.
• AppPF BAR4: 128 GiB prefetchable BAR that can be used to map the external/internal memory address space.
• PCIS: 512-bit AXI4 interface used for high-throughput access paths (e.g., DDR/HBM via BAR4).

For authoritative and up-to-date details, refer to the AWS Shell Interface Specification:
https://awsdocs-fpga-f2.readthedocs-hosted.com/latest/hdk/docs/AWS-Shell-Interface-Specification.html

High-Level Integration Flow

1. Develop the kernel in Vitis HLS
2. Export RTL from Vitis HLS
3. Run the generator to integrate RTL into an AWS FPGA CL project
4. Build the CL and generate a DCP
5. Package the DCP into an AFI
6. Deploy and validate on an AWS EC2 FPGA F2 instance

Quickstart and Tutorial

For a step-by-step walkthrough, see:

• TUTORIAL.md

Project Disclaimer

• This project is not affiliated with Amazon Web Services, Inc. or AMD/Xilinx.
• Provided “AS IS”, without warranties or conditions of any kind.
• Experimental / proof-of-concept only; interfaces and scripts may change without notice.
• Users are responsible for complying with applicable third-party licenses and terms (AWS FPGA HDK/SDK, Vivado, Vitis, etc.).

Maintainer Disclaimer

This repository is maintained as a portfolio-quality proof of concept focused on cloud FPGA acceleration workflows, CL/shell integration, and build automation around AWS EC2 F2.

For collaboration or opportunities related to FPGA acceleration and systems-level tooling, please reach out via:

• https://www.linkedin.com/in/lohboonhong

Third-Party Code and Licenses

Repository license (original work)

Unless otherwise indicated in a file’s header or accompanying notices, all original source code authored by this repository’s owner is licensed under the Apache License 2.0 (see LICENSE.md).

Third-party materials (AWS FPGA HDK and others)

This repository includes third-party materials, including files copied from and/or modified from the AWS FPGA Hardware Development Kit (HDK). Such files retain their original copyright and license notices and are licensed under the license identified in the relevant file headers and/or accompanying notice files.

AWS-provided/AWS-derived files may be licensed under the Amazon Software License (see LICENSES/Amazon-Software-License.txt). The Amazon Software License is not the Apache License 2.0; it contains a use limitation and other terms that govern use of the AWS-provided/AWS-derived files. In the event of any conflict, the applicable third-party license terms control.

This site is open source. Improve this page.