Skip to content

User_Guide_AWS_EC2_FPGA_Development_Kit.md

Latest commit

 

History

History
245 lines (196 loc) · 18.7 KB

User_Guide_AWS_EC2_FPGA_Development_Kit.md

File metadata and controls

245 lines (196 loc) · 18.7 KB

AWS EC2 FPGA Development Kit

The development kit includes example designs to get you familiar with developing for AWS EC2 FPGA Instances.

AWS EC2 F2 Instance Overview

Amazon EC2 F2 instances are Amazon’s second-generation FPGA-powered instances, purpose-built for customers to develop and deploy reconfigurable hardware in the cloud. With AMD UltraScale+ VU47P FPGAs and High Bandwidth Memory (HBM), customers can achieve orders-of-magnitude application acceleration such as 95x faster graph database analysis and 10x faster genomics secondary analysis when compared to CPU-only analysis. F2 instances provide up to 8 FPGAs paired with a 3rd-generation AMD EPYC (Milan) processor. F2 instances provide 3x more processor cores (192 vCPU), 2x more system memory (2 TiB), 2x NVMe SSDs (7.6 TiB), and 4x more networking bandwidth (100 Gbps), compared to the previous generation FPGA-based instances. The accompanying AWS FPGA Developer kit empowers developers to quickly start building with their hardware accelerations and adopting advanced technology, such as HBM, to process data at up to 460 GiB/s.

This documentation is relevant to F2 only. Therefore, it applies to all branches on the GitHub repo prefixed with f2. Any branches not prefixed f2 in their name are not referred to in this documentation.

Instance Types

f2_instances

F2 2nd Generation On-Cloud FPGA Accelerator Card

accel_card_specs

Comparison to F1

f2_f1_comp

AWS EC2 F2 FPGA Development Kit

Development Environments

This table lists the F2 development flows currently enabled and supported in the development kit.

Development Environment Description Accelerator Language Hardware Interface Debug Options Typical Developer
Hardware accelerator development using Vivado (HDK) This environment supports the Hardware Development Kit (HDK) design flow, which empowers FPGA developers to create accelerator designs from scratch, using HDL source code and IPs. The AMD Vivado tool synthesizes, implements, and generates the Design Check Point (DCP) file used in F2 AFI creation. AWS FPGA developers benefit from the suite of scripts supplied in the HDK that help to automate different design steps. This allows for flexibility in architecting, implementing, and optimizing accelerator designs while using the HDK. Verilog/System Verilog/VHDL User-implemented DMA engine or Streaming Data Engine (SDE) Simulation, Virtual JTAG Hardware developers with advanced FPGA experience
Hardware accelerator development using Vitis This environment supports the Vitis design flow, which enables software developers to write C++ code, which may then be compiled into RTL and used in cycle-accurate hardware simulation. After it may then be built into an accelerator design. This step is not necessary, but is encouraged. Vitis may also be used to implement accelerator designs from scratch, using HDL and IPs directly, similar to Vivado. Vitis offers additional analysis tools to aid in the refinement of designs. Verilog/System Verilog/VHDL XDMA Engine (coming soon) Hardware Emulation Advanced software developers or hardware developers with intermediate to advanced FPGA experience
Hardware accelerator development using Vivado IP Integrator (IPI) and High Level Design (HLx) This environment supports the Vivado high-level design flow using IP integrator in the GUI. Block Design in IP Integrator AWS IP for HLx Simulation, Virtual JTAG Hardware developers with intermediate FPGA experience
On-premise environment Customers can set up a on-premise development (with licensing requirements listed) environment for supported AMD tool versions..

Quick Start Links

Development Environment Example Description Quick Start Guide Resources
HDK cl_mem_perf Demonstrates fine-tuned paths to memory to maximize bandwidth Guided Example Design Spec
Design Source Code
Testbench
Runtime Software
cl_dram_hbm_dma Demonstrates connectivity to various internal interfaces from the shell Design Spec
Design Source
Testbench
Runtime Software
cl_sde Demonstrates the use of the Streaming Data Engine (SDE) via the Virtual Ethernet Application Design Spec
Design Source
Testbench
Runtime Software
Vitis hello_world Demonstrates streaming to the FPGA rather than block transferring Guided Example Design Spec
Design Source
Testbench
Runtime Software
HLx hello_world_hlx Demonstrates simple register peek and poke using GPIO and VLED Vivado IPI Setup Guide Design Spec
Testbench
Runtime Software
hello_world_mb_hlx Demonstrates integrating MicroBlaze soft processor in HLx design Design Spec
Testbench
Runtime Software
cl_ipi_cdma_test_hlx Demonstrates direct memory access to the DDR and HBM in AWS IP Design Spec
Testbench
Runtime Software

AWS Shells

