GitHub - aws/aws-fpga at f1_small_shell (original) (raw)
⚠️ NOTE: The AWS FPGA Developer AMI based on CentOS or Amazon Linux 2 (AL2) is no longer supported. Please use the AWS-provided Ubuntu FPGA Developer AMI
Small Shell
This branch provides a Small Shell which is 30% smaller in size than the F1.X.1.4 Shell. Small Shell F1.S.1.0 occupies only 14 Clock Regions worth of real estate in the FPGA: 10 Clock Regions in Middle SLR, and 4 Clock Regions in Bottom SLR. Smaller physical footprint of the Shell F1.S.1.0 increases the available resources to the CL. This feature is available in Shell F1.S.1.0 provided in this developer kit.
⚠️ NOTE: Small Shell does not include DMA capability. Customers should implement their own DMA engine in the CL, or use SDE IP provided in the Developer Kit.
⚠️ NOTE: CL's with Small Shell F1.S.1.0 require Xilinx 2024.1 or 2020.2 tools
⚠️ NOTE: Vitis, HLx and IPI flows are not supported with Small Shell since DMA engine is not included.
Following table shows the resources available to CL in comparison with F1.X.1.4 Shell:
| FPGA Resource Type | Total Resource in VU9P FPGA | Available for CL with F1.X.1.4 Shell | Available for CL with Small Shell F1.S.1.0 | Improvement | Improvement % |
|---|---|---|---|---|---|
| CLB LUT | 1,181,768 | 895,200 | 980,272 | 85,072 | 9.50% |
| LUT as Logic | 1,181,768 | 895,200 | 980,272 | 85,072 | 9.50% |
| LUT as Memory | 591,840 | 450,720 | 493,004 | 42,284 | 9.38% |
| CLB Registers | 2,363,536 | 1,790,400 | 1,960,544 | 170,144 | 9.50% |
| CARRY8 | 147,721 | 111,900 | 122,534 | 10,634 | 9.50% |
| Block RAM Tile | 2,160 | 1,680 | 1,824 | 144 | 8.57% |
| URAM | 960 | 560 | 636 | 76 | 13.57% |
| DSPs | 6,840 | 5,640 | 6,000 | 360 | 6.38% |
| MMCM | 30 | 20 | 23 | 3 | 15.00% |
Additional Features:
- Improved FPGA <-> Host Performance by 5-20% due to increase in Number of PCIM Outstanding Read Transactions to 64. This allows CL to issue more number of read requests over PCIM and therefore achieving higher performance. This results in ~20% increase in performance for smaller read request lengths = 0x1 and 0x3; and ~5% increase in performance for request lengths = 0x7, 0xF, 0x1F and 0x3F.
- Small Shell reduces routing congestion and ease timing closure because of additional resources in the Bottom SLR.
- AWS recommends customers to place their DMA Engine in Bottom SLR because the PCIM interface between Shell<->CL is now moved to Bottom SLR.
Table of Contents
- Small Shell
- Table of Contents
- Overview of AWS EC2 FPGA Development Kit
- Getting Started
- Documentation Overview
- Developer Support
Overview of AWS EC2 FPGA Development Kit
AWS EC2 FPGA Development Kit is a set of development and runtime tools to develop, simulate, debug, compile and run hardware accelerated applications on Amazon EC2 F1 instances. It is distributed between this github repository and FPGA Developer AMI (Ubuntu) provided by AWS with no cost of development tools.
⚠️ NOTE: The developer kit is supported for Linux operating systems only.
Development Flow
After creating an FPGA design (also called CL - Custom logic), developers can create an Amazon FPGA Image (AFI) and easily deploy it to an F1 instance. AFIs are reusable, shareable and can be deployed in a scalable and secure way.
Development Environments
| Development Environment | Description | Accelerator Language | Hardware Interface | Debug Options | Typical Developer |
|---|---|---|---|---|---|
| Hardware Accelerator Development using Vivado | Fully custom hardware development experience provides hardware developers with the tools required for developing AFIs for AWS FPGA instances | Verilog/VHDL | XDMA Driver, peek/poke | Simulation, Virtual JTAG | HW Developer with advanced FPGA experience |
For on-premise development, Vivado must have the correct license and use one of the supported tool versions.
FPGA Developer AMI
The FPGA Developer AMI is available on the AWS marketplace without a software charge and includes tools needed for developing FPGA Designs to run on AWS F1.
Given the large size of the FPGA used inside AWS F1 Instances, Xilinx tools work best with 32GiB Memory. z1d.xlarge/c5.4xlarge and z1d.2xlarge/c5.8xlarge instance types would provide the fastest execution time with 30GiB+ and 60GiB+ of memory respectively. Developers who want to save on cost, could start coding and run simulations on low-cost instances, like t2.2xlarge, and move to the aforementioned larger instances to run the synthesis of their acceleration code.
AWS marketplace offers multiple versions of the FPGA Developer AMI. The following compatibility table describes the mapping of currently supported developer kit versions to AMI versions:
| Developer Kit Version | Tool Version Supported | Compatible FPGA Developer AMI Version |
|---|---|---|
| 1.6.1+ | 2024.1 | v1.16.X (Xilinx Vivado/Vitis 2024.1) |
Getting Started
Getting familiar with AWS
If you have never used AWS before, we recommend you start with AWS getting started training, and focus on the basics of the AWS EC2 and AWS S3 services. Understanding the fundamentals of these services will make it easier to work with AWS F1 and the FPGA Developer Kit.
FPGA Image generation and EC2 F1 instances are supported in the us-east-1 (N. Virginia), us-west-2 (Oregon), eu-west-1 (Ireland) and us-gov-west-1 (GovCloud US) regions.
⚠️ NOTE: By default, your AWS Account will have an EC2 F1 Instance launch limit of 0. Before using F1 instances, you will have to open a Support Case to increase the EC2 Instance limits to allow launching F1 instances.
Setting up development environment for the first time
You have the choice to develop on AWS EC2 using the FPGA Developer AMI or on-premise.
ℹ️ INFO: We suggest starting with the FPGA Developer AMI with build instances on EC2 as it has Xilinx tools and licenses setup for you to be able to quickly get into development.
ℹ️ INFO: For on-premise development, you will need to have Xilinx tools and licenses available for you to use
- Start a Build Instance first to start your development.
💡 TIP: This instance does not have to be an F1 instance. You only require an F1 instance to run your AFI's(Amazon FPGA Image) once you have gone through your design build and AFI creation steps.
ℹ️ INFO: If you need to follow GUI Development flows, please checkout our Developer Resources where we provide Step-By-Step guides to setting up a GUI Desktop. - Clone the small_shell branch of FPGA Developer Kit on your instance.
git clone -b small_shell https://github.com/aws/aws-fpga.git - Follow the quickstarts from the next section.
- Review the F1.S.1.0 shell migration guide for help with migrating from shell F1.X.1.4 to small shell F1.S.1.0
Quickstarts
Before you create your own AWS FPGA design, we recommend that you go through one of the step-by-step Quickstart guides:
| Description | Quickstart | Next Steps |
|---|---|---|
| Custom Hardware Development(HDK) | HDK hello_world Quickstart | CL to Shell and DRAM connectivity example, Virtual Ethernet Application using the Streaming Data Engine |
Documentation Overview
Documentation is located throughout this developer kit and the table below consolidates a list of key documents to help developers find information:
| Topic | Document Name | Description |
|---|---|---|
| AWS setup | Setup AWS CLI and S3 Bucket | Setup instructions for preparing for AFI creation |
| Developer Kit | RELEASE NOTES | Release notes for all developer kit features, excluding the shell |
| Developer Kit | Errata | Errata for all developer kit features, excluding the shell |
| Migration Guidelines | Migration guide | Migration guidelines for moving from XDMA shell F1.X.1.4 to small shell F1.S.1.0 |
| F1 Shell | AWS Shell RELEASE NOTES | Release notes for F1 shell |
| F1 Shell | AWS Shell ERRATA | Errata for F1 shell |
| F1 Shell | AWS Shell Interface Specification | Shell-CL interface specification for HDK developers building AFI |
| F1 Shell - Timeout and AXI Protocol Protection | How to detect a shell timeout | The shell will terminate transactions after a time period or on an illegal transaction. This describes how to detect and gather data to help debug CL issues caused by timeouts. |
| HDK - Host Application | Programmer View | Host application to CL interface specification |
| HDK - CL Debug | Debug using Virtual JTAG | Debugging CL using Virtual JTAG (Chipscope) |
| HDK - Simulation | Simulating CL Designs | Shell-CL simulation specification |
| HDK - Driver | README | Describes the XDMA driver used by HDK examples and includes a link to an installation guide |
| AFI | AFI Management SDK | CLI documentation for managing AFI on the F1 instance |
| AFI - EC2 CLI | copy_fpga_image, delete_fpga_image, describe_fpga_images, fpga_image_attributes | CLI documentation for administering AFIs |
| AFI - Creation Error Codes | create_fpga_image_error_codes | CLI documentation for managing AFIs |
| AFI - Power | FPGA Power, recovering from clock gating | Helps developers with understanding FPGA power usage, preventing power violations on the F1 instance and recovering from a clock gated slot. |
| On-premise Development | Tools, Licenses required for on-premise development | Guidance for developer wanting to develop AFIs from on-premises instead of using the FPGA Developer AMI |
| Frequently asked questions | FAQ | Q/A are added based on developer feedback and common AWS forum questions |
Developer Support
- The Amazon FPGA Development User Forum is the first place to go to post questions, learn from other users and read announcements.
- We recommend joining the AWS forums to engage with the FPGA developer community, AWS and Xilinx engineers to get help.
- You could also file a Github Issue for support. We prefer the forums as this helps the entire community learn from issues, feedback and answers.
- Click the "Watch" button in GitHub upper right corner to get regular updates.