Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 2 additions & 6 deletions .github/ISSUE_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,3 @@
### Release version
Please don't remove the line below

### Expected Behavior

### Actual Behavior

### Steps to reproduce
@aws/fpga-user
239 changes: 124 additions & 115 deletions FAQs.md
Original file line number Diff line number Diff line change
@@ -1,115 +1,124 @@
**Frequently Asked Questions**

**What do I need to get started on building accelerators for FPGA
instances?**

Getting started requires downloading the latest HDK and SDK from the AWS
FPGA GitHub repository. The HDK and SDK provide the needed code and
information for building FPGA code. The HDK provides all the information
needed on building source code for use within the FPGA. The SDK provides
all the information needed on building software for managing FPGAs on an
F1 instance.

FPGA code requires a simulator to test code and a Vivado tool set for
synthesis of source code into compiled FPGA code. The FPGA Developer AMI
includes the Xilinx Vivado tools for simulation and synthesis of
compiled FPGA code.

**How do I develop accelerator code for an FPGA in an F1 instance?**

Start with the Shell interface specification:
AWS\_Shell\_Interface\_Specification.md. This document describes the
interface between Custom Logic and the AWS Shell. All Custom Logic for
an accelerator resides within the Custom Logic region of the F1 FPGA.

**What are the major areas of the GitHub repository?**

The HDK side of the GitHub repository contains the AWS Shell code, Build
scripts, Documentation, and Examples. Shell code is contained in
aws-fpga/hdk/common. Build scripts are in
aws-fpga/hdk/common/shell\_current/build. Documentation is in
aws-fpga/hdk/docs. Custom Logic examples are in aws-fpga/hdk/cl.

The SDK side of the GitHub repository contains the FPGA Management
Tools, a preview of the AWS CLI for F1, and software for Xilinx XDMA and
SDAccell. The FPGA Management Tools are for loading/clearing AFIs and
getting status of the FPGAs mapped to an instance. FPGA Management Tools
are in aws-fpga/sdk/management. The AWS CLI preview is in
aws-fpga/sdk/aws-cli-preview.

**What is included in the HDK?**

The HDK includes documentation for the Shell interface and other Custom
Logic implementation guidelines, the Shell code needed for Custom Logic
development, simulation models for the Shell, software for exercising
the Custom Logic examples, a getting started guide for Custom Logic, and
examples for starting a Custom Logic Design.

**What is in the AWS Shell?**

The AWS Shell includes the PCIe interface for the FPGA, a single DDR
interface, and necessary FPGA management functionality. Also provided as
part of the Shell code, but implemented within the Custom Logic region
of the FPGA are three DDR interfaces. These interfaces are provided for
implementation within the Custom Logic region to provide maximum
efficiency for the developer.

**Are there examples for getting started on accelerators?**

Yes, examples are in the aws-fpga/hdk/cl/examples directory. The
cl\_hello\_world example is a simple example to build and test the CL
development process. The cl\_simple example provides an expanded example
for testing access to the DDR interfaces.

**How do I get access to the Developer AMI?**

Start with an AWS account and request access to the Developer AMI in AWS
Marketplace. Currently, the FPGA Developer AMI is private. You will
receive permission on the AWS account you submitted for access to the
FPGA Developer AMI. The AMI can be launched directly from AWS
Marketplace on any EC2 instance. See the FPGA Developer AMI README for
more details.

**What is an AFI?**

An AFI stands for Amazon FPGA Image. That is the compiled FPGA code that
is loaded into an FPGA for performing the Custom Logic function created
by the developer. AFIs are maintained by AWS according to the AWS
account that created them. An AFI ID is used to reference a particular
AFI from an F1 instance. The AFI ID is used to indicate the AFI that
should be loaded into a specific FPGA within the instance.

**What is the process for creating an AFI?**

The AFI process starts by creating Custom Logic code that conforms to
the Shell Specification. Then, the Custom Logic must be compiled using
the Vivado tools to create a Design Checkpoint. That Design Checkpoint
is submitted to AWS for generating an AFI using the API.

See aws-fpga/hdk/cl and aws-fpga/hdk/cl/examples for more detailed
information.

**Is there any software I need on my instance?**

The required AWS software is the FPGA Management Tool set found in the
SDK directory. This software manages loading and clearing AFIs for FPGAs
in the instance. It also allows developers to retrieve status on the
FPGAs from within the instance. See the README in aws-fpga/sdk for more
details.

**Why do I see error “vivado not found” while running hdk\_setup.sh**

This is an indication that Xilinx vivado tool set are not installed. Try
installing the tool, or alternative use AWS FPGA Development AMI
available on AWS Marketplace, which comes with pre-installed Vivado
toolset and license

