Creating an Amazon FPGA Image (AFI)

This document guides you through the steps to create an AWS Amazon FPGA Image (AFI) which can run on AWS EC2 F1 instance to verify that the design works in hardware. It assumes that a full system (Vitis project) is built which consists of an host application (executable file) and an FPGA binary file (.xclbin).

Create an AFI

AWSEducate users follow these steps to create an AFI

To execute the application on F1, the following files are needed:

The awsxclbin is an Amazon specific version of the FPGA binary file (xclbin) produced by the Vitis software.

The awsxclbin can be created by running the create_vitis_afi.sh script which is included in the aws-fpga GitHub repository.

The script can be found in the following location in the aws-fpga repository:

$VITIS_DIR/tools/create_vitis_afi.sh

Before running the commands below, make sure the Vitis setup script has been sourced (the following command assumes the aws-fpga Git repository is cloned to the user home area)

source ~/aws-fpga/vitis_setup.sh
$VITIS_DIR/tools/create_vitis_afi.sh –xclbin=<filename>.xclbin –s3_bucket=<bucket-name> -s3_dcp_key=<dcp-folder-name> -s3_logs_key=<logs-folder-name>

In the above command, set your xclbin file as <filename>; the Amazon S3 <bucket-name>, <dcp-folder-name>, and <logs-folder-name> with the names you had given when running CLI script. You can choose any valid folder name for the dcp and logs folder. The Amazon S3 bucket name should match an S3 bucket you have set up.

Learn more about setting up S3 buckets here

The create_vitis_afi.sh script does the following:

Check the AFI status

The AFI will become available after some time in the AWS cloud and can then be used to program the FPGA in an AWS EC2 F1 instance. To check the AFI status, the AFI ID is required.

cat *afi_id.txt
aws ec2 describe-fpga-images --fpga-image-ids <AFI_ID>
aws ec2 describe-fpga-images --fpga-image-ids afi-0b9167434a1c74ba9

Or you can use a handy shortcut to pass the AFI id directly to the command. Read the file, get the second row, remove " and , and finally remove everything before the colon included

aws ec2 describe-fpga-images --fpga-image-ids $(cat *afi_id.txt | sed -n '2p' | tr -d '",' | sed 's/.*://')

Note: When AFI creation is in progress, the State will be pending. When the AFI creation is finished, the output should show available:

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

    ...

Wait until the AFI becomes available before proceeding to execute on the F1 instance.

Regenerate .awsxclbin

You can regenerate the .awsxclbin file as long as you have access to *agfi_id.txt and *.xclbin files

  1. Edit these variable with the corresponding names

    export xclbin=<xclbin_filename>
    export agfi_id=<*_agfi_id.txt>
    export awsxclbin=<output_name>
    
  2. Generate .awsxclbin file

    xclbinutil -i $xclbin --remove-section PARTITION_METADATA --remove-section SYSTEM_METADATA --replace-section BITSTREAM:RAW:${agfi_id} -o ${awsxclbin}.awsxclbin
    

Copyright© 2021 Xilinx