1. Quick Start
2. Overview of AWS EC2 FPGA Development Kit
   • Development environments
   • Runtime environments
   • Example applications
   • Development tools
3. Getting Started
4. FPGA Developer AMI available on AWS Marketplace
5. FPGA Hardware Development Kit (HDK)
6. FPGA Software Development Kit (SDK)
7. OpenCL Development Environment with Amazon EC2 F1 FPGA Instances to accelerate your C/C++ applications
8. Developer Support
9. Recommended Documentation
10. Github tips and tricks

git clone git@github.com:amsharifian/dandelion-aws.git
cd dandelion-aws
source sdk_setup.sh
source hdk_setup.sh
cd hdk/cl/developer_designs/cl_dandelion_acc/
export CL_DIR=$(pwd)

# For SW/HW co-simulation
cd verify/scripts
make C_TEST=test_dandelion_hwsw_cosim AXI_MEMORY_MODEL=1

# For Building HW Image
cd build/scripts
export EMAIL=your.email@example.com
$AWS_FPGA_REPO_DIR/shared/bin/scripts/notify_via_sns.py
./aws_build_dcp_from_cl.sh -notify
cd ../checkpoints/to_aws/
aws s3 cp 20_03_29-233820.Developer_CL.tar s3://dandelion-aws/dcp/
aws ec2 create-fpga-image --name dandelion_accel --description "dandelion with dcr and dme" --input-storage-location Bucket=dandelion-aws,Key=dcp/20_03_29-233820.Developer_CL.tar --logs-storage-location Bucket=dandelion-aws,Key=log/LOGS_FILES_GO_HERE.txt
aws ec2 describe-fpga-images  --fpga-image-ids "afi-0de9dd5ccb760a5d8"

The AWS EC2 FPGA Development Kit is provided by AWS to support development and runtime on AWS FPGA instances. Amazon EC2 FPGA instances are high-performance compute instances with field programmable gate arrays (FPGAs) that are programmed to create custom hardware accelerations in EC2. F1 instances are easy to program and AWS provides everything needed to develop, simulate, debug, compile and run hardware accelerated applications. Using the FPGA Developer AMI, developers create an FPGA design. Once the FPGA design (also called CL - Custom logic) is complete, developers create the Amazon FPGA Image (AFI), and easily deploy it to the F1 instance. AFIs are reusable, shareable and can be deployed in a scalable and secure way.

NOTE: For on-premises development, SDx/Vivado must have the correct license and use one of the supported versions of SDx/Vivado. The FPGA HDK+SDK Release Notes may contain additional information. The following links have more information on on-premises development: Vivado requirements and SDx requirements

If you have never used AWS before, we recommend you start with AWS getting started training, and focus on the basics of the AWS EC2 and AWS S3 services. Understanding the fundamentals of these services will make it easier to work with AWS FPGAs.

AWS FPGA generation and EC2 F1 instances are supported in the us-east-1 (N. Virginia), us-west-2 (Oregon), eu-west-1 (Ireland) and us-gov-west-1 (GovCloud US) regions.

The developer kit is supported for Linux operating systems only. You have the choice to develop on AWS EC2 using the FPGA Developer AMI or on-premises. Within a linux environment, you can execute git clone https://github.com/aws/aws-fpga.git to download the latest release to your EC2 Instance or local server. Help on cloning from github is available here. When using a SSH connection, execute git clone git@github.com:aws/aws-fpga.git. To get help with connecting to Github via SSH.

To setup your instance for development, checkout our Developer Resources where we provide Step-By-Step guides to setting up a GUI Desktop or a compute cluster.

Before you start your first AWS FPGA design, we recommend that you go through one of the step-by-step guides. The guides will walk through development steps for hello world examples. Based on the tables above, pick the development environment that best fits your needs and use the guide to get started:

• For fastest way to get started on FPGA accelerator development, start with the software defined development environment. The guide starts with the SW Hello World example.
  • Next use the same guide to develop using the C/C++/openCL/RTL based 80+ examples on github.
