SETUP.md

AWS F1 Xilinx Developer Labs
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 a pre-configured EC2 F1 instance and connect to it using a remote desktop client. Once connected, you will download the lab files and confirm you can execute a simple application on F1.

For this event, each registered participant has been attributed a preconfigured EC2 F1 instance and should have received an email with the following details:

• Account ID
• IAM username
• Link to access a preconfigured EC2 F1 instance

If you have not received that email, please contact an Xilinx event staff member now.

Start a preconfigured EC2 F1 instance

1. Open the above mentioned email containing your connection credentials.

2. Click on the link to your preconfigured instance.

   • You will be asked to sign-in before accessing your instance in the AWS EC2 Console.

3. In the AWS sign-in page, enter the Account ID which was emailed to you

4. Click Next.

5. Enter the IAM user name which was emailed to you.

6. Enter the Password provided at the event.

7. Click Sign In.

   • You should now be logged in the AWS EC2 Console and you should see an f1.2xlarge instance in the stopped state.

8. Start the instance by choosing the Actions button, then select Instance State and then Start.

   

   • Allow about 10 seconds for the instance to start and be in the Running state.
   • If needed, click the Refresh icon () in the top-right corner of the EC2 Console to update the instance status information.

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

Connect to your instance using a remote desktop client

The instance you just started is preconfigured with remote desktop protocol (RDP) services.

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

   • IMPORTANT: Before connecting, set your remote desktop client to use 24-bit for color depth
     • Windows client: In the bottom-left corner of connection prompt, click Options, select the Display tab and set Colors to True Colors (24 bit)
   • 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 v8.0.43 (that version offers color depth settings) from the Mac App Store.

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

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

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

5. Login with the following credentials:

   • User: centos
   • Password: ******** (provided at the event)

   

6. Click Ok.

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

Open the lab instructions on the remote F1 instance

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

   • It opens the browser and loads the lab instructions.

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

2. Continue following the lab 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, git clone the AWS-F1-Developer-Labs repository to download the files for the Xilinx Developer Lab.

   cd /home/centos
   git clone https://github.com/Xilinx/AWS-F1-Developer-Labs.git

3. Source the SDAccel environment.

   cd ~/src/project_data/aws-fpga
   source sdaccel_setup.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 lab.

1. Compile the host application

   # Go to the example directory
   cd ~/AWS-F1-Developer-Labs/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-04261818_dynamic_5_0.awsxclbin

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

   sudo sh
   source /opt/xilinx/xrt/setup.sh
   ./helloworld

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

   sh-4.2# ./helloworld
   xclProbe found 1 FPGA slots with xocl driver running
   Found Platform
   Platform Name: Xilinx
   Found Device=xilinx_aws-vu9p-f1-04261818_dynamic_5_0
   XCLBIN File Name: vector_addition
   INFO: Importing xclbin/vector_addition.hw.xilinx_aws-vu9p-f1-04261818_dynamic_5_0.awsxclbin
   Loading: 'xclbin/vector_addition.hw.xilinx_aws-vu9p-f1-04261818_dynamic_5_0.awsxclbin'
   INFO: Could not load AFI for data retention, code: 18 - Loading in classic mode.
   AFI load complete.
   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#

   You compiled a host application and successfully executed it on F1 using a pre-compiled Amazon FPGA Image (AFI).

4. Close your terminal.

   exit
   exit

This concludes this first lab.

---

Start the next module: 2: Experiencing F1 acceleration