**Do AWS Marketplace customers see FPGA source code or a bitstream?**

Neither: AWS Marketplace customers that pick up an AMI with with one our
more AFIs associated with it will not see any source code nor bitstream.
Marketplace customers actually have permission to use the AFI but not
permission to see its code. The only reference to the AFI is through the
AFI ID. The Customer would call fpga-local-load-image with the correct
AFI ID for that Marketplace offering, which will result in AWS loading
the AFI into the FPGA. No FPGA internal design code is exposed.
**Frequently Asked Questions**

**What do I need to get started on building accelerators for FPGA
instances?**

Getting started requires downloading the latest HDK and SDK from the AWS
FPGA GitHub repository. The HDK and SDK provide the needed code and
information for building FPGA code. The HDK provides all the information
needed on building source code for use within the FPGA. The SDK provides
all the information needed on building software for managing FPGAs on an
F1 instance.

FPGA code requires a simulator to test code and a Vivado tool set for
synthesis of source code into compiled FPGA code. The FPGA Developer AMI
includes the Xilinx Vivado tools for simulation and synthesis of
compiled FPGA code.

**How do I develop accelerator code for an FPGA in an F1 instance?**

Start with the Shell interface specification:
AWS\_Shell\_Interface\_Specification.md. This document describes the
interface between Custom Logic and the AWS Shell. All Custom Logic for
an accelerator resides within the Custom Logic region of the F1 FPGA.

**What are the major areas of the GitHub repository?**

The HDK side of the GitHub repository contains the AWS Shell code, Build
scripts, Documentation, and Examples. Shell code is contained in
aws-fpga/hdk/common. Build scripts are in
aws-fpga/hdk/common/shell\_current/build. Documentation is in
aws-fpga/hdk/docs. Custom Logic examples are in aws-fpga/hdk/cl.

The SDK side of the GitHub repository contains the FPGA Management
Tools, a preview of the AWS CLI for F1, and software for Xilinx XDMA and
SDAccell. The FPGA Management Tools are for loading/clearing AFIs and
getting status of the FPGAs mapped to an instance. FPGA Management Tools
are in aws-fpga/sdk/management. The AWS CLI preview is in
aws-fpga/sdk/aws-cli-preview.

**What is included in the HDK?**

The HDK includes documentation for the Shell interface and other Custom
Logic implementation guidelines, the Shell code needed for Custom Logic
development, simulation models for the Shell, software for exercising
the Custom Logic examples, a getting started guide for Custom Logic, and
examples for starting a Custom Logic Design.

**What is in the AWS Shell?**

The AWS Shell includes the PCIe interface for the FPGA, a single DDR
interface, and necessary FPGA management functionality. Also provided as
part of the Shell code, but implemented within the Custom Logic region
of the FPGA are three DDR interfaces. These interfaces are provided for
implementation within the Custom Logic region to provide maximum
efficiency for the developer.

**Are there examples for getting started on accelerators?**

Yes, examples are in the aws-fpga/hdk/cl/examples directory. The
cl\_hello\_world example is a simple example to build and test the CL
development process. The cl\_simple example provides an expanded example
for testing access to the DDR interfaces.

**How do I get access to the Developer AMI?**

Currently, the FPGA Developer AMI is private and you will need to be whitelisted. You will
receive permission and notifications via email. Email aws-fpga-developer-support@amazon.com with any questions
See the FPGA Developer AMI README for more details.


**What is an AFI?**

An AFI stands for Amazon FPGA Image. That is the compiled FPGA code that
is loaded into an FPGA for performing the Custom Logic function created
by the developer. AFIs are maintained by AWS according to the AWS
account that created them. An AFI ID is used to reference a particular
AFI from an F1 instance. The AFI ID is used to indicate the AFI that
should be loaded into a specific FPGA within the instance.

**What is the process for creating an AFI?**

The AFI process starts by creating Custom Logic code that conforms to
the Shell Specification. Then, the Custom Logic must be compiled using
the Vivado tools to create a Design Checkpoint. That Design Checkpoint
is submitted to AWS for generating an AFI using the API.

See aws-fpga/hdk/cl and aws-fpga/hdk/cl/examples for more detailed
information.

**Is there any software I need on my instance?**

The required AWS software is the FPGA Management Tool set found in the
SDK directory. This software manages loading and clearing AFIs for FPGAs
in the instance. It also allows developers to retrieve status on the
FPGAs from within the instance. See the README in aws-fpga/sdk for more
details.

**Why do I see error “vivado not found” while running hdk\_setup.sh**

This is an indication that Xilinx vivado tool set are not installed. Try
installing the tool, or alternative use AWS FPGA Development AMI
available on AWS Marketplace, which comes with pre-installed Vivado
toolset and license

