Skip to content

Commit df490e6

Browse files
AWSwinefredAWSwinefred
committed
squashing commits before moving repo to public access
Change-Id: Iec0592fc0c60b1e6c2aa7c528f563afd800bf64b
1 parent 682b324 commit df490e6

File tree

412 files changed

+750182
-4
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

412 files changed

+750182
-4
lines changed

‎.github/ISSUE_TEMPLATE.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
### Release version
2+
3+
### Expected Behavior
4+
5+
### Actual Behavior
6+
7+
### Steps to reproduce

‎.gitignore

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
cscope.files
2+
cscope.out
3+
tags
4+
simv
5+
simv.daidir
6+
csrc
7+
ucli.key
8+
vc_hdrs.h
9+
INCA_libs
10+
irun.log
11+
irun.key
12+
13+
fpga-local-cmd
14+
15+
*_compile.log
16+
*_run.log
17+
*.vpd
18+
.simvision
19+
*.vcd
20+
*.vcdplus*
21+
waves.shm
22+
23+
*~
24+
.\#*
25+
\#*
26+
27+
*.swp
28+
*.o
29+
.nfs*
30+
*.so
31+
*.a

‎FAQ.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Frequently Asked Questions
2+
3+
4+
5+
### Error while running `hdk_setup.sh`
6+
7+
Q. I see error ##vivado not found## ?
8+
9+
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
10+
11+
12+
## AFI on AWS Marketplace
13+
14+
### Q. Do AWS Marketplace customers see FPGA source code or is it just a bitstream?
15+
16+
Neither: AWS Marketplace customers that pick up an AMI with with one our more AFIs associated with it would not see any source code nor bitstream. Marketplace customers actually have permission to use the AFI but not permission to see its code. The Customer would call`fpga-local-load-image` which will result in AWS loading the AFI into the FPGA. This way, your design is not exposed.

