smitha-xilinx / aws-fpga

Official repository of the AWS EC2 FPGA Hardware and Software Development Kit

Table of Contents

1. AWS EC2 FPGA Hardware and Software Development Kits
   • FPGA Hardware Development Kit Workflow(HDK)
   • GUI Workflow with Vivado IP Integrator (IPI)
   • FPGA Software Development Kit (SDK)
   • FPGA Developer AMI available on AWS Marketplace
   • Developer Support
2. Building an example AFI
   • Prerequisites
   • Using an AFI on EC2 FPGA Instances

AWS EC2 FPGA Hardware and Software Development Kits

The AWS EC2 FPGA Hardware and Software Development Kits include two portions: Development workflows for developing Amazon FPGA Image (AFI) with the HDK or the GUI workflow, and SDK for using AFIs on FPGA-enabled EC2 instances such as F1.

Execute git clone https://github.com/aws/aws-fpga.git to download this HDK+SDK release to your EC2 Instance or local server. For an SSH connection execute git clone [email protected]:aws/aws-fpga.git. To get help with connecting to Github via SSH

The Release Notes document covers the list of supported features, programming environments, and known restrictions.

NOTE: The HDK and SDK are tested and supported for Linux operating systems, for the time being, other OSs haven't been tested by AWS

Please click the "Watch" button in GitHub upper right corner to stay posted.

FPGA HDK

The HDK directory contains useful information and scripts for developers wanting to start building Amazon FPGA Images (AFI). It includes the development environment, simulation, build and AFI creation scripts. The HDK can be installed on any on-premises server or an EC2 instance. The HDK is not required if you are using a pre-built AFI and not planning to build your own AFI. The following resources provide further details:

HDK README

AWS FPGA Shell Interface Specification

FPGA PCIe Address Map

GUI Workflow with Vivado IP Integrator (IPI)

Developers have the option of working in a GUI mode using Vivado IPI. With IPI you can create complex F1 custom designs on a graphical interface design canvas. The HDK development kit provides AWS FPGA IP which will help you quickly develop your custom designs by enabling you to quickly drop in IP blocks into your design.

The IPI flow isolates the Custom Logic (CL) from the shell, allowing the developer to focus on differentiating logic and leave the heavy lifting, undeferentiated hardware interfaces development to the AWS FPGA Shell. Generating a logic diagram is simplified with designer automation that connects RTL, IP, and peripherals like DDR and PCIe in a correct by construction flow. The “what you see is what you get” tool generates the equivalent code by instantiating the underlying IP and RTL with access via the Vivado project to the entire FPGA hardware design flow. A video walk through of this flow for a simple diagram is available at https://www.xilinx.com/video/hardware/using-vivado-ip-integrator-and-amazon-f1.html. This flow example is a good starting point for developers who want to quickly add IP blocks with high performance access to multiple external memories.

The IPI RTL flow enables the developer a single graphical environment to add sources and IP, simulate, synthesize the RTL, and then stitch together the Custom Logic (CL) with the Shell’s design checkpoint (DCP). For design debug, developers can easily instantiate logic analyzers or other debug logic, investigate timing and resource reports, and quickly link from implementation messages to the design view and source code when applicable. This flow is a good starting point for experts in RTL design or designs who have a minimal amount of interconnection between RTL modules.

The below documentation covers the setup, tutorials of the IPI flows and IPI FAQ. Developers are advised to read all documents before starting thier first AWS FPGA design with IPI.

IPI Setup

IPI Tutorials/Examples

IPI Developer Flow

IPI FAQ

FPGA SDK

The SDK directory includes the runtime environment required to run on EC2 FPGA instances. It includes the drivers and tools to manage the AFIs that are loaded to EC2 FPGA instance slots. The SDK isn't required during the AFI development process; it is only required once an AFI is loaded onto an EC2 FPGA instance. The following resources provide further details:

SDK README

Access FPGA From Linux Applications

AFI Management Tools

FPGA Developer AMI

AWS Marketplace offers the FPGA developer AMI for development on EC2 instances. The FPGA Developer AMI comes with Xilinx tools and AWS CLI pre-installed. The HDK examples and quick start can be run on any C4/M4/R4/T2.2XLARGE EC2 instance. Given the large size of the FPGA used in AWS FPGA instances, the implementation tools require 32GiB Memory (C4.4XLarge, M4.2XLarge, R4.XLarge, T2.2XLarge). C4.4XLarge and C4.8XLarge would provide the fastest execution time with 30 and 60GiB of memory respectively.

Developer Support

The Amazon FPGA Development User Forum is the first place to go to post questions, learn from other users and read announcements from the EC2 FPGA team.

• To be notified on important messages click on the “Watch Forum” button on the right side of the screen.
• In case you can't see "Your Stuff" details, you will need to logout using the logout button on the forums page and log back in again.

Building a Custom Logic AFI for AWS FPGA Instances

Developers can build their own Custom Logic (CL) and deploy it on AWS. The CL must comply with the AWS Shell Interface Specifications, and pass through the build scripts.

The CL Examples directory is provided to assist developers in creating a functional CL implementation. Each example includes:

1. The source code for the example under the /design directory.
2. The timing, clock and placement constraints files, scripts for compiling the example design. (This requires running in an instance/server that have Xilinx tools and license installed. Developers are recommended to use the FPGA Development AMI available free of charge on AWS Marketplace).
3. The final build, called Design Checkpoint (DCP) that can be submitted for AWS to generate the AFI.
4. An AFI-ID for a pre-generated AFI that matches the example design.
5. Software source code required on the FPGA-enabled instance to run the example.
6. Software binary that can be loaded on an FPGA-enabled instance to test the AFI.

In summary:

• An AFI can be created using the files in #1, #2, and #3. The AFI creation can take place on any EC2 instance or on-premises.
• The AFI can be used in an EC2 F1 instance by using the files in #4, #5 and #6.

By following the example CLs, a developer will learn how to interface to the AWS Shell of the FPGA, compile the source code to create an AFI, and load/run an AFI from the F1 instance for use.

Prerequisites

• AWS FPGA HDK and SDK run in Linux environment only.

• The build stage uses Xilinx's Vivado tool set. In case you build on-premises you should have an installed Vivado that has the correct license. Please check for supported versions of Vivado. Release Notes may contain additional information.

• Executing aws s3 <action> and aws ec2 create-fpga-image require having AWS CLI installed, having an active AWS account, and the server/instance has been configured with your credentials and the same AWS region as your S3 bucket via aws configure command line. It’s also required that your instance and the S3 bucket where the tarball reside in will be in the same AWS region. Please refer to AWS documentation for help with configuring the AWS CLI.

The Getting started with CL examples guide provides step-by-step instructions to build an AFI from one of the provided examples, register it with AWS, and load it on an EC2 FPGA instance.

Using an AFI on EC2 FPGA Instances

Now that you have built an AFI, or if you want to use one of the example pre-built AFIs provided by AWS, you need to launch an EC2 FGPA Instance, and install the SDK as detailed at: SDK Quick Start