Skip to content

Latest commit

 

History

History
306 lines (236 loc) · 13 KB

STEP1.md

File metadata and controls

306 lines (236 loc) · 13 KB

Create, Configure, and Test an AWS F1 Instance

This module guides you through the following steps:

  1. Creating an EC2 F1 Instance from the AWS Console
  2. Connecting to the Instance with a remote desktop client
  3. Configuring the Instance for Working with SDAccel
  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

Step 1: Launch the Instance

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

Step 2: Choose an Amazon Machine Image (AMI)

  1. Click AWS Marketplace (on the left pane, this is the second item under Quick Start).
  2. Search for FPGA.
  3. Select the FPGA Developer AMI.
  4. A dialog box opens, showing rates for each instance type.
  5. Click Continue.

Step 3: Select an Instance Type

  1. Select a f1.2xlarge instance.
  2. Click Next: Configure Instance Details.

NOTE: Do not click Review and Launch.

Step 4: Configure Your Instance

  1. Click Next: Add Storage (no need to change the default settings).
  2. Click Next: Add tags (no need to change the default settings).
  3. Click Next: Configure Security group (no need to change the default settings).

Step 5: Configure the Security Group

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

  1. 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
  2. Click Review and Launch.

Step 6: Review Your Instance

  1. Click Launch.
  2. Select an existing key pair or create a new key pair.
  3. Click the check box at the bottom of the dialog box.
  4. Click Launch Instances.

Step 7: Check the Status of Your Instance

  1. When ready, at the bottom of the page, select View Instances.
  2. In the bottom pane, note the IPv4 Public DNS and Public IP address of the instance.

IMPORTANT: You will need these addresses 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. Connecting to the Instance with a remote desktop client

Step 1: Connect to the Instance using SSH (Linux) or PuTTY (Windows)

Connect to the instance using one of the following commands:

  • If you are connecting from a Linux machine, use SSH to connect:
ssh -i <AWS key pairs.pem> -ssh centos@<public IP address 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 IP address 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.

Step 2: Set up GUI Services on the Instance

The FPGA Developer AMI does not include a GUI desktop application. In these steps, you install the Gnome window manager and start remote desktop protocol (RDP) services to allow remote desktop connections.

  1. Execute the following commands from the command line of the instance terminal:
source <(curl -s https://s3.amazonaws.com/aws-fpga-developer-ami/1.5.0/Scripts/setup_gui.sh)

The script takes about 10 minutes to run and finishes by setting a password for the 'centos' user.

IMPORTANT: Take note of the password generated by the script. You will need it to connect using RDP.

  1. Return to the AWS EC2 dashboard in your web browser.

  2. Select your instance, then from the Actions menu, select Instance State and then select Reboot.

  3. Wait a couple of minutes for the instance to complete the reboot cycle.

After you have completed this step, you are ready to connect to the instance using a remote desktop client.

Step 3: Connect to the Instance with a Remote Desktop Client

  1. From your local machine, start a remote desktop protocol (RDP) client.
  • On Windows: press the Windows key and type mstsc.exe in the Windows run prompt.
  • On Linux: use an RDP client, such as Remmina or Vinagre.
  • On macOS: use the Microsoft Remote Desktop v8.0.43 from the Mac App Store. That version offers color depth settings.

IMPORTANT: Set your RDP client to use 24-bit for color depth.

  • On Windows: In the bottom-left corner of connection prompt, click Options, then click the Display tab and set Colors to True Colors (24 bit).
  • In the RDP client, enter the IPv4 Public IP of your instance.
  • Click Connect. A dialog box regarding connection certificates opens.
  • Click Yes to dismiss the message. The Remote Desktop Connection window opens with a login prompt.
  • Log in with the following credentials:
    • User: centos
    • Password: password generated by the setup_gui.sh script
  • Click Ok.

You are now connected to the instance running Centos 7 and the FPGA Developer AMI.

3. Configuring the Instance for Working with SDAccel

Step 1: Configure the AWS Command Line Interface (CLI)

To successfully create Amazon FPGA Images, you must have the AWS CLI properly configured.

  1. Open a new terminal by right-clicking anywhere in the Desktop area and selecting Open Terminal.
  2. 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

Step 2: Configure the SDAccel Environment

In this step, you install the necessary files to build and execute applications on AWS F1. This includes the SDAccel&tm; platform, runtime and drivers.

  1. 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

NOTE: Sourcing sdaccel_setup.sh takes a couple of minutes, because the first time you run it, the script will download the platform and compile the runtime and drivers. Subsequent runs are much faster. You must source sdaccel_setup.sh each time you open a new terminal as it sets the necessary environment variables to run SDAccel.

  1. Close the terminal.

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

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

Step 1: Set Up the SDAccel Environment

  1. Open a new terminal window.
  2. Execute the following commands to set-up the SDAccel environment:
cd $AWS_FPGA_REPO_DIR  
source sdaccel_setup.sh

Step 2: Build and Run the Emulation Flows

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

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

Step 3: Build the Host Application and FPGA Binary to Execute on F1

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

  • Host application
  • AWS FPGA binary
  • 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.

  1. Build the host application and the *.xclbin (Xilinx FPGA binary file):
cd $SDACCEL_DIR/examples/xilinx/getting_started/host/helloworld_c/
make clean
make TARGETS=hw DEVICES=$AWS_PLATFORM all
  1. Create the AWS FPGA binary and AFI from the *.xclbin (Xilinx FPGA binary file):
cd xclbin
$SDACCEL_DIR/tools/create_sdaccel_afi.sh \
	  -xclbin=<xclbin file name>.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 <timestamp>_afi_id.txt file, 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.

Step 4: Wait for Completion of the AFI Creation Process

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

  1. Note the values of the AFI IDs by opening the <timestamp>_afi_id.txt file:
cat *.afi_id.txt
  1. Use the describe-fpga-images API to check the status AFI generation process.
aws ec2 describe-fpga-images --fpga-image-ids <AFI ID>
  1. When AFI creation completes successfully, the output should contain:
...
"State": {
    "Code": "available"
},
...
  1. Wait until the AFI becomes available before proceeding to execute the application on the F1 instance.

Step 5: Execute the Host Application

⚠️ IMPORTANT : The previous steps do not require an AWS EC2 F1 instance. They can be executed on other AWS EC2 instances such as C4 or C5. However, the steps that follow must be performed on an AWS EC2 F1 instance. You will receive error messages if you do not perform the following steps on an F1 instance.

  1. Execute the following commands in the instance terminal:
cd $SDACCEL_DIR/examples/xilinx/getting_started/host/helloworld_c/
sudo sh
source /opt/xilinx/xrt/setup.sh   
./helloworld

  1. The example application displays 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=<platform name>
XCLBIN File Name: vector_addition
INFO: Importing ./<awsxclbin file name>.awsxclbin
Loading: './<awsxclbin file name>.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

After 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 must 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 might charge you for any EBS volume attached to the instance.

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

NEXT: Run your first SDAccel program on AWS F1


Copyright© 2019 Xilinx