Skip to content

Latest commit

 

History

History
257 lines (193 loc) · 16.1 KB

README.md

File metadata and controls

257 lines (193 loc) · 16.1 KB
Raw

Quick Start Guide to Accelerating your C/C++ application on an AWS F1 FPGA Instance with SDAccel

There are three simple steps for accelerating your application on an AWS F1 instance:

  1. Build the host application, Xilinx FPGA binary and verify you are ready for FPGA acceleration
  2. Create an AFI
  3. Run the FPGA accelerated application on AWS FPGA instances

❗ NOTE: If you would like to directly go to step 3 to experience how to execute your application on F1 instance Please read Helloworld OpenCL Runtime example

This quick start guide will use a simple "Hello World" SDAccel 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 compile time is ~4hrs (4DDR) and ~1hr (1DDR), therefore, software and hardware emulation should be used during development.

It is highly recommended you read the documentation and utilize software and hardware emulation prior to running on F1. The F1 HW compile time is ~4hrs (4DDR) and ~1hr (1DDR), therefore, software and hardware emulation should be used during development.

It is highly recommended you read the documentation and utilize software and hardware emulation prior to running on F1. The F1 HW compile time is ~4hrs (4DDR) and ~1hr (1DDR), 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 SDAccel Information

Overview

  • SDAccel is a complete development environment for applications accelerated with 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++ with OpenCL APIs
  • The code for the FPGA binary can be written in C/C++, OpenCL or RTL
  • Once you have gone through this quick start example. See the SDAccel GUI Guide to access the fully integrated Eclipse-based environment with built-in debug, profiling and performance analysis tools.

Prerequisites

AWS Account, F1/EC2 Instances, On-Premises, AWS IAM Permissions, AWS CLI and S3 Setup (One-time Setup)

  • Setup an AWS Account
  • Launch an instance using the FPGA Developer AMI which comes pre-installed with SDAccel and required licenses.
    • This release supports Xilinx SDx 2017.4 and 2017.1. The compatibility table describes the mapping of developer kit version to FPGA developer AMI version:
Developer Kit Version Tool Version Supported Compatible FPGA developer AMI Version
1.3.0-1.3.6 2017.1 v1.3.5
1.3.7-1.3.X 2017.1 v1.3.5-v1.3.X (Xilinx SDx 2017.1)
1.3.7-1.3.X 2017.4 v1.4.0-v1.4.X (Xilinx SDx 2017.4)

Github and Environment Setup (Once per new instance or machine)

  • Clone this github repository and source the sdaccel_setup.sh script. This will take care of:

    • Downloading the required files:
      • AWS Platform that allows Xilinx FPGA Binary files to target AWS F1 instances
      • AFI Creation script that generates an AFI and AWS FPGA Binary from a Xilinx FPGA Binary
      • SDAccel HAL source code and binary files for mapping SDAccel/OpenCL runtime libraries to AWS FPGA instance.
      • Installing the required libraries and drivers
        $ git clone https://github.com/aws/aws-fpga.git $AWS_FPGA_REPO_DIR  
    $ cd $AWS_FPGA_REPO_DIR                                         
    $ source sdaccel_setup.sh
    • Depending on the Xilinx SDx tool version that is being used a default platform will be selected. This section describes the valid platforms for each support tool version.
      • Xilinx Tool 2017.1 Platforms:
        • AWS_PLATFORM_4DDR - (Default) AWS F1 platform with 4 DDRs and profiling support. Optimized for multi DDR use cases. This platform should be used for all production applications which require more than 1 DDR bank.
        • AWS_PLATFORM_4DDR_DEBUG - This platform is a debug variant of the 4DDR platform and should be used for hardware debugging of kernels. This version consists of an additional debug feature which allows advanced users to insert ILA’s in the kernels for debugging purposes. All other features are identical to the AWS_PLATFORM_4DDR platform.
        • AWS_PLATFORM_1DDR - This platform consist of 1 DDR that is located in the shell region. This allow maximum space for kernels. This also allows much faster compile times for all the use cases which require only 1 DDR bank. This platform does not support APM and hence no profiling data can be obtained.
      • Xilinx Tool 2017.4 Platform:
        • AWS_PLATFORM_DYNAMIC_5_0 - (Default) AWS F1 platform dynamically optimized for multi DDR use cases.

  • Changing to a different platform can be accomplished by setting the AWS_PLATFORM environment variable. Example:  

        $ export AWS_PLATFORM=$AWS_PLATFORM_1DDR

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.

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. The SW Emulation enables developer 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 SDAccel SW Emulation flow using the Makefile provided with a simple "hello world" example

    $ cd $SDACCEL_DIR/examples/xilinx/getting_started/host/helloworld_ocl/          
    $ make clean                                                                 
    $ make check TARGETS=sw_emu DEVICES=$AWS_PLATFORM all