For AWS EC2 F2 FPGA instances, each FPGA is divided into two partitions:

  • Shell (SH) – AWS platform logic implementing system management and external peripherals like PCIe and interrupts to the host.
  • Custom Logic (CL) – Custom acceleration logic created by the FPGA developer and equipped with direct memory access (DMA) to DDR and HBM.

At the end of the development process, combining the Shell and CL creates an Amazon FPGA Image (AFI) that is then available to load onto all F2 FPGA cards on instances owned by the developer.

The HDK design flow currently supports the Small Shell. The Small Shell offers 88% usable FPGA resources. The common interface (is defined in cl_ports.vh) along with the floorplans and built-in functions. CL designs must integrate with the small shell. The table below details the released shell version and its main features.

Shell Name Shell Version Description
F2 Small Shell 0x10212415 Shell with no built-in DMA engine (40% smaller shell footprint).

Hardware Development Kit (HDK)

The Hardware Development Kit (HDK) comes with an hdk_setup.sh script to set up environment variables required for customer design development using HDL source code.

The HDK directory structure contains:

  • common/shell_stable: All build scripts, constraints, and other directory structures required to support design builds using the supported shells.
  • common/lib: All common IPs used in various examples and Tcl scripts to build IPs are available here.
  • cl/examples: Multiple CL examples to demonstrate connectivity between CL logic, the F2 Shell, and accelerator resources like DDR and HBM.
  • Support for 3rd party simulators

The HDK currently supports the following tool versions:

AMD Vivado Design Suite Synopsys VCS (Bring your own license) Siemens Questa (Bring your own license)
2025.2 X-2025.06-SP1 2025.2_2
2025.1 W-2024.09-SP1 2024.3_3
2024.2 V-2023.12-SP1 2024.1_2
2024.1 U-2023.03-SP2 2023.3

Our scripts require a minimum Python version of 3.10, under /usr/bin/env python3:

Tool Minimum Version
Python 3.10+

Software-Defined Development Environment

The software-defined development environment allows customers to compile their C/C++/OpenCL code into AFIs and use C/C++/OpenCL APIs to interface with the accelerator, running on the FPGA. Software developers with little or no FPGA experience will be able to quickly familiarize themselves with the development experience that accelerates cloud applications. The optimized compiler, Vitis, allows easy F2 accelerator development using C/C++/OpenCL and/or Verilog/VHDL.

Currently, the F2 developer kit provides development tools for Vitis hardware emulation.

To get started, please see the README for a hello world accelerator example

FPGA Developer AMI

A free-to-use FPGA developer AMI is available for on-cloud F2 development with AMD tools pre-installed on a variety of AWS EC2 instance types. Customers can use this AMI to design, simulate, and build their designs. The table below lists the FPGA Developer AMI(s) currently released to customers:

FPGA Developer AMI Version FPGA Developer AMI ID (us-east-1) Vivado/Vitis Version Supported Operating System Version
1.19.1 ami-07c259dae738189ec 2025.2 Ubuntu 24.04 (kernel 6.8.0-1021-aws)
1.19.1 ami-039f2d1d9952ef402 2025.2 Rocky Linux 8.10 (4.18.0-553.36.1.el8_10.x86_64)
1.16.1 ami-092fc5deb8f3c0f7d 2024.1 Ubuntu 20.04.6 (kernel 5.15)

Given the large size of the FPGA used for F2, AMD tools work best with at least 4 vCPU’s and 32GiB Memory. We recommend Compute Optimized and Memory Optimized instance types to successfully run the synthesis of acceleration code. Developers may start coding and run simulations on low-cost General Purpose instances types.

Note that the tools used by the HDK are only supported on x86-based EC2 instances (Graviton-based instances are not compatible with the tools).

For long-term cost savings when evaluating or debugging an accelerator in hardware, we recommend creating a runtime AMI using the Runtime AMI Builder (RAB). The RAB is a customizable and extensible tool based on the AWS CDK that easily automates building production-ready AMIs tailored to each accelerator application's needs.

Getting Familiar with AWS

If you have never used AWS before, we recommend you start with AWS getting started training, focusing on the basics of the AWS EC2 and AWS S3 services. Understanding the fundamentals of these services will further enhance the developer experience with AWS F2 instances and the FPGA Developer Kit.

Next Steps

Once developers are familiar with the F2 development kit and the HDK development environment, we recommend exploring all the design features and examples offered in the AWS EC2 FPGA Development Kit:

  1. Get Started: Follow the step-by-step quickstart guide for customer hardware development before creating your own AWS FPGA design

  2. Learn by Example: Explore CL examples to understand shell-to-CL connectivity, memory interfaces (DDR & HBM), and the CL clock generation block

  3. Create Your Design: Use the CL_TEMPLATE example as a starting point

    • Review the shell floorplan and locations of major shell interfaces.
    • Connect to debug cores within a custom FPGA CL design through the Virtual JTAG interface to debug hardware issues.