**Do AWS Marketplace customers see FPGA source code or a bitstream?**

Neither: AWS Marketplace customers that pick up an AMI with with one our
more AFIs associated with it will not see any source code nor bitstream.
Marketplace customers actually have permission to use the AFI but not
permission to see its code. The only reference to the AFI is through the
AFI ID. The Customer would call fpga-local-load-image with the correct
AFI ID for that Marketplace offering, which will result in AWS loading
the AFI into the FPGA. No FPGA internal design code is exposed.

**Why did my example job run and die without generating a DCP file?**

The error message below indicates that you ran out of memory. Restart your instance
with a different instance type that has 8GiB or more.

Finished applying 'set_property' XDC Constraints : Time (s): cpu = 00:06:26 ;
elapsed = 00:08:59 . Memory (MB): peak = 4032.184 ; gain = 3031.297 ; free physical = 1285 ; free virtual = 1957
/opt/Xilinx/Vivado/2016.3/bin/loader: line 164: 8160 Killed "$RDI_PROG" "$@"
Parent process (pid 8160) has died. This helper process will now exit

13 changes: 11 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,19 +14,28 @@ Please click the "Watch" button in GitHub upper right corner to stay posted.

## FPGA HDK

The [HDK directory](./hdk) is recommended for developers wanting to start building Amazon FPGA Images (AFI). It includes the development environment, simulation, build and AFI creation scripts. The HDK can be installed on any server or EC2 instance. AWS recommends the use of the [FPGA Developer AMI on AWS Marketplace](https//aws.amazon.com/marketplace/AmazonFPGAAmi). The HDK is not required if you are using a pre-built AFI and not planning to build your own AFI.
The [HDK directory](./hdk) is recommended for developers wanting to start building Amazon FPGA Images (AFI). It includes the development environment, simulation, build and AFI creation scripts. The HDK can be installed on any server or EC2 instance. The HDK is not required if you are using a pre-built AFI and not planning to build your own AFI.

Execute [`source ./hdk_setup.sh`](./hdk_setup.sh) to setup the environment variables required by the rest of the HDK scripts.

## FPGA SDK

The [SDK directory](./sdk) includes the drivers and runtime environment required by any EC2 Instance running on F1. It includes the drivers and tools to interact with pre-built AFIs that are loaded to EC2 F1 FPGAs. The SDK is not required during the AFI development process; it is only required once the AFI is loaded onto an F1 instance.

## FPGA Developer AMI

AWS recommends the use of the F1 FPGA developer AMI for development on EC2 instances. The HDK examples and quick start can be run on any [C4/M4](https://aws.amazon.com/ec2/instance-types/) EC2 instance with atleast 8GiB Memory. For the best performance, c4.2xlarge is recommended. To start using the AMI your AWS account needs to be whitelisted. Once you are whitelisted, from the AWS console you will have access to AMIs. Make sure you are in N. Virginia (us-east-1).
Go to EC2->Launch Instance->My AMIs
Tick the ‘Shared with me’ box on the Ownership tab on the left.
FPGA developer AMI will be prefixed with F1

During private access period, developers are emailed with details on how to get started with the AMI, terms and conditions and additional info on how to get started using F1 instances. Please email aws-fpga-developer-support@amazon.com for questions regarding developer AMI.

# Quick Start

## Building an Example AFI

By following the next few steps, you would have downloaded the HDK, compiled and built one of the example Custom Logic (CL) designs included in this HDK, and registered it with AWS. You can run these steps on any EC2 instance, with [C4](https://aws.amazon.com/ec2/instance-types/) and [M4](https://aws.amazon.com/ec2/instance-types/) being the recommended instance types for performance.
By following the next few steps, you would have downloaded the HDK, compiled and built one of the example Custom Logic (CL) designs included in this HDK, and registered it with AWS.

#### Prerequisites
* AWS FPGA HDK and SDK run in Linux environment only.
Expand Down
2 changes: 1 addition & 1 deletion RELEASE_NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ This is first public release for AWS EC2 FPGA Development Kit. The kit comes wit

* The HDK and SDK are designed for **Linux** environment and has not been tested on other platforms.
* First install of AWS FPGA SDK requires having gcc installed in the instance server. If that's not available, try `sudo yum update && sudo yum group install "Development Tools"`
* The HDK build step requires having Xilinx's Vivado tool and Vivado License Management running
* The HDK build step requires having Xilinx's Vivado tool and Vivado License Management running. Tools and licenses are provided free of charge in AWS FPGA Developer AMI
* Vivado License need to support VU9p ES1 FPGA
* Vivado License need to support encryption
* This release tested and validated with Vivado 2016.3
Expand Down
Loading