For more information on how to debug your application in a SW Emulation environment, please see the SDAccel Debug Guide.

Hardware (HW) Emulation

The SDAccel 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 SDAccel 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 $SDACCEL_DIR/examples/xilinx/getting_started/host/helloworld_ocl/             
    $ make clean                                                                   
    $ make check TARGETS=hw_emu DEVICES=$AWS_PLATFORM all

For more information on how to debug your application in a HW Emulation environment, please see the SDAccel Debug Guide.

Build the Host Application and Xilinx FPGA Binary

The SDAccel 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 $SDACCEL_DIR/examples/xilinx/getting_started/host/helloworld_ocl/           
    $ make clean                                                             
    $ make TARGETS=hw DEVICES=$AWS_PLATFORM all

Now that you have built your Xilinx FPGA binary, see SDAccel Power Analysis Guide for more details on how to analyze power for your binary.

2. Create an Amazon FPGA Image (AFI)

This assumes you have:

The create_sdaccel_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_fgpa_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
    $ $SDACCEL_DIR/tools/create_sdaccel_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 FPGA Binary immediately on an F1 instance will result in an 'Invalid AFI ID' error. Please wait until you confirm the AFI has been created successfully.

Tracking the status of your registered AFI

The *_afi_id.txt file generated by the create_sdaccel_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_sdaccel_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_sdaccel_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 F1

Here are the steps:

  • Start an F1 instance using FPGA Developer AMI on AWS Marketplace and check the AMI compatiability table. Alternatively, you can create your own Runtime AMI for running your SDAccel applications on F1.
    • Assuming the developer flow (compilation) was done on a separate instance you will need to:
      • Copy the compiled host executable (exe) to new instance
      • Copy the *.awsxclbin AWS FPGA binary file to the new instance
      • If using Xilinx SDx 2017.1 and 1DDR platform or 4DDR Rtl kernel debug platform:
        • Depending on the host code, the *.awsxclbin may need to be renamed. Ex: cp vector_addition.hw.xilinx_aws-vu9p-f1_1ddr-xpr-2pr_4_0.awsxclbin vector_addition.hw.xilinx_aws-vu9p-f1_4ddr-xpr-2pr_4_0.awsxclbin
      • Copy any data files required for execution to the new instance
      • Clone the github repository to the new F1 instance and install runtime drivers
    • Clone the github repository to the new F1 instance and install runtime drivers
   $ git clone https://github.com/aws/aws-fpga.git $AWS_FPGA_REPO_DIR
   $ cd $AWS_FPGA_REPO_DIR 
   $ source sdaccel_setup.sh

  • Ensure the host application can find and load the *.awsxclbin AWS FPGA binary file.

  • Source the Runtime Environment & Execute your Host Application (Xilinx SDx 2017.1):

    $ sudo sh
    # source /opt/Xilinx/SDx/2017.1.rte.4ddr/setup.sh   # Use 2017.1.rte.1ddr or 2017.1.rte.4ddr_debug when using AWS_PLATFORM_1DDR or AWS_PLATFORM_4DDR_DEBUG. Other runtime env settings needed by the host app should be setup after this step
    # ./helloworld
  • Source the Runtime Environment & Execute your Host Application (Xilinx SDx 2017.4):
    $ sudo sh
    # source /opt/Xilinx/SDx/2017.1.rte.dyn/setup.sh   # Other runtime env settings needed by the host app should be setup after this step
    # ./helloworld

Additional SDAccel Information (2017.4)