‎FAQs.md

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
**Frequently Asked Questions**
2+
3+
**What do I need to get started on building accelerators for FPGA
4+
instances?**
5+
6+
Getting started requires downloading the latest HDK and SDK from the AWS
7+
FPGA GitHub repository. The HDK and SDK provide the needed code and
8+
information for building FPGA code. The HDK provides all the information
9+
needed on building source code for use within the FPGA. The SDK provides
10+
all the information needed on building software for managing FPGAs on an
11+
F1 instance.
12+
13+
FPGA code requires a simulator to test code and a Vivado tool set for
14+
synthesis of source code into compiled FPGA code. The FPGA Developer AMI
15+
includes the Xilinx Vivado tools for simulation and synthesis of
16+
compiled FPGA code.
17+
18+
**How do I develop accelerator code for an FPGA in an F1 instance?**
19+
20+
Start with the Shell interface specification:
21+
AWS\_Shell\_Interface\_Specification.md. This document describes the
22+
interface between Custom Logic and the AWS Shell. All Custom Logic for
23+
an accelerator resides within the Custom Logic region of the F1 FPGA.
24+
25+
**What are the major areas of the GitHub repository?**
26+
27+
The HDK side of the GitHub repository contains the AWS Shell code, Build
28+
scripts, Documentation, and Examples. Shell code is contained in
29+
aws-fpga/hdk/common. Build scripts are in
30+
aws-fpga/hdk/common/shell\_current/build. Documentation is in
31+
aws-fpga/hdk/docs. Custom Logic examples are in aws-fpga/hdk/cl.
32+
33+
The SDK side of the GitHub repository contains the FPGA Management
34+
Tools, a preview of the AWS CLI for F1, and software for Xilinx XDMA and
35+
SDAccell. The FPGA Management Tools are for loading/clearing AFIs and
36+
getting status of the FPGAs mapped to an instance. FPGA Management Tools
37+
are in aws-fpga/sdk/management. The AWS CLI preview is in
38+
aws-fpga/sdk/aws-cli-preview.
39+
40+
**What is included in the HDK?**
41+
42+
The HDK includes documentation for the Shell interface and other Custom
43+
Logic implementation guidelines, the Shell code needed for Custom Logic
44+
development, simulation models for the Shell, software for exercising
45+
the Custom Logic examples, a getting started guide for Custom Logic, and
46+
examples for starting a Custom Logic Design.
47+
48+
**What is in the AWS Shell?**
49+
50+
The AWS Shell includes the PCIe interface for the FPGA, a single DDR
51+
interface, and necessary FPGA management functionality. Also provided as
52+
part of the Shell code, but implemented within the Custom Logic region
53+
of the FPGA are three DDR interfaces. These interfaces are provided for
54+
implementation within the Custom Logic region to provide maximum
55+
efficiency for the developer.
56+
57+
**Are there examples for getting started on accelerators?**
58+
59+
Yes, examples are in the aws-fpga/hdk/cl/examples directory. The
60+
cl\_hello\_world example is a simple example to build and test the CL
61+
development process. The cl\_simple example provides an expanded example
62+
for testing access to the DDR interfaces.
63+
64+
**How do I get access to the Developer AMI?**
65+
66+
Start with an AWS account and request access to the Developer AMI in AWS
67+
Marketplace. Currently, the FPGA Developer AMI is private. You will
68+
receive permission on the AWS account you submitted for access to the
69+
FPGA Developer AMI. The AMI can be launched directly from AWS
70+
Marketplace on any EC2 instance. See the FPGA Developer AMI README for
71+
more details.
72+
73+
**What is an AFI?**
74+
75+
An AFI stands for Amazon FPGA Image. That is the compiled FPGA code that
76+
is loaded into an FPGA for performing the Custom Logic function created
77+
by the developer. AFIs are maintained by AWS according to the AWS
78+
account that created them. An AFI ID is used to reference a particular
79+
AFI from an F1 instance. The AFI ID is used to indicate the AFI that
80+
should be loaded into a specific FPGA within the instance.
81+
82+
**What is the process for creating an AFI?**
83+
84+
The AFI process starts by creating Custom Logic code that conforms to
85+
the Shell Specification. Then, the Custom Logic must be compiled using
86+
the Vivado tools to create a Design Checkpoint. That Design Checkpoint
87+
is submitted to AWS for generating an AFI using the API.
88+
89+
See aws-fpga/hdk/cl and aws-fpga/hdk/cl/examples for more detailed
90+
information.
91+
92+
**Is there any software I need on my instance?**
93+
94+
The required AWS software is the FPGA Management Tool set found in the
95+
SDK directory. This software manages loading and clearing AFIs for FPGAs
96+
in the instance. It also allows developers to retrieve status on the
97+
FPGAs from within the instance. See the README in aws-fpga/sdk for more
98+
details.
99+
100+
**Why do I see error “vivado not found” while running hdk\_setup.sh**
101+
102+
This is an indication that Xilinx vivado tool set are not installed. Try
103+
installing the tool, or alternative use AWS FPGA Development AMI
104+
available on AWS Marketplace, which comes with pre-installed Vivado
105+
toolset and license
106+
107+
**Do AWS Marketplace customers see FPGA source code or a bitstream?**
108+
109+
Neither: AWS Marketplace customers that pick up an AMI with with one our
110+
more AFIs associated with it will not see any source code nor bitstream.
111+
Marketplace customers actually have permission to use the AFI but not
112+
permission to see its code. The only reference to the AFI is through the
113+
AFI ID. The Customer would call fpga-local-load-image with the correct
114+
AFI ID for that Marketplace offering, which will result in AWS loading
115+
the AFI into the FPGA. No FPGA internal design code is exposed.

‎README.md

