Skip to content

Latest commit

 

History

History
218 lines (163 loc) · 12.3 KB

README.md

File metadata and controls

218 lines (163 loc) · 12.3 KB
Raw

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
  2. Prerequisites
  3. Build the host application, Xilinx FPGA binary and verify you are ready for FPGA acceleration
  4. Create an Amazon FPGA Image (AFI)
  5. Run the FPGA accelerated application on F1
  6. Additional Vitis Information

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)

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_2 (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 and created a Vivado_init.tcl file in ~/.Xilinx/Vivado. This will cause problems 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:

The 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 <timestamp>_afi_id.txt which contains the identifiers for your AFI
  • Creates an AWS FPGA Binary file with an *.awsxclbin extension that is composed of: Metadata and AGFI-ID.
    • This *.awsxclbin is the AWS FPGA Binary file that will need to be loaded by your host application to the FPGA
    $ $VITIS_DIR/tools/create_vitis_afi.sh -xclbin=<input_xilinx_fpga_binary_xclbin_filename>
		-o=<output_aws_fpga_binary_awsxclbin_filename_root> \
		-s3_bucket=<bucket-name> -s3_dcp_key=<dcp-folder-name> -s3_logs_key=<logs-folder-name>

Save the *.awsxclbin, you will need to copy it to your F1 instance along with your executable host application.

NOTE: Attempting to load your AFI immediately on an F1 instance will result in an 'Invalid AFI ID' error. Please wait until you confirm the AFI has been created successfully.

Refer to FAQ for details.

Tracking the status of your registered AFI

The *_afi_id.txt file generated by the create_vitis_afi.sh also includes the two identifiers for your AFI:

  • FPGA Image Identifier or AFI ID: this is the main ID used to manage your AFI through the AWS EC2 CLI commands and AWS SDK APIs. This ID is regional, i.e., if an AFI is copied across multiple regions, it will have a different unique AFI ID in each region. An example AFI ID is afi-06d0ffc989feeea2a.
  • Global FPGA Image Identifier or AGFI ID: this is a global ID that is used to refer to an AFI from within an F1 instance. For example, to load or clear an AFI from an FPGA slot, you use the AGFI ID. This is embedded into the AWS FPGA Binary *.awsxclbin file generated by create_vitis_afi.sh. Since the AGFI IDs is global (by design), it allows you to copy a combination of AFI/AMI to multiple regions, and they will work without requiring any extra setup. An example AGFI ID is agfi-0f0e045f919413242.

Use the describe-fpga-images API to check the AFI state during the background AFI generation process.

    $ aws ec2 describe-fpga-images --fpga-image-ids <AFI ID>

When AFI creation completes successfully, the output should contain:

    ...
    "State": {
        "Code": "available"
    },
    ...

If the “State” code indicates the AFI generation has "failed", the AFI creation logs can be found in the bucket location (s3://<bucket-name>/<logs-folder-name>) provided to create_vitis_afi.sh above. These will detail the errors encountered during the AFI creation process.

For help with AFI creation issues, see create-fpga-image error codes

3. Run the FPGA accelerated application on Amazon FPGA instances

  • Start an FPGA instance using FPGA Developer AMI on AWS Marketplace and check the AMI compatibility table and runtime compatibility table. Alternatively, you can create your own Runtime AMI for running your Vitis applications on Amazon FPGA instances.

  • To setup tools, runtime environment & execute your Host Application:

    $ git clone https://github.com/aws/aws-fpga.git $AWS_FPGA_REPO_DIR
$ cd $AWS_FPGA_REPO_DIR
$ source vitis_runtime_setup.sh   # Other runtime env settings needed by the host app should be setup after this step
# Wait till the MPD service has initialized. Check systemctl status mpd
$ ./hello_world ./vadd.awsxclbin

  • The runtime setup script also starts the Xilinx XRT Message Proxy Daemon(MPD) service. To learn more about the XRT implementation, check the XRT Instructions

Additional Vitis Information