• For custom hardware development (HDK) environment, start with the HDK Hello World example.
  • Next use the same guide to develop using the cl_dram_dma.

Once you have completed your hello world examples, we recommend diving deeper into a training workshop or application notes

• Software-defined re:Invent 2019 Workshop.
  • Lab modules will take you through accelerating compute intensive functions like Inverse Discrete Cosine Transform, Bloom Filter, 2D video convolution, etc.
  • You will learn how to identify functions to accelerate and use profiling on example applications use that information to optimize your data movement between the HOST and FPGA.
• Software-defined re:Invent 2018 Workshop demonstrates a 2D Filter acceleration and how to debug and optimize your accelerator.
• Custom hardware developers need to learn about how the hardware accelerator interfaces to the F1 Shell
• Shell Interface
• Shell Address Map
• Programmer view of the FPGA
• Virtual JTAG
• Application for methods of interfacing the host application to the Hardware accelerator

The FPGA Developer AMI is available on the AWS marketplace without a software charge and includes free tools and drivers needed for FPGA development on EC2 instances. FPGA development runs on several EC2 instance types. Given the large size of the FPGA used inside the AWS FPGA instances, the implementation tools require 32GiB Memory (ex: z1d.xlarge, z1d.2xlarge, c5.4xlarge, m5.2xlarge, r5.xlarge, t2.2xlarge). z1d.xlarge/c5.4xlarge and z1d.2xlarge/c5.8xlarge would provide the fastest execution time with 30GiB+ and 60GiB+ of memory respectively. Developers who want to save on cost, could start coding and run simulations on low-cost instances, like t2.2xlarge, and move to the aforementioned larger instances to run the synthesis of their acceleration code.

Currently, AWS marketplace includes multiple versions of the FPGA Developer AMI, supporting Xilinx SDx 2017.4, 2018.2, 2018.3 and 2019.1 toolchain versions. The following compatibility table describes the mapping of currently supported developer kit versions to AMI versions:

Developer kit versions prior to v1.3.7 and Developer AMI prior to v1.4 (2017.1) reached end-of-life. See AWS forum announcement for additional details.

If developing using SDAccel environment please refer to this Runtime Compatibility Table

The HDK directory contains useful information, examples, 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 developer kit is not required if you plan to use a pre-built AFI shared from another developer.

The software-defined development environment allows customers to compile their C/C++/OpenCL code into the FPGA as kernels, and use OpenCL APIs to pass data to the FPGA. Software developers with no FPGA experience will find a familiar development experience that supercharges cloud applications.

In addition, this development environment (also called SDAccel) allows the mix of C/C++ and RTL accelerator designs into a C/C++ software based development environment. This method enables faster prototyping using C/C++ while supporting manual optimization of critical blocks within RTL. This approach is similar to optimizing time critical functions using software compiler optimization methods.

This developer kit has 80+ examples to help you get started on FPGA acceleration. To get started, review the Software-defined development environment readme.

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 on the FPGA instance. 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 sdk resources are provided:

• Linux Kernel Drivers - The developer kit includes three drivers:
  • XDMA Driver - DMA interface to/from HDK accelerators.
  • XOCL Driver - DMA interface with software defined accelerators (also called hardware kernels).
• FPGA Libraries - APIs used by C/C++ host applications.
• FPGA Management Tools - AFI management APIs for runtime loading/clearing FPGA image, gathering metrics and debug interface on the F1 instance.

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.

• Click the "Watch" button in GitHub upper right corner to get regular updates.
• We recommend you will join the AWS forum to engage with the FPGA developer community and get help when needed (both AWS and Xilinx engineers monitor this forum).
• 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.

The documentation is located throughout this developer kit, therefore, to help developers find information quicker the table below consolidates a list of key documents:

• Cloning the repository
• Forking the repository
• Searching code and advanced search syntax
• Finding files
• Simply replace github.com with gitprint.com to generate a printable PDF