# Quick Start Guide to Accelerating your C/C++ application on an AWS F1 FPGA Instance with Vitis
There are three steps for accelerating your application on an Amazon EC2 FPGA instance using the software-defined development flow:
1. Build the host application, and the Xilinx FPGA binary
2. Create an AFI
3. Run the FPGA accelerated application on AWS FPGA instances
This quick start guide will utilize a simple "Hello World" Vitis example to get you started.
It is highly recommended you read the documentation and utilize software and hardware emulation prior to running on F1.
The F1 HW Target compile time is ~50 minutes, therefore, software and hardware emulation should be used during development.
# Table of Content
1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
* [AWS Account, F1/EC2 Instances, On-Premises, AWS IAM Permissions, AWS CLI and S3 Setup](#iss)
* [Github and Environment Setup](#gitsetenv)
3. [Build the host application, Xilinx FPGA binary and verify you are ready for FPGA acceleration](#createapp)
* [Emulate the code](#emu)
* [Software Emulation](#swemu)
* [Hardware Emulation](#hwemu)
* [Build the host application and Xilinx FPGA Binary](#hw)
4. [Create an Amazon FPGA Image (AFI)](#createafi)
5. [Run the FPGA accelerated application on F1](#runonf1)
6. [Additional Vitis Information](#read)
# Overview
* Vitis is a complete development environment for applications accelerated using Xilinx FPGAs
* It leverages the OpenCL heterogeneous computing framework to offload compute intensive workloads to the FPGA
* The accelerated application is written in C/C++, OpenCL or RTL with OpenCL APIs
# Prerequisites
## AWS Account, F1/EC2 Instances, On-Premises, AWS IAM Permissions, AWS CLI and S3 Setup (One-time Setup)
* [Setup an AWS Account](https://aws.amazon.com/free/)
* Launch an instance using the [FPGA Developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) which comes pre-installed with Vitis and required licenses.
* You may use this F1 instance to [build your host application and Xilinx FPGA binary](#createapp), however, it is more cost efficient to either:
* Launch the [FPGA Developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) on a compute EC2 instance, with a minimum of 30GiB RAM), **OR**
* Follow the [On-Premises Instructions](../docs/on_premise_licensing_help.md) to purchase and install a license from Xilinx.
* Setup AWS IAM permissions for creating FPGA Images (CreateFpgaImage and DescribeFpgaImages). [EC2 API Permissions are described in more detail](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/ec2-api-permissions.html). It is highly recommended that you validate your AWS IAM permissions prior to proceeding with this quick start. By calling the [DescribeFpgaImages API](../hdk/docs/describe_fpga_images.md) you can check that your IAM permissions are correct.
* [Setup AWS CLI and S3 Bucket](docs/Setup_AWS_CLI_and_S3_Bucket.md) to enable AFI creation.
* Install optional [packages](packages.txt) required to run all examples. If you do not install these packages, some examples may not work properly. The setup scripts will warn you of any missing packages.
* Additional dependencies may get flagged during the AWS Vitis scripts as warnings or errors.
## Github and Environment Setup
* Clone this github repository and source the *vitis_setup.sh* script:
```
$ git clone https://github.com/aws/aws-fpga.git $AWS_FPGA_REPO_DIR
$ cd $AWS_FPGA_REPO_DIR
$ source vitis_setup.sh
```
* Sourcing the *vitis_setup.sh* script:
* Downloads and sets the correct AWS Platform:
* AWS Vitis Platform that contains the dynamic hardware that enables Vitis kernels to run on AWS F1 instances.
* Valid platforms for shell_v04261818: `AWS_PLATFORM_201920_3` (Default) AWS F1 Vitis platform.
* Sets up the Xilinx Vitis example submodules.
* Installs the required libraries and package dependencies.
* Run environment checks to verify supported tool/lib versions.
# 1. Build the host application, Xilinx FPGA binary and verify you are ready for FPGA acceleration
This section will walk you through creating, emulating and compiling your host application and FPGA Binary
# Emulate your Code
The main goal of emulation is to ensure functional correctness and to determine how to partition the application between the host CPU and the FPGA.
HW/SW Emulation does not require use of actual FPGA's and can be run on any compute instances. Using non-F1 EC2 compute instances for initial development will help reduce costs.
## Software (SW) Emulation
For CPU-based (SW) emulation, both the host code and the FPGA binary code are compiled to run on an x86 processor.
SW Emulation enables developers to iterate and refine the algorithms through fast compilation.
The iteration time is similar to software compile and run cycles on a CPU.
The instructions below describe how to run the Vitis SW Emulation flow using the Makefile provided with a simple "hello world" example
```
$ cd $VITIS_DIR/examples/xilinx/hello_world
$ make clean
$ make run TARGET=sw_emu DEVICE=$AWS_PLATFORM all
```
For more information on how to debug your application in a SW Emulation environment.
## Hardware (HW) Emulation
The Vitis hardware emulation flow enables the developer to check the correctness of the logic generated for the FPGA binary. This emulation flow invokes the hardware simulator in the Vitis environment to test the functionality of the code that will be executed on the FPGA Custom Logic.
The instructions below describe how to run the HW Emulation flow using the Makefile provided with a simple "hello world" example:
```
$ cd $VITIS_DIR/examples/xilinx/hello_world
$ make clean
$ make run TARGET=hw_emu DEVICE=$AWS_PLATFORM all
```
For more information on how to debug your application in a HW Emulation environment.
# Build the Host Application and Xilinx FPGA Binary
The Vitis system build flow enables the developer to build their host application as well as their Xilinx FPGA Binary.
The instructions below describe how to build the Xilinx FPGA Binary and host application using the Makefile provided with a simple "hello world" example:
```
$ cd $VITIS_DIR/examples/xilinx/hello_world
$ make clean
$ make TARGET=hw DEVICE=$AWS_PLATFORM all
```
NOTE: If you encounter an error with `No current synthesis run set`, you may have previously run the [HDK IPI examples](../hdk/docs/IPI_GUI_Vivado_Setup.md) and created a `Vivado_init.tcl` file in `~/.Xilinx/Vivado`. This will cause [problems](https://forums.aws.amazon.com/thread.jspa?threadID=268202&tstart=25) with the build process, thus it is recommended to remove it before starting a hardware system build.
# 2. Create an Amazon FPGA Image (AFI)
*The Vitis Flow only supports AFI's created with Device ID 0xF010 and Vendor ID 0x1D0F.*
The runtime drivers are designed to only bind to 0xF010 and 0x1042(Cleared AFI) and loading AFI's from your application that provide other Device/Vendor ID's will require restarting the Xilinx MPD.
This assumes you have:
* [Compiled your host application and Xilinx FPGA Binary](#hw)
* Validated your code using [SW/HW Emulation](#emu) and you are ready to create an AFI and test on F1.
* [Setup AWS CLI and S3 bucket](docs/Setup_AWS_CLI_and_S3_Bucket.md) for AFI creation
The [create_vitis_afi.sh](./tools/create_vitis_afi.sh) script is provided to facilitate AFI creation from a Xilinx FPGA Binary, it:
* Takes in your Xilinx FPGA Binary \*.xclbin file
* Calls *aws ec2 create_fpga_image* to generate an AFI under the hood
* Generates a \