v1.3.7 Release (#399)

* v1.3.7 Release to RC

* Update init.sh

* v1.3.7 Release to RC

* Update ERRATA.md

* Update README.md

* Update RELEASE_NOTES.md

* Update README.md

* Update FAQ.md

* Update README.md

Author: kristopk

.gitignore

@@ -35,7 +35,10 @@ waves.shm
 *.a
 *.ko
 
-!SDAccel/aws_platform/xilinx_aws-vu9p-f1_1ddr-xpr-2pr_4_0/libxilinxopencl.so
+!SDAccel/aws_platform/xilinx_aws-vu9p-f1_1ddr-xpr-2pr_4_0/sw/lib/x86_64/libxilinxopencl.so
+!SDAccel/aws_platform/xilinx_aws-vu9p-f1_4ddr-xpr-2pr_4_0/sw/lib/x86_64/libxilinxopencl.so
+!SDAccel/aws_platform/xilinx_aws-vu9p-f1_4ddr-xpr-2pr-debug_4_0/sw/lib/x86_64/libxilinxopencl.so
+!SDAccel/aws_platform/xilinx_aws-vu9p-f1_dynamic_5_0/sw/lib/x86_64/libxilinxopencl.so 
 
 nohup.out
 *.nohup.out

.gitmodules

@@ -1,4 +1,7 @@
-[submodule "SDAccel/examples/xilinx"]
-	path = SDAccel/examples/xilinx
+[submodule "SDAccel/examples/xilinx_2017.1"]
+	path = SDAccel/examples/xilinx_2017.1
 	url = https://github.com/Xilinx/SDAccel_Examples.git
 	branch = 2017.1
+[submodule "SDAccel/examples/xilinx_2017.4"]
+	path = SDAccel/examples/xilinx_2017.4
+	url = https://github.com/Xilinx/SDAccel_Examples.git

ERRATA.md

@@ -22,9 +22,13 @@
 * Aurora and Reliable Aurora modules for the FPGA-to-FPGA 
 * Preserving the DRAM content between different AFI loads (by the same running instance)
 * Cadence Xcelium simulations tools
+* Questa 10.6b simulations tools have not been tested.  Xilinx 2017.4 tools only support Questa 10.6b.   
 * PCIM and DMA-PCIS AXI-4 interfaces do not support AxSIZE other than 3'b110 (64B)
 
 ## Known Bugs/Issues
-* F1 CL designs using the v1.3 Shell must treat all clocks within the same group as asynchronous.  For example:  If using clk_main_a1, clk_extra_a1, clk_extra_a2, and clk_extra_a3 they need to be asynchronous.  See [AWS Shell Interface Specification](./hdk/docs/AWS_Shell_Interface_Specification.md)
-* The API fpga-load-local-image, has a bug in the error messaging which does not indicate a PCI ID mismatch occurred.  The PCI ID’s listed in the AFI manifest when an AFI is submitted to the CreateFpgaImage api (Vendor ID, Device ID, SubSystem ID, or SubSystem Vendor ID) should match the actual values in the submitted DCP. If there is a mismatch between the manifest IDs and the actual device ID, calling fpga-load-local-image on the AFI should report back load-failed (error 7), with a sub-error indicating there is a device ID mismatch. However, fpga-load-local-image does not report the sub-error, leaving no description as to why the load has failed.  Until this issue has been fixed, if you experience an AFI load-failed when loading the AFI,  double check the device IDs in the submitted manifest match the device IDs in the DCP.
 
+* AXI-L Interface ordering - The v071417d3 shell has an issues that impacts transaction ordering on the AXI-L interfaces (BAR1, OCL, SDA) only.  The Shell should preserve PCIe ordering rules on these interfaces, but there is an issue where a read request may pass a previous write request.  The shell terminates a write when the data is transferred on the W channel (WVALID/WREADY) rather than wait for the response on the B channel.  A CL workaround for this issue is to backpressure reads (deassert ARREADY) when there are any writes pending.
+* Linux kernel 3.10.0-862.2.3.el7.x86_64.  By default, the AWS Developer AMI GUI setup script updates the kernel version. We have provided a patch to prevent kernel updates during GUI setup. Instead of running the setup_gui.sh as documented/included within the developer AMI, please use the patched script as shown below:
+$curl https://s3.amazonaws.com/aws-fpga-developer-ami/1.4.0/Scripts/setup_gui.sh -o /home/centos/src/scripts/setup_gui.sh
+$/home/centos/src/scripts/setup_gui.sh
+ 

FAQs.md

@@ -3,39 +3,56 @@
 # Table of Contents
 
 1. [AWS EC2 FPGA Hardware and Software Development Kits](#devkit)
+    - [FPGA Developer AMI available on AWS Marketplace](#devAmi)
     - [FPGA Hardware Development Kit Workflow(HDK)](#fpgahdk)
-    - [GUI Workflow with Vivado IP Integrator (IPI)](#ipi)    
+    - [GUI Workflow with Vivado IP Integrator (IPI)](#ipi)
     - [FPGA Software Development Kit (SDK)](#fpgasdk)
     - [OpenCL Development Environment with Amazon EC2 F1 FPGA Instances to accelerate your C/C++ applications](#sdaccel)
-    - [FPGA Developer AMI available on AWS Marketplace](#devAmi)
     - [Developer Support](#devSupport)
 2. [Building an example AFI](#buildingAnExample)
     - [Prerequisites](#buildingafiprereq)
     - [Using an AFI on EC2 FPGA Instances](#usingAfi)
 
 <a name="devkit"></a>
-# AWS EC2 FPGA Hardware and Software Development Kits 
+# AWS EC2 FPGA Hardware and Software Development Kits
 
-The AWS EC2 FPGA Hardware and Software Development Kits include two portions: Development workflows for developing Amazon FPGA Image (AFI) with the [HDK](./hdk) or the GUI workflow, and [SDK](./sdk) for using AFIs on FPGA-enabled EC2 instances [such as F1](https://aws.amazon.com/ec2/instance-types/f1/).
+The AWS EC2 FPGA Hardware and Software Development Kits consists of three components: Hardware development workflows for developing Amazon FPGA Image (AFI) with the [HDK](./hdk), Software development workflows for developing AFI with [OpenCL/C/C++](./SDAccel) and [SDK](./sdk) for using AFIs on FPGA-enabled EC2 instances [such as F1](https://aws.amazon.com/ec2/instance-types/f1/).
 
-Execute `git clone https://github.com/aws/aws-fpga.git` to download this HDK+SDK release to your EC2 Instance or local server.
+Execute `git clone https://github.com/aws/aws-fpga.git` to download this HDK+SDAccel+SDK release to your EC2 Instance or local server.
 For an SSH connection execute `git clone [email protected]:aws/aws-fpga.git`. [To get help with connecting to Github via SSH](https://help.github.com/articles/connecting-to-github-with-ssh/)
 
-The [Release Notes](./RELEASE_NOTES.md) document covers the list of supported features, programming environments, and known restrictions.
+The [Release Notes](./RELEASE_NOTES.md) and [Errata](./ERRATA.md) list supported features, programming environments, 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**
+**NOTE: This developer kit is 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.
 
+<a name="devAmi"></a>
+## FPGA Developer AMI
+
+AWS Marketplace offers the [FPGA developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) for development on EC2 instances. The FPGA Developer AMI comes with Xilinx tools and AWS CLI pre-installed.  The HDK examples and quick start can be run on any [C4/C5/M4/M5/R4/T2.2XLARGE](https://aws.amazon.com/ec2/instance-types/) EC2 instance. Given the large size of the FPGA used in AWS FPGA instances, the implementation tools require 32GiB Memory (ex: C4.4XLarge, M4.2XLarge, R4.XLarge, T2.2XLarge). C4.4XLarge and C4.8XLarge would provide the fastest execution time with 30 and 60GiB of memory respectively.
+
+This release supports Xilinx SDx 2017.4 and 2017.1.  The compatibility table describes the mapping of developer kit version to [FPGA developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) version:  
+
+| Developer Kit Version   | Tool Version Supported     |  Compatible FPGA developer AMI Version     |
+|-----------|-----------|------|
+| 1.3.0-1.3.6 | 2017.1 | v1.3.5 |
+| 1.3.7-1.3.X | 2017.1 | v1.3.5-v1.3.X (Xilinx SDx 2017.1) |
+| 1.3.7-1.3.X | 2017.4 | v1.4.0-v1.4.X (Xilinx SDx 2017.4) |
+
+FPGA developer kit version is listed in [hdk_version.txt](./hdk/hdk_version.txt)
+
+FPGA developer kit supported tool versions are listed in [supported_vivado_versions](./supported_vivado_versions.txt)
+
 <a name="fpgahdk"></a>
-## FPGA HDK 
+## FPGA HDK
 
 The [HDK directory](./hdk) contains useful information and scripts 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 on-premises server or an EC2 instance. The HDK is not required if you are using a pre-built AFI and not planning to build your own AFI. The following resources provide further details:
 
 [HDK README](./hdk/README.md)
-        
+
 [AWS FPGA Shell Interface Specification](./hdk/docs/AWS_Shell_Interface_Specification.md)
-        
+
 [FPGA PCIe Address Map](./hdk/docs/AWS_Fpga_Pcie_Memory_Map.md)
 
 <a name="ipi"></a>
@@ -44,7 +61,7 @@ The [HDK directory](./hdk) contains useful information and scripts for developer
 Developers have the option of working in a GUI mode using Vivado IPI.  With IPI you can create complex F1 custom designs on a graphical interface design canvas.  The HDK development kit provides AWS FPGA IP which will help you quickly develop your custom designs by enabling you to quickly drop in IP blocks into your design.
 
 The IPI flow isolates the Custom Logic (CL) from the shell, allowing the developer to focus on differentiating logic and leave the heavy lifting, undifferentiated hardware interfaces development to the AWS FPGA Shell.  Generating a logic diagram is simplified with designer automation that connects RTL, IP, and peripherals like DDR and PCIe in a correct by construction flow.  The “what you see is what you get” tool generates the equivalent code by instantiating the underlying IP and RTL with access via the Vivado project to the entire FPGA hardware design flow.  A video walk through of this flow for a simple diagram is available at https://www.xilinx.com/video/hardware/using-vivado-ip-integrator-and-amazon-f1.html.  This flow example is a good starting point for developers who want to quickly add IP blocks with high performance access to multiple external memories.
- 
+
 The IPI RTL flow enables the developer a single graphical environment to add sources and IP, simulate, synthesize the RTL, and then stitch together the Custom Logic (CL) with the Shell’s design checkpoint (DCP).  For design debug, developers can easily instantiate logic analyzers or other debug logic, investigate timing and resource reports, and quickly link from implementation messages to the design view and source code when applicable.  This flow is a good starting point for experts in RTL design or designs who have a minimal amount of interconnection between RTL modules.
 
 The below documentation covers the setup, tutorials of the IPI flows and IPI FAQ.  Developers are advised to read all documents before starting their first AWS FPGA design with IPI.  
@@ -56,7 +73,7 @@ The below documentation covers the setup, tutorials of the IPI flows and IPI FAQ
 [IPI Developer Flow](./hdk/docs/IPI_GUI_Flows.md)
 
 [IPI FAQ](./hdk/docs/IPI_GUI_Vivado_FAQ.md)
-        
+
 <a name="fpgasdk"></a>
 ## FPGA SDK
 
@@ -71,24 +88,19 @@ The [SDK directory](./sdk) includes the runtime environment required to run on E
 <a name="sdaccel"></a>
 ## OpenCL Development Environment with Amazon EC2 F1 FPGA Instances to accelerate your C/C++ applications
 
-The OpenCL development environment allows customers to use OpenCL with Amazon EC2 F1 FPGA Instances to accelerate their C/C++ applications. Software developers with little to no FPGA experience, will find a familiar development experience and now can use the cloud-scale availability of FPGAs to supercharge their applications. 
+The OpenCL development environment allows customers to use OpenCL with Amazon EC2 F1 FPGA Instances to accelerate their C/C++ applications. Software developers with little to no FPGA experience, will find a familiar development experience and now can use the cloud-scale availability of FPGAs to supercharge their applications.
 
-Kernels are expressed in OpenCL or C/C++ and accelerated by implementing them in custom FPGA hardware. In addition, the development environment from Xilinx called SDAccel allows the acceleration to be performed using pre-existing RTL designs. 
+Kernels are expressed in OpenCL or C/C++ and accelerated by implementing them in custom FPGA hardware. In addition, the development environment from Xilinx called SDAccel allows the acceleration to be performed using pre-existing RTL designs.
 
 This developer kit has 50+ examples to help you get started on FPGA acceleration.  To get started, review the [SDAccel README](SDAccel/README.md)
 
-<a name="devAmi"></a>
-## FPGA Developer AMI 
-
-AWS Marketplace offers the [FPGA developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) for development on EC2 instances. The FPGA Developer AMI comes with Xilinx tools and AWS CLI pre-installed.  The HDK examples and quick start can be run on any [C4/M4/R4/T2.2XLARGE](https://aws.amazon.com/ec2/instance-types/) EC2 instance. Given the large size of the FPGA used in AWS FPGA instances, the implementation tools require 32GiB Memory (C4.4XLarge, M4.2XLarge, R4.XLarge, T2.2XLarge). C4.4XLarge and C4.8XLarge would provide the fastest execution time with 30 and 60GiB of memory respectively.
-
 <a name="devSupport"></a>
-## Developer Support 
+## Developer Support
 
-The [**Amazon FPGA Development User Forum**](https://forums.aws.amazon.com/forum.jspa?forumID=243&start=0) is the first place to go to post questions, learn from other users and read announcements from the EC2 FPGA team. 
+The [**Amazon FPGA Development User Forum**](https://forums.aws.amazon.com/forum.jspa?forumID=243&start=0) is the first place to go to post questions, learn from other users and read announcements from the EC2 FPGA team.
 
 * To be notified on important messages click on the “Watch Forum” button on the right side of the screen.
-* In case you can't see "Your Stuff" details, you will need to logout using the logout button on the forums page and log back in again. 
+* In case you can't see "Your Stuff" details, you will need to logout using the logout button on the forums page and log back in again.
 
 <a name="buildingAnExample"></a>
 # Building a Custom Logic AFI for AWS FPGA Instances
@@ -117,8 +129,8 @@ By following the example CLs, a developer will learn how to interface to the AWS
 ### Prerequisites
 * AWS FPGA HDK and SDK run in Linux environment only.
 
-* The build stage uses Xilinx's Vivado tool set. In case you build on-premises you should have an installed Vivado that has the correct license.  Please check for [supported versions of Vivado](./hdk/supported_vivado_versions.txt). [Release Notes](./RELEASE_NOTES.md) may contain additional information.
-* 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 the same AWS region as your S3 bucket via `aws configure` command line. It’s also required that your instance and the S3 bucket where the tarball reside in will be in the same AWS region.  Please refer to [AWS documentation for help with configuring the AWS CLI.](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)   
+* The build stage uses Xilinx's Vivado tool set. In case you build on-premises you should have an installed Vivado that has the correct license.  Please check for [supported versions of Vivado](./supported_vivado_versions.txt). [Release Notes](./RELEASE_NOTES.md) may contain additional information.
+* 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 the same AWS region as your S3 bucket via `aws configure` command line. It’s also required that your instance and the S3 bucket where the tarball reside in will be in the same AWS region.  Please refer to [AWS documentation for help with configuring the AWS CLI.](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
 
 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 FPGA instance.