+86-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,86 @@
1-
# aws-fpga
2-
Official repository of the AWS EC2 FPGA Hardware Development Kit
1+
<span style="display: inline-block;">
2+
3+
# AWS EC2 FPGA Hardware and Software Development Kit
4+
5+
This release includes two portions: [HDK](./hdk) for developing Amazon FPGA Image (AFI), and [SDK](./sdk) for using AFI on FPGA-enabled EC2 instances [such as F1](https://aws.amazon.com/ec2/instance-types/f1/).
6+
7+
Execute `git clone http://github.com/aws/aws-fpga` to download this HDK+SDK release to your EC2 Instance or local server.
8+
9+
The [Release Notes](./RELEASE_NOTES.md) document covers the list of supported features, programming environment, and known restrictions.
10+
11+
**NOTE: The HDK and SDK are tested and supported for Linux operating systems, for the time being, other OSs haven't been tested by AWS**
12+
13+
Please click the "Watch" button in GitHub upper right corner to stay posted.
14+
15+
## FPGA HDK
16+
17+
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.
18+
19+
Execute [`source ./hdk_setup.sh`](./hdk_setup.sh) to setup the environment variables required by the rest of the HDK scripts.
20+
21+
## FPGA SDK
22+
23+
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.
24+
25+
# Quick Start
26+
27+
## Building an Example AFI
28+
29+
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.
30+
31+
#### Prerequisites
32+
* AWS FPGA HDK and SDK run in Linux environment only.
33+
* If you can not access GitHub repository, please request access permission from your AWS representative.
34+
* The build stage uses Xilinx's Vivado tool set. You should have an installed Vivado and Vivado License Manager (See [Release Notes](./RELEASE_NOTES.md) for details on the version).
35+
* Executing `aws s3 <action>` and `aws ec2 create-fpga-image` require having AWS CLI installed, having an active AWS account, and the server/instance has been configured with your credentials and AWS region via `aws configure` command line.
36+
* AWS offers FPGA Developer AMI with all Xilinx's Vivado tools and AWS CLI pre-installed.
37+
38+
**NOTE**: The DCP generation (`Step 7`) can take up to several hours to complete.
39+
We recommend that you initiate the generation in a way that prevents interruption.
40+
For example, if working on a remote machine, we recommend using window management tools such as [`screen`](https://www.gnu.org/software/screen/manual/screen.html) to mitigate potential network disconnects.
41+
42+
```
43+
$ git clone https://github.com/aws/aws-fpga # Step 1: Download the HDK and SDK code
44+
$ cd aws-fpga # Step 2: Move to the root directory
45+
$ source hdk_setup.sh # Step 3: Set up the HDK environment variables
46+
$ cd hdk/cl/examples/cl_simple # Step 4: Change directory to one of the provided examples
47+
$ export CL_DIR=$(pwd) # Step 5: Define this directory as the root for the CL design
48+
$ cd build/scripts # Step 6: The build directory for synthesizing, placement, timing etc
49+
$ source aws_build_dcp_from_cl.sh # Step 7: Generate a placed-and-routed design checkpoint (DCP)
50+
$ cd $CL_DIR/build/checkpoints/to_aws # Step 8: This directory includes the DCP file
51+
$ aws s3 mb s3://<bucket-name> # Step 9: Create an S3 bucket (choose a unique bucket name)
52+
$ aws s3 cp *.SH_CL_routed.dcp \ # Step 10: Upload the DCP file to S3
53+
s3://<bucket-name>/cl_simple.dcp
54+
$ aws ec2 create-fpga-image \ # Step 11: Ingest the generated DCP to create an AFI
55+
--fpga-image-architecture xvu9p \
56+
--shell-version 0x11241611 \
57+
--fpga-pci-id deviceId=0x1d50,vendorId=0x6789,subsystemId=0x1d51,subsystemVendorId=0xfedc \
58+
--input-storage-location Bucket=<bucket-name>,Key=cl_simple.dcp
59+
--name MyFirstDCP
60+
--logs-storage-location Bucket=<bucket-name>,Key=logs/
61+
```
62+
63+
**NOTE**: The `aws ec2 create-fpga-image` command-line API is coming soon and subject to change.
64+
65+
## Using an AFI on EC2 F1
66+
67+
Now that you have built an AFI, or if you want to use one of the example pre-built AFIs provided by AWS, you need to launch an EC2 F1 Instance, and install the SDK:
68+
69+
You can setup and install the SDK with the following few steps. Note that the first two steps may be skipped if you have already run them in the above HDK setup.
70+
71+
```
72+
$ git clone https://github.com/aws/aws-fpga # Fetch the HDK and SDK code
73+
$ cd aws-fpga # Move to the root directory of the repository before running the next script
74+
$ source sdk_setup.sh # Set up the envronment variables, build and install the SDK
75+
```
76+
77+
**NOTE:** The `sdk_setup.sh` would install the [FPGA management tools](./sdk/management/fpga_image_tools/README.md) if they are not already available in `/usr/bin`. The `sdk_setup.sh` requires having `gcc` installed. if it is not installed, try running the next command to install it on Amazon Linux, Centos or Redhat distributions:
78+
79+
```
80+
$ sudo yum groupinstall -y “Development Tools"
81+
```
82+
83+
## Need to build a new Custom Logic and register it as an AFI?
84+
85+
The [Getting started with CL examples](./hdk/cl/examples/README.md) guide provides step-by-step instructions to build an AFI from one of the provided examples, register it with AWS, and load it on an EC2 F1 instance.
86+

‎RELEASE_NOTES.md

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
2+
# AWS EC2 FPGA HDK+SDK Release notes
3+
4+
# Release 1.0.0
5+
6+
## Content
7+
8+
This is first public release for AWS EC2 FPGA Development Kit. The kit comes with HDK(Hardware Development Kit) and SDK(Software Development Kit). Below is the list of features included in this release. More details about these features can be found in ![AWS Shell Interface Specification](./hdk/docs/AWS_Shell_Interface_Specification.md)
9+
10+
* AWS EC2 FPGA platform feature list:
11+
* Xilinx UltraScale+ VU9P
12+
* Interfaces available for Custom Logic(CL):
13+
* One x16 PCIe Gen 3 Interface
14+
* Four DDR4 RDIMM interfaces (with ECC)
15+
* AXI4 protocol support on all interfaces
16+
* 250 MHz base clock and asynchronous reset provided to Custom Logic(CL)
17+
* PCIE endpoint presentation to Custom Logic(CL)
18+
* Management PF (physical function)
19+
* Application PF
20+
* PCIE interface between Shell(SH) and Custom Logic(CL).
21+
* SH to CL inbound 512-bit AXI4 interface (currently supports 32-bit accesses only).
22+
* CL to SH outbound 512-bit AXI4 interface
23+
* Maximum payload size set by the Shell
24+
* Maximum read request size set by the Shell
25+
* AXI4 error handling
26+
* Proprietary AxUSER bits implemented on address channels: please refer to ![AWS Shell Interface Specification](./hdk/docs/AWS_Shell_Interface_Specification.md)
27+
* DDR interface between SH and CL
28+
* CL to SH 512-bit AXI4 interface
29+
* 1 DDR controller implemented in the SH (always available)
30+
* 3 DDR controllers implemented in the CL (configurable number of implemented controllers allowed)
31+
32+
## Implementation Restrictions
33+
34+
* PCIE AXI4 interfaces between Custom Logic(CL) and Shell(SH) have following restrictions:
35+
* All PCIe transactions must adhere to the PCIe Exress base spec.
36+
* 4Kbyte Address boundary for all transactions(PCIe restriction).
37+
* Multiple outstanding outbound PCIe Read transactions with same ID not supported.
38+
* PCIE extended tag not supported, so read-request is limited to 32 outstanding.
39+
* Address must match DoubleWord(DW) address of the transaction.
40+
* WSTRB(write strobe) must reflect appropriate valid bytes for AXI write beats
41+
* Only Increment burst type is supported.
42+
* AXI lock, memory type, protection type, Quality of service and Region identifier are not supported.
43+
44+
## Unsupported Features (Planned for future releases)
45+
46+
* DMA Engine is not included with the current version of the Shell
47+
* Interrupts are not supported
48+
* Build flow limited to RTL/Verilog source files
49+
* VHDL
50+
* HLS and OpenCL build flow not included in this HDK release
51+
* ChipScope
52+
* FPGA to FPGA communication over PCIe for F1.16xl
53+
* FPGA to FPGA over the 400Gbps Ring for F1.16xl
54+
* Aurora and Reliabile Aurora modules for the FPGA-to-FPGA
55+
* Customizable PCIe DeviceID/VendorID
56+
* Preserving the DRAM content between different AFI loads (by the same running instance)
57+
* Cadence RTL simulations tools
58+
* Synopsys RTL simulations tools
59+
* Xilinx SDAccel development environment
60+
* Additional metric counters for FPGA management tools
61+
* PCIe Slave interface supports 32-bit accesses only (can only do 32-bit accesses from Instance to FPGA), future releases will go up to 512-bit
62+
* Wider bus on ARID/AWID on DRAM and PCIe buses to allow developers to do AXI ID based routing
63+
* Emulated LED display (exposed via the Management PF)
64+
65+
## Supported Tools and Environment
66+
67+
* The HDK and SDK are designed for **Linux** environment and has not been tested on other platforms.
68+
* 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"`
69+
* The HDK build step requires having Xilinx's Vivado tool and Vivado License Management running
70+
* Vivado License need to support VU9p ES1 FPGA
71+
* Vivado License need to support encryption
72+
* This release tested and validated with Vivado 2016.3
73+
* Vivado XSIM RTL simulator supported by the HDK
74+
* MentorGraphic's Questa RTL simulator supported by the HDK (but requires a purchase of separate license from MentorGraphics)
75+
76+
## License Requirements
77+
78+
The HDK and SDK in the development kit have different licenses. SDK is licensed under open source Apache license and HDK is licensed under Amazon Software License. Please refer to [HDK License](./hdk/LICENSE.txt) and [SDK License](./sdk/LICENSE.txt).
79+
80+
## What's new
81+
82+
### 2016/12/06
83+
* Add support for configurable number of DDR controllers in the CL (see ![AWS Shell Interface Specification](./hdk/docs/AWS_Shell_Interface_Specification.md))
84+
85+
## Bug Fixes
86+
87+
This section will include any bug fixes in the future releases. Please use [HDK Bug](https://github.com/aws/aws-fpga/issues/16) and [SDK Bug](https://github.com/aws/aws-fpga/issues/17) to file bugs for HDK and SDK respectively and use [HDK Feature](https://github.com/aws/aws-fpga/issues/18) and [SDK Feature](https://github.com/aws/aws-fpga/issues/19) to file feature requests for HDK and SDK respectively. For any other general purpose requests, please use [F1 FPGA general support](https://github.com/aws/aws-fpga/issues/20).
88+
89+
## Known Issues
90+
91+
This section will include any known issues in the future releases.
92+
93+

0 commit comments

Comments
 (0)