Instructor-led XUP tutorial: Connecting to AWS

The following instructions are for live, instructor-led XUP tutorials where AWS F1 instances have been set by Xilinx and login details have been provided to attendees. You can check the XUP workshop schedule for upcoming training. Ask your instructor if you do not have your login details. If you are not attending a live XUP tutorial, go back to the Quick Start page and follow one of the other options to work through these labs.

Introduction

This lab will show you how to start, stop, and connect to a preconfigured AWS EC2 F1 instance.

Objectives

After completing this lab, you will be able to:

Connect to an AWS EC2 F1 instance using the provided credentials
Start the instance
Connect to the instance using remote desktop
Stop the instance
Run the pre lab setup to configure AWS-FPGA and XRT for the instance

Steps

Each registered participant to Xilinx tutorial has been allocated a pre-configured EC2 F1 instance. You should have received an email with the following details:

Account ID
IAM username
Link to access a pre-configured EC2 F1 instance

Follow the link provided by your instructor, or go to https://console.aws.amazon.com/ec2.

If you see the login page for Root user, click the link to sign in to a different account.
Select IAM user and use the account ID provided by your instructor (E.g. xilinx-aws-f1-developer-labs) in Account ID (12 digits) or account alias.
Use the username and password provided by your instructor
In the top right corner make sure to select the AWS region specified by your instructor (E.g. N. Virginia).

If the wrong region is selected you will not be able to see your instance.
Click on the Services in the menu bar at the top of the screen and click on EC2 to see the available instances.

You can also click on the Instances link on the left panel

You may see several instances.
Find the instance that matches your username. If you need to check your username, the account you are logged in as is visible in the menu bar at the top of the screen.

You can enter your username in the Filter instances box to filter the list
Select your instance (tick the checkbox) and click on Instance state > Start
Click on the refresh button to check the status of the instance. It will take about a few seconds before the instance is ready.

Keep refreshing the status until you see the Instance state update to Running. This means the instance is now ready for you to connect to it.
With your instance selected, view the instance Details in the bottom part of the page. You can resize the page to make this section easier to view. Find the Public IPv4 address and copy it. Notice the copy button that will automatically copy the IP address to your clipboard.

This address will be used by to access the remote instance.

Connect to your remote instance

Your instance has been preconfigured to allow you to connect to a remote desktop for your instance using NICE DCV or RDP.

You can also ssh to AWS instances (E.g. using PuTTY) if you only need a terminal. See Appendix: ssh using PuTTY for details.

Connect using NICE DCV

NICE DCV is recommended by Amazon for use with AWS instances. This is also the recommended way to connect to your instance for this tutorial.

Download and install NICE DCV client (Windows|Mac|Linux)

The NICE DCV session has already been started on the pre-configured instance. See the Appendix for details on how to setup a NICE DCV session - for example if you wanted to set up your own AWS instance after this tutorial.

Open the NICE DCV application on your computer, enter the IPv4 Public IP from the Amazon console and click Open
The first time a certificate warning will be displayed. Click Trust to continue
When prompted, enter the Instance ssh\RDP credentials: username and password provided by your instructor (E.g. username: centos). Note that this is different to the username that you used to log in to AWS.
Continue to Lab setup

Connect using RDP

The following instructions are for Windows Remote Desktop Connection (pre-installed on Windows 10 and recent versions). For Mac VNC is recommended (see the next section). For Linux you can use Remmina or Vinagre (search for instructions on how to install this for your OS). Detailed instructions are not provided for Linux. You can follow the steps below and carry out the corresponding actions in your Linux RDP client.

Search for Remote Desktop Connection in the windows start menu, and open it to start a session
Enter the IPv4 Public IP address for your instance
Click on the Show Options
Select the Display tab and select True Color (24 bit) and click Connect
A certificate warning will be displayed. Click Yes to open the RDP session
Enter the RDP credentials you were provided with and click OK

Continue to Lab setup

Known issues:

If the color depth is not set to True Color(24 bit) some programs are not displayed properly

Connect using VNC (Suggested for Mac users)

Install RealVNC client for Mac

Other alternatives for Linux-based OS are Remmina or Vinagre
Open the RealVNC client
Enter IPv4 Public IP:01 and then hit the enter key
You will be informed that the connection is Unencrypted, click Continue
Enter the provided RDP credentials password and click OK
Continue to Lab setup

Lab setup

In your remote desktop session, right click on the desktop and select Open Terminal
Copy and paste the following commands to your terminal (make sure to hit enter to run the last command):

git clone https://github.com/aws/aws-fpga -b v1.4.21 aws-fpga
git clone https://github.com/Xilinx/xup_compute_acceleration xup_compute_acceleration
echo "export PLATFORM_REPO_PATHS=~/aws-fpga/Vitis/aws_platform/xilinx_aws-vu9p-f1_shell-v04261818_201920_2/" >> ~/.bashrc
echo "source /opt/xilinx/xrt/setup.sh" >> ~/.bashrc
echo "source $XILINX_VITIS/settings64.sh" >> ~/.bashrc
echo "source ~/aws-fpga/vitis_setup.sh" >> ~/.bashrc
echo "source ~/aws-fpga/vitis_runtime_setup.sh" >> ~/.bashrc
source ~/.bashrc

This will

Clone the aws-fpga repository to your home area. aws-fpga includes the AWS F1 tools, Hardware Development Kit (HDK) and documentation.
Setup the AWS platform path, and add XRT and Vitis setup scripts to your .bashrc file. This means they will be available in every new terminal session you open.
Clone this repository to get source code for the labs
Source ~/bashrc to refresh this terminal session
Source AWS Vitis setup scripts. This are setup scripts that need to be run once to configure the aws-fpga and Vitis tools.

You will see a lot of messages in the terminal. The last line should read:

INFO: Vitis runtime check PASSED

You can now proceed to Lab 1: Introduction to Vitis Part 1.

If you are using the AWSEducate instances then execute the following to clone the xup_compute_acceleration repository. No additional variables need to be set as the provided AMI has all necessary files including aws-fpga repository cloning, the AWS F1 tools, Hardware Development Kit (HDK) and documentation

git clone https://github.com/Xilinx/xup_compute_acceleration.git

The previous command will:

Clone this repository to get source code and solutions

For more details visit: aws-fpga/Vitis/README.md

Appendix

SSH using PuTTY

Start PuTTY or your preferred SSH client
Enter centos@<IPv4_Public_IP> in the Host Name field and 22 in the Port field
Make sure that SSH is selected as the Connection type
Click Open and then Yes when PuTTY Security Alert is shown

The PuTTY window will open. It will ask for the password (in case of the workshop). Enter the provided password
Enter exit to close the session

Set up the NICE DCV session

Open PuTTY, and ssh to your instance as described on SSH using PuTTY
On the terminal, enter the following command to start the DCV server:
```
dcv create-session --user centos centos
```
By default NICE DCV runs in the TCP port 8443
Verify dcv session

If the output of dcv list-sessions should look like:
```
Session: 'centos' (owner: centos)
```

Stop the firewall

sudo systemctl disable firewalld
sudo systemctl stop firewalld