SETUP.md

re:Invent 2017 Developer Workshop
Introduction	1. Connecting to your F1 instance	2. Experiencing F1 acceleration	3. Developing F1 applications	4. Wrapping-up

---

Connecting to your F1 instance

In this module you will start an EC2 F1 instance using the FPGA Developer AMI and connect to it using a remote desktop client. Once connected, you will download the workshop files and confirm you can execute a simple application on F1.

For this event, each registered participant will be required to start an EC2 F1 instance, therefore, participants need to have experience with:

• AWS account and launching EC2 instances
• EC2 Key Pair (.pem)
• EC2 Security Groups
• IAM username and credentials
• Setting up AWS CLI
• Connecting to a running instance using SSH or PuTTy

Start a EC2 F1 instance based FPGA developer AMI

1. Sign into your AWS account and go to EC2

2. Select Region US-East (N. Virginia). The pull down is located in the upper right corner of the console.

3. Launch an F1 Instance (f1.2xlarge) using the FPGA developer AMI from the EC2 Console.

   • Use Manual launch

   • Select launch with EC2 console

   • Configure the root volume(/dev/sda1) to be 100GB

   • Setup your security groups to allow RDP and SSH ingress from your IP or from anywhere depending on your security preferences.

4. Once the instance is running, find and note the IPv4 Public IP address of your instance.

   • You will be using this IP address to connect to your instance.
   • The IPv4 Public IP address is displayed in EC2 Console next to the instance status.

Some AWS accounts may have a F1 instance limit equal to 0. If your F1 instance fails to launch due to your account has an instance limit equal to 0: During the workshop, raise your hand for assistance so we can manaully raise the limit on your account. After the workshop, use AWS support to submit for a F1 instance limit increase.

Connect to your instance using SSH

Windows Users - Connecting to Your Linux Instance from Windows Using PuTTY

1. In the SSH client, use the IPv4 Public IP of your instance:

    ssh -i <.pem file> centos@<IPv4 Public IP>

2. Run a setup script to configure GUI and download workshop files.

   source <(curl -s https://s3.amazonaws.com/aws-ec2-f1-reinvent-17/setup_script/setup_reinvent.sh)

   This setup script performs the following tasks:

   • Download and setup the aws-fpga repository in (/home/centos).
   • Download and setup the aws-fpga-app-notes repository in (/home/centos).
   • Install packages to setup a GUI Desktop on the FPGA Developer AMI.
   • Set a user password for the 'centos' user.
   • IMPORTANT: Please take a note of the password it generates at the end. You will need to use it to connect using RDP.
   • The setup script is a one time setup and completes in 8-15 mins. Feel free to use this time to read the workshop.

Connect to your instance using a remote desktop client

The instance you just started should now be configured with remote desktop protocol (RDP) services.

1. From your local machine, start a remote desktop protocol client

   • On Windows: press the Windows key and type "remote desktop".
     • You should see the "Remote Desktop Connection" in the list of programs.
     • Alternatively you can also simply type mstsc.exe in the Windows run prompt.
   • On Linux: RDP clients such a Remmina or Vinagre are suitable.
   • On macOS: use the Microsoft Remote Desktop from the Mac App Store.

2. In the RDP client, enter the IPv4 Public IP of your instance.

3. IMPORTANT: Before connecting, set your remote desktop client to use 24-bit or less for color depth

   • On Windows: In the bottom-left corner of connection prompt, click Options, then select the Display tab and set Colors to True Colors (24 bit)

4. Click Connect. This should bring up a message about connection certificates.

5. Click Yes to dismiss the message. The Remote Desktop Connection window opens with a login prompt.

6. Login with the following credentials:

   • User: centos
   • Password: ******** (Generated as part of the setup script)
   • Look for output like below:

     INFO: Setting password for user 'centos'
     INFO: **************************************
     INFO: *** PASSWORD : reinvent2017_123   ****
     INFO: **************************************

   

7. Click Ok.

You should now be connected to the remote F1 instance running Centos 7.

Open the workshop instructions on the remote F1 instance

1. In the remote instance, double click on the Chromium Web Browser icon.

   • It opens the browser and loads the workshop instructions.

   Note: if a "keyring" popup comes up, click Cancel.

2. Continue following the workshop instructions from within the remote instance and the Chromium browser.

   • We suggest you perform all your copy-paste from the instructions to the shell within the RDP session to avoid issues.

Configure the Xilinx SDAccel environment and load the workshop files

1. Open a new terminal by right-clicking anywhere in the Desktop area and selecting Open Terminal.

2. In the terminal, verify that the reInvent17_Developer_Workshop within the aws-fpga-apps-notes repository exists and that the aws-fpga repository exists.

   ls -lrtha ~/aws-fpga-app-notes
   ls -lrtha ~/aws-fpga

3. Source the SDAccel environment from the aws-fpga repository.

   cd ~/aws-fpga
   source sdaccel_setup.sh
   source $XILINX_SDX/settings64.sh 

   Note: the sdaccel_setup.sh script might generate warning messages, but these can be safely ignored.

Run the hello_world example to validate the setup of your F1 instance

The hello world example is an OpenCL application with a simple vector-addition accelerator. This example uses a precompiled FPGA binary to reduce compilation time and streamline the workshop.

1. Compile the host application

   # Go to the example directory
   cd ~/aws-fpga-app-notes/reInvent17_Developer_Workshop/helloworld_ocl
   
   # Compile the host application (./helloworld)
   make TARGETS=hw DEVICES=$AWS_PLATFORM exe

2. Confirm the presence of the precompiled FPGA binary.

   ls -la ./xclbin/vector_addition.hw.xilinx_aws-vu9p-f1_4ddr-xpr-2pr_4_0.awsxclbin

3. Execute the host application with the precompiled FPGA binary on the F1 instance.

   sudo sh
   source /opt/Xilinx/SDx/2017.1.rte/setup.sh
   ./helloworld

4. The host application executes using the vector_addition kernel running in the FPGA and produces the following results:

   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. You compiled a host application and successfully executed it on F1 using a pre-compiled Amazon FPGA Image (AFI).

6. Close your terminal.

   exit
   exit

This concludes this first module.

---

Start the next module: 2: Experiencing F1 acceleration