squashing commits before moving repo to public access

Change-Id: Iec0592fc0c60b1e6c2aa7c528f563afd800bf64b

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,7 @@
+### Release version
+
+### Expected Behavior
+
+### Actual Behavior
+
+### Steps to reproduce

.gitignore

@@ -0,0 +1,31 @@
+cscope.files
+cscope.out
+tags
+simv
+simv.daidir
+csrc
+ucli.key
+vc_hdrs.h
+INCA_libs
+irun.log
+irun.key
+
+fpga-local-cmd
+
+*_compile.log
+*_run.log
+*.vpd
+.simvision
+*.vcd
+*.vcdplus*
+waves.shm
+
+*~
+.\#*
+\#*
+
+*.swp
+*.o
+.nfs*
+*.so
+*.a

FAQ.md

@@ -0,0 +1,16 @@
+# Frequently Asked Questions
+
+
+
+### Error while running `hdk_setup.sh`
+
+Q. I see error ##vivado not found## ?
+
+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
+
+
+## AFI on AWS Marketplace
+
+### Q. Do AWS Marketplace customers see FPGA source code or is it just a bitstream?
+
+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

@@ -0,0 +1,115 @@
+**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.

README.md

@@ -1,2 +1,86 @@
-# aws-fpga
-Official repository of the AWS EC2 FPGA Hardware Development Kit
+<span style="display: inline-block;">
+
+# AWS EC2 FPGA Hardware and Software Development Kit
+
+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/).
+
+Execute `git clone http://github.com/aws/aws-fpga` to download this HDK+SDK release to your EC2 Instance or local server.
+
+The [Release Notes](./RELEASE_NOTES.md) document covers the list of supported features, programming environment, and known restrictions.
+
+**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**
+
+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.
+
+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.
+
+# 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.
+
+#### Prerequisites
+* AWS FPGA HDK and SDK run in Linux environment only.
+* If you can not access GitHub repository, please request access permission from your AWS representative.
+* 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).
+* 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.
+* AWS offers FPGA Developer AMI with all Xilinx's Vivado tools and AWS CLI pre-installed.
+
+**NOTE**: The DCP generation (`Step 7`) can take up to several hours to complete. 
+We recommend that you initiate the generation in a way that prevents interruption. 
+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.  
+
+```
+$ git clone https://github.com/aws/aws-fpga     # Step 1: Download the HDK and SDK code
+$ cd aws-fpga                                   # Step 2: Move to the root directory
+$ source hdk_setup.sh                           # Step 3: Set up the HDK environment variables
+$ cd hdk/cl/examples/cl_simple                  # Step 4: Change directory to one of the provided examples
+$ export CL_DIR=$(pwd)                          # Step 5: Define this directory as the root for the CL design
+$ cd build/scripts                              # Step 6: The build directory for synthesizing, placement, timing etc
+$ source aws_build_dcp_from_cl.sh                    # Step 7: Generate a placed-and-routed design checkpoint (DCP)
+$ cd $CL_DIR/build/checkpoints/to_aws           # Step 8: This directory includes the DCP file
+$ aws s3 mb s3://<bucket-name>                 # Step 9: Create an S3 bucket (choose a unique bucket name)
+$ aws s3 cp *.SH_CL_routed.dcp \                # Step 10: Upload the DCP file to S3
+        s3://<bucket-name>/cl_simple.dcp
+$ aws ec2 create-fpga-image \                   # Step 11: Ingest the generated DCP to create an AFI  
+        --fpga-image-architecture xvu9p \
+        --shell-version 0x11241611 \
+        --fpga-pci-id deviceId=0x1d50,vendorId=0x6789,subsystemId=0x1d51,subsystemVendorId=0xfedc \
+        --input-storage-location Bucket=<bucket-name>,Key=cl_simple.dcp
+        --name MyFirstDCP
+        --logs-storage-location Bucket=<bucket-name>,Key=logs/
+```
+
+**NOTE**: The `aws ec2 create-fpga-image` command-line API is coming soon and subject to change.
+
+## Using an AFI on EC2 F1
+
+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:
+
+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.
+
+```
+$ git clone https://github.com/aws/aws-fpga   # Fetch the HDK and SDK code
+$ cd aws-fpga                                 # Move to the root directory of the repository before running the next script
+$ source sdk_setup.sh                         # Set up the envronment variables, build and install the SDK
+```
+
+**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:
+
+```
+$ sudo yum groupinstall -y “Development Tools"
+```
+
+## Need to build a new Custom Logic and register it as an AFI?
+
+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.
+

RELEASE_NOTES.md

@@ -0,0 +1,93 @@
+
+# AWS EC2 FPGA HDK+SDK Release notes
+
+# Release 1.0.0
+
+## Content
+
+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)
+
+*   AWS EC2 FPGA platform feature list:
+    *    Xilinx UltraScale+ VU9P
+    *    Interfaces available for Custom Logic(CL):
+          *    One x16 PCIe Gen 3 Interface
+          *    Four DDR4 RDIMM interfaces (with ECC)
+               *    AXI4 protocol support on all interfaces
+    *  	250 MHz base clock and asynchronous reset provided to Custom Logic(CL)
+    *    PCIE endpoint presentation to Custom Logic(CL)
+         *    Management PF (physical function)
+         *    Application PF
+    *    PCIE interface between Shell(SH) and Custom Logic(CL).
+         *    SH to CL inbound 512-bit AXI4 interface (currently supports 32-bit accesses only).
+         *    CL to SH outbound 512-bit AXI4 interface
+         *    Maximum payload size set by the Shell
+         *    Maximum read request size set by the Shell
+         *    AXI4 error handling
+         *    Proprietary AxUSER bits implemented on address channels: please refer to ![AWS Shell Interface Specification](./hdk/docs/AWS_Shell_Interface_Specification.md)        
+    *    DDR interface between SH and CL
+         *     CL to SH 512-bit AXI4 interface
+         *     1 DDR controller implemented in the SH (always available)
+         *     3 DDR controllers implemented in the CL (configurable number of implemented controllers allowed)
+
+## Implementation Restrictions
+
+*    PCIE AXI4 interfaces between Custom Logic(CL) and Shell(SH) have following restrictions:
+    *    All PCIe transactions must adhere to the PCIe Exress base spec.
+    *    4Kbyte Address boundary for all transactions(PCIe restriction).
+    *    Multiple outstanding outbound PCIe Read transactions with same ID not supported.
+    *    PCIE extended tag not supported, so read-request is limited to 32 outstanding.
+    *    Address must match DoubleWord(DW) address of the transaction.
+    *    WSTRB(write strobe) must reflect appropriate valid bytes for AXI write beats
+    *    Only Increment burst type is supported.
+    *    AXI lock, memory type, protection type, Quality of service and Region identifier are not supported.
+
+## Unsupported Features (Planned for future releases)
+
+* DMA Engine is not included with the current version of the Shell
+* Interrupts are not supported
+* Build flow limited to RTL/Verilog source files
+* VHDL
+* HLS and OpenCL build flow not included in this HDK release
+* ChipScope
+* FPGA to FPGA communication over PCIe for F1.16xl
+* FPGA to FPGA over the 400Gbps Ring for F1.16xl
+* Aurora and Reliabile Aurora modules for the FPGA-to-FPGA 
+* Customizable PCIe DeviceID/VendorID
+* Preserving the DRAM content between different AFI loads (by the same running instance)
+* Cadence RTL simulations tools
+* Synopsys RTL simulations tools
+* Xilinx SDAccel development environment
+* Additional metric counters for FPGA management tools
+* 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
+* Wider bus on ARID/AWID on DRAM and PCIe buses to allow developers to do AXI ID based routing
+* Emulated LED display (exposed via the Management PF)
+
+## Supported Tools and Environment
+
+* 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
+* Vivado License need to support VU9p ES1 FPGA
+* Vivado License need to support encryption
+* This release tested and validated with Vivado 2016.3
+* Vivado XSIM RTL simulator supported by the HDK
+* MentorGraphic's Questa RTL simulator supported by the HDK (but requires a purchase of separate license from MentorGraphics)
+
+## License Requirements
+
+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).
+
+## What's new
+
+### 2016/12/06 
+   * Add support for configurable number of DDR controllers in the CL (see ![AWS Shell Interface Specification](./hdk/docs/AWS_Shell_Interface_Specification.md)) 
+
+## Bug Fixes
+
+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).
+
+## Known Issues
+
+This section will include any known issues in the future releases.
+
+