Skip to content

Create, configure and test an AWS F1 instance

Jump to bottom
Thomas Bollaert edited this page Nov 11, 2017 · 7 revisions

This module will you through the following steps:

  1. Creating an EC2 instance from the AWS Console
  2. Configuring the instance for working with SDAccel
  3. Connecting to the instance with a Remote Desktop application
  4. Running the SDAccel 'Hello World' example on AWS F1
  5. Closing the session

Important: You should only start this module after successfully completing the prerequisites section of this 'Getting Started' guide.


1. Creating an EC2 F1 instance from the AWS console

Initiating the process

  • Navigate to the AWS EC2 dashboard: https://console.aws.amazon.com/ec2
  • In the top right corner, select a region with F1 instances, such as 'US West (Oregon)'
  • Click 'Launch Instance'

Step 1: Choose an Amazon Machine Image (AMI)

  • Click 'AWS Marketplace' (on the left pane, second item under Quick Start)
  • Search for 'FPGA'
  • Select the 'FPGA Developer AMI'
  • This brings up a pop-up screen showing rates for each instance type
  • Click 'Continue'

Step 2: Choose an Instance Type

  • Select a 'f1.2xlarge' instance
  • Click 'Next: Configure Instance Details'. Do not click 'Review and Launch'

Step 3: Configure Instance

  • Click 'Next: Add Storage' (no need to change the default settings)

Step 4: Add Storage

  • Click 'Next: Add tags' (no need to change the default settings)

Step 5: Add Tags

  • Click 'Next: Configure Security group' (no need to change the default settings)

Step 6: Configure Security group

In this step we modify the security group attached to the instance to allow inbound RDP requests over TCP port # 3389. This is required to work with Remote Desktop GUI session.

  • Click 'Add Rule' to create a new security rule with the following properties:
    • Type: RDP
    • Protocol: TCP (default value)
    • Port Range: 3389 (default value)
    • Source: Custom - 0.0.0.0/0
  • Click 'Review and Launch'

Step 7: Review

  • Click 'Launch'
  • Select an existing key pair or create a new key pair
  • Click the check box at the bottom of the dialog
  • Click 'Launch Instances'

Check Status

  • Return to the AWS EC2 dashboard: https://console.aws.amazon.com/ec2
  • In the left pane, click the 'Instances' to display the list of available instances
  • In the bottom pane, note the IPv4 Public DNS and Public IP address of the instance. You will need these to connect to your instance.

When the status of the newly launched instance switches to green (Running), you are ready to connect to it.


2. Configuring the instance for working with SDAccel

Connecting to the instance using SSH (Linux) or PuTTY (Windows)

  • If you are connecting from a Linux machine, use SSH to connect:
ssh -i <AWS key pairs.pem> -ssh centos@<public DNS of EC2 instance> 22
  • If you are connecting from a Windows machine, use PuTTY to connect:
putty -i <AWS key pairs.ppk> -ssh centos@<public DNS of EC2 instance> 22

Where:

  • <AWS key pairs> is the full path to the .pem (SSH) or .ppk (PuTTY) file containing the key pairs
  • <public DNS of EC2 instance> is the Public DNS of the instance
  • The user name is always 'centos'
  • The connection type is always SSH
  • The port is always 22

You are now connected to the EC2 instance.

Configuring the AWS Command Line Interface (CLI)

To successfully create Amazon FPGA Images, you will need to have the AWS CLI properly configured.

  • Configure the AWS CLI as follows:
$ aws configure
AWS Access Key ID [None]: <your access key> 
AWS Secret Access Key [None]: <your secret key> 
Default region name [None]: <your AWS region, for instance us-west-2 for Oregon>
Default output format [None]: json

Configuring the SDAccel environment

In this step, you clone the Github repository containing the necessary files to run SDAccel and then compile and install the necessary drivers.

  • Execute the following commands from the command line of the instance terminal:
git clone https://github.com/aws/aws-fpga.git $AWS_FPGA_REPO_DIR  
cd $AWS_FPGA_REPO_DIR                                         
source sdaccel_setup.sh

Setting up XRDP on the instance

In this step, you install XRDP and necessary services to run a Remote Desktop GUI session and then set a new password for the 'centos' user. You will need this password to login and authenticate from the Remote Desktop application. This steps take about 5 minutes.

  • Execute the following commands from the command line of the instance terminal:
sudo yum install -y kernel-devel
sudo yum groupinstall -y "Server with GUI"
sudo systemctl set-default graphical.target
sudo yum -y install epel-release
sudo rpm -Uvh http://li.nux.ro/download/nux/dextop/el7/x86_64/nux-dextop-release-0-5.el7.nux.noarch.rpm
sudo yum install -y xrdp tigervnc-server
sudo systemctl start xrdp
sudo systemctl enable xrdp
sudo systemctl disable firewalld
sudo systemctl stop firewalld

sudo passwd centos

After you have completed this step, you are ready to connect to the instance using a Remote Desktop application and run SDAccel.


3. Connecting to the instance with a remote desktop client

  • If you are connecting from a Linux machine, use an RDP client such as Remmina or Vinagre
  • If you are connecting from a Windows machine, start the Microsoft Terminal Services Client by typing the following command in the Windows Start Menu
mstsc.exe
  • In the RDP client, enter the Public IP address of the EC2 instance
  • In the Options menu of the RDP client, make sure that the color depth is set to less than 32 bit
  • Click 'Connect'
  • This should bring up a message about connection certificates. Click 'Yes' to proceed.
  • The Remote Desktop Connection window opens with a login prompt. Log in with the following credentials
    • User: centos
    • Password: password specified during the earlier 'sudo passwd centos' step
  • Click 'Ok'

You should now be connected to the instance.

  • Open a terminal
  • Load the SDAccel environment using the following command:
source $XILINX_SDX/settings64.sh
  • Start SDAccel using the following command:
sdx

NOTE: The first time you will invoke SDAccel, it may take a little while for the GUI to come up. Subsequent invocations will be much faster.


4. Running the SDAccel 'Hello World' example on AWS F1

This final section explains how run the SDAccel 'helloworld_ocl' example on AWS F1 and confirm that environment is properly configured.

Set-up the SDAccel environment

  • In a terminal window, execute the following commands to set-up the SDAccel environment
cd $AWS_FPGA_REPO_DIR  
source sdaccel_setup.sh
source $XILINX_SDX/settings64.sh

Build and run the emulation flows

The SDAccel emulation flows allows testing, profiling and debugging the application before deploying on F1.

  • Run the SW Emulation flow for the SDAccel 'hello world' example:
cd $SDACCEL_DIR/examples/xilinx/getting_started/host/helloworld_ocl/
make clean
make check TARGETS=sw_emu DEVICES=$AWS_PLATFORM all
  • Run the HW Emulation flow for the SDAccel 'hello world' example:
cd $SDACCEL_DIR/examples/xilinx/getting_started/host/helloworld_ocl/
make clean
make check TARGETS=hw_emu DEVICES=$AWS_PLATFORM all

Build the host application and FPGA binary to execute on F1

To execute on F1, the following files need to be built:

  1. Host application
  2. AWS FPGA binary
  3. Amazon FPGA Image (AFI)

Building these files is a two-step process. First SDAccel is used to build the host application and the Xilinx FPGA binary. Then the AWS create_sdaccel_afi.sh script is used to create the AFI and AWS FPGA binary from the Xilinx FPGA binary.

  • Build the host application and the *.xclbin (Xilinx FPGA binary file)
cd $SDACCEL_DIR/examples/xilinx/getting_started/host/helloworld_ocl/
make clean
make TARGETS=hw DEVICES=$AWS_PLATFORM all
  • Create the AWS FPGA binary and AFI from the *.xclbin (Xilinx FPGA binary file)
cd xclbin
$SDACCEL_DIR/tools/create_sdaccel_afi.sh \
	-xclbin=vector_addition.hw.xilinx_aws-vu9p-f1_4ddr-xpr-2pr_4_0.xclbin \
	-s3_bucket=<bucket-name> \
	-s3_dcp_key=<dcp-folder-name> \
	-s3_logs_key=<logs-folder-name>

The create_sdaccel_afi.sh script does the following:

  1. Starts a background process to create the AFI
  2. Generates a _afi_id.txt which contains the FPGA Image Identifier (or AFI ID) and Global FPGA Image Identifier (or AGFI ID) of the generated AFI
  3. Creates the *.awsxclbin AWS FPGA binary file which will need to be read by the host application to determine which AFI should be loaded in the FPGA.

Wait for completion of the AFI creation process

The AFI creation process started in the background is not instantaneous. You need to make sure that the process completes successfully before being able to run on the F1 instance.

  • Note the values of the AFI IDs by opening the _afi_id.txt file 
cat *.afi_id.txt
  • Use the describe-fpga-images API to check the status 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"
 },
...
  • Wait until the AFI becomes available before proceeding to execute the application on the F1 instance.

Execute the host application

  • Execute the following commands in the instance terminal:
cd ..
sudo sh
source /opt/Xilinx/SDx/2017.1.rte/setup.sh   
./helloworld
  • The example application will display the following messages:
Device/Slot[0] (/dev/xdma0, 0:0:1d.0)
xclProbe found 1 FPGA slots with XDMA driver running
platform Name: Xilinx
Vendor Name : Xilinx
Found Platform
Found Device=xilinx:aws-vu9p-f1:4ddr-xpr-2pr:4.0
XCLBIN File Name: vector_addition
INFO: Importing ./vector_addition.hw.xilinx_aws-vu9p-f1_4ddr-xpr-2pr_4_0.awsxclbin
Loading: './vector_addition.hw.xilinx_aws-vu9p-f1_4ddr-xpr-2pr_4_0.awsxclbin'
Result =
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42
TEST PASSED
sh-4.2#

5. Closing the session

Once you have finished your session, you can either 'Stop' or 'Terminate' your instance.

If you 'Terminate' the instance, its root volume will be deleted. You will need to create and configure a new instance the next time you need to work on F1.

It you 'Stop' the instance, the root volume is preserved and the stopped instance can be restarted later. Connecting is then as simple as starting a new RDP client session as outlined in this guide. You do not need to go through the configuration steps anymore. AWS does not charge for stopped instances but may charge you for any EBS volume attached to the instance.

  • Close the remote session
  • Return to the EC2 Dashboard: https://console.aws.amazon.com/ec2
  • Click 'Running Instances' in the main window
  • Select your instance
  • Click the 'Actions' drop-down menu, select 'Instance State' and then click 'Stop' or 'Terminate'.

This concludes the instructions on how to create, configure and test an AWS F1 instance

SDAccel Examples Wiki

Clone this wiki locally