Release v1.4.15 (#496)

* Add Vitis Debug document (#601)

    * Create Debug_OpenCL_Kernel.md
    * Update and rename Debug_OpenCL_Kernel.md to Debug_Vitis_Kernel.md

* Updated the shell interface spec to reflect current shell (#603)

    * Updated the shell interface spec to reflect current shell and pointed to the DDR Data Retention doc
    * Update hdk/docs/AWS_Shell_Interface_Specification.md

* Enhance DDR Model Build qualifiers in hdk_setup.sh script. (#604)

    * Enhance DDR Model Build qualifiers in hdk_setup.sh script.
    * Enhance the DDR model build's lock file creation+check to not rely on external tools.

* Update Virtual_JTAG_XVC.md (#606)

* AR73068 patching (#608)

    * Added patching mechanism for Vivado AR73068
    * Updated supported versions

* Added dma range error to interrupt status register metrics (#591)

    * added dma range error to interrupt status register metrics
    * updated tests to match change to output

* Fixing test_fpga_tools to accomodate dma range error addition.  (#609)
    * Fixed the lines where we expect ` clock group c `

Author: deeppat

.gitignore

@@ -110,3 +110,4 @@ patches/*
 .batch
 .temp
 
+.python-version

ERRATA.md

@@ -9,14 +9,25 @@
 * DRAM Data retention is not supported for CL designs with less than 4 DDRs enabled
 * Combinatorial loops in CL designs are not supported.  
 * Connecting one of the clocks provided from the shell (clk_main_a0, clk_extra_a1, etc...) directly to a BUFG in the CL is not supported by the Xilinx tools and may result in a non-functional clock. To workaround this limitation, it is recommended to use an MMCM to feed the BUFG (clk_from_shell -> MMCM -> BUFG). Please refer to [Xilinx AR# 73360](https://www.xilinx.com/support/answers/73360.html) for further details.
+
+### Xilinx Design Advisory for UltraScale/UltraScale+ DDR4/DDR3 IP - Memory IP Timing Exceptions (AR# 73068)
+AWS EC2 F1 customers using the DDR4 IP in customer logic (HDK or SDAccel/Vitis designs) may be impacted by a recent design advisory from Xilinx.
+
+AWS customers may experience hardware failures including: post calibration data errors and DQS gate tracking issues. The error condition is build dependent and errors would need to be detected on the first write/read access after a successful calibration to prevent further data corruption.
+
+To detect if your build is impacted by this bug, AWS recommends all EC2 F1 customers utilizing the DDR4 IP in their designs should run a TCL script on the design checkpoint point (DCP) to check to determine if the design is susceptible to this issue. If the check passes, your design is safe to use as the hardware will function properly. 
+If the check fails, the design is susceptible to the issue and will need to be regenerated using the same tool version with the AR 73068 patch. 
+For designs under development, we recommend applying the patch to your on-premises tools or update to developer kit v1.4.15. 
+For additional details, please refer to the [Xilinx Answer Record #73068](https://www.xilinx.com/support/answers/73068.html)
+
 ### 2019.1 
 * Vivado `compile_simlib` command fails to generate the following verilog IP libraries for the following simulators.
+* Please refer to the Xilinx Answer record for details.
 
-| Library(verilog) | Simulator |
-|---|---|
-| `sync_ip` | Cadence IES |
-| `hdmi_gt_controller_v1_0_0` | Synopsys VCS |
-* We are working with Xilinx to provide a fix for these.
+| Library(verilog) | Simulator | Xilinx Answer Record | 
+|---|---|---|
+| `sync_ip` | Cadence IES | [AR72795](https://www.xilinx.com/support/answers/72795.html) |
+| `hdmi_gt_controller_v1_0_0` | Synopsys VCS | [AR72601](https://www.xilinx.com/support/answers/72601.html) |
 
 ## SDK
 

README.md

@@ -5,8 +5,8 @@
 1. [Overview of AWS EC2 FPGA Development Kit](#overviewdevkit)
     - [Development environments](#overviewdevenv)
     - [Runtime environments](#overviewrunenv)
-    - [Example applications](#overviewexapps)
     - [Development tools](#overviewdevtools)
+    - [Example applications](#overviewexapps)
 2. [Getting Started](#gettingstarted)
 3. [FPGA Developer AMI available on AWS Marketplace](#devAmi)
 4. [FPGA Hardware Development Kit (HDK)](#fpgahdk)
@@ -18,7 +18,9 @@
 <a name="overviewdevkit"></a>
 # Overview of AWS EC2 FPGA Development Kit
 
-The AWS EC2 FPGA Development Kit is provided by AWS to support development and runtime on [AWS FPGA instances](https://aws.amazon.com/ec2/instance-types/f1/).  Amazon EC2 FPGA instances are high-performance compute instances with field programmable gate arrays (FPGAs) that are programmed to create custom hardware accelerations in EC2. F1 instances are easy to program and AWS provides everything needed to develop, simulate, debug, compile and run hardware accelerated applications.  Using the [FPGA Developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ), developers create an FPGA design. Once the FPGA design (also called CL - Custom logic) is complete, developers create the Amazon FPGA Image (AFI), and easily deploy it to the F1 instance. AFIs are reusable, shareable and can be deployed in a scalable and secure way.
+AWS EC2 FPGA Development Kit is a set of free development and runtime tools that provide everything needed to develop, simulate, debug, compile and run hardware accelerated applications on [Amazon EC2 F1 instances](https://aws.amazon.com/ec2/instance-types/f1/), EC2 F1 instances are high-performance compute instances with field programmable gate arrays (FPGAs) that enable the development and deployment of custom hardware accelerators on AWS cloud.
+
+AWS EC2 FPGA Development Kit content is distributed between this github repository and [FPGA Developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) provided by AWS, developers are able to develop, simulate and debug an FPGA design on compute [EC2 instance](https://aws.amazon.com/ec2/) with no cost of development or runtime tools. Once the FPGA design (also called CL - Custom logic) is complete, developers create the Amazon FPGA Image (AFI), and easily deploy it to the F1 instance. AFIs are reusable, shareable and can be deployed in a scalable and secure way.
 ![Alt text](hdk/docs/images/f1-Instance-How-it-Works-flowchart.jpg)
 
 <a name="overviewdevenv"></a>
@@ -78,13 +80,12 @@ The AWS EC2 FPGA Development Kit is provided by AWS to support development and r
 <a name="gettingstarted"></a>
 # Getting Started
 
-### New to AWS?
+### Getting familiar with AWS
 If you have never used AWS before, we recommend you start with [AWS getting started training](https://aws.amazon.com/getting-started/), and focus on the basics of the [AWS EC2](https://aws.amazon.com/ec2/) and [AWS S3](https://aws.amazon.com/s3/) services.  Understanding the fundamentals of these services will make it easier to work with AWS FPGAs.
 
 AWS FPGA 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](https://aws.amazon.com/govcloud-us/)) [regions](https://aws.amazon.com/about-aws/global-infrastructure/).
 
-
-### New to AWS FPGAs and setting up a development environment?
+### Setting up development environment for the first time 
 The developer kit is supported for Linux operating systems only. 
 You have the choice to develop on AWS EC2 using the [FPGA Developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) or on-premises. Within a linux environment, you can execute `git clone https://github.com/aws/aws-fpga.git` to download the latest release to your EC2 Instance or local server.  Help on cloning from github is available [here](https://help.github.com/articles/which-remote-url-should-i-use/). When using a 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/).
 

RELEASE_NOTES.md

@@ -24,6 +24,12 @@
          *    1 DDR controller implemented in the SH (always available)
          *    3 DDR controllers implemented in the CL (configurable number of implemented controllers allowed)
 
+## Release 1.4.15 (See [ERRATA](./ERRATA.md) for unsupported features)
+* Added Xilinx AR#73068 patching
+* Added DMA range error to the interrupt status register metrics
+* Enhanced DDR model rebuild qualifiers in hdk_setup.sh 
+* Updated Virtual JTAG Documentation
+
 ## Release 1.4.14 (See [ERRATA](./ERRATA.md) for unsupported features)
 * Updated Vitis Platform file to fix a DDR bandwidth issue
 * Added Vitis Debug Documentation

SDAccel/examples/3rd_party/README.md

@@ -81,7 +81,6 @@ make TARGETS=hw DEVICES=$AWS_PLATFORM all
 
 * For more information on running this example on an F1 instance, see [this](../../README.md#runonf1).
 
-
 ## Xilinx and third party Implementation Differences
 #### Host Code
 | third party FPGA     | Xilinx     |
@@ -104,18 +103,12 @@ make TARGETS=hw DEVICES=$AWS_PLATFORM all
 | declares and initializes an struct object together | declare an struct object and then initialize it separately |
 
 ## SUPPORT
-For more information check here:
-[SDAccel User Guides][]
+For more information check the [SDAccel User Guides](http://www.xilinx.com/support/documentation-navigation/development-tools/software-development/sdaccel.html?resultsTablePreSelect=documenttype:SeeAll#documentation)
 
-For questions and to get help on this project or your own projects, visit the [SDAccel Forums][].
+For questions and to get help on this project or your own projects, visit the [SDAccel Forums](https://forums.xilinx.com/t5/SDAccel/bd-p/SDx)
 
 ## REVISION HISTORY
 
 Date    | Readme Version | Revision Description
 --------|----------------|-------------------------
 SEP2017 | 1.0            | Initial release
-
-
-
-[SDAccel Forums]: https://forums.xilinx.com/t5/SDAccel/bd-p/SDx
-[SDAccel User Guides]: http://www.xilinx.com/support/documentation-navigation/development-tools/software-development/sdaccel.html?resultsTablePreSelect=documenttype:SeeAll#documentation

hdk/common/verif/scripts/.gitignore

@@ -0,0 +1,2 @@
+.done
+

hdk/common/verif/scripts/Makefile

@@ -0,0 +1,34 @@
+#-------------------------------------------------------------------------------
+# Amazon FPGA Hardware Development Kit
+#
+# Copyright 2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Amazon Software License (the "License"). You may not use
+# this file except in compliance with the License. A copy of the License is
+# located at
+#
+#    http://aws.amazon.com/asl/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or
+# implied. See the License for the specific language governing permissions and
+# limitations under the License.
+#-------------------------------------------------------------------------------
+
+DONE_FILE := $(HDK_COMMON_DIR)/verif/scripts/.done
+DEPS_FILE := $(HDK_SHELL_DESIGN_DIR)/ip/ddr4_core/ddr4_core.xci
+DEPS_FILE += $(HDK_COMMON_DIR)/verif/scripts/init.tcl
+DEPS_FILE += $(HDK_COMMON_DIR)/verif/scripts/init.sh
+
+all: $(DONE_FILE)
+
+$(DONE_FILE): $(DEPS_FILE)
+	@ echo "INFO: Building in $(shell dirname $@)"
+	@ echo "INFO: This could take 5-10 minutes, please be patient!"
+	@ git clean -fXdq $(shell dirname $@)
+	@ cd $(shell dirname $@)\
+	&& ./init.sh $(MODEL_DIR)\
+	&& echo "INFO: DDR4 model build passed."\
+	|| (echo "ERROR: DDR4 model build failed." && exit 2)
+	@ touch $@
+

hdk/common/verif/scripts/init.sh

@@ -16,12 +16,12 @@
 # limitations under the License.
 
 if [[ ":$HDK_COMMON_DIR" == ":" ]]; then
-  echo "error: HDK_COMMON_DIR not set. Source hdk_setup.sh first."
+  echo "ERROR: HDK_COMMON_DIR not set. Source hdk_setup.sh first."
   exit 2
 fi
 
 if [[ ":$VIVADO_VER" == ":" ]]; then
-  echo "error: VIVADO_VER not set. Source hdk_setup.sh first."
+  echo "ERROR: VIVADO_VER not set. Source hdk_setup.sh first."
   exit 2
 fi
 
@@ -39,12 +39,12 @@ lockfile_filename=$models_dir/build.lock
 # Prevent multiple users from building in the same directory.
 # Set the number of retries to 0 so that we will just fail
 # and let the other process complete the build.
-if [ -e /bin/lockfile ]; then
-  if ! lockfile -r 0 $lockfile_filename; then
-    echo "error: $lockfile_filename exists"
-    echo "error: Another process is already building the models."
-    exit 2
-  fi
+if [ -e $lockfile_filename ]; then
+  echo "ERROR: $lockfile_filename exists"
+  echo "ERROR: Another process is already building the models."
+  exit 2
+else
+  touch $lockfile_filename
 fi
 
 echo "$VIVADO_VER" > $models_dir/.vivado_version

hdk/docs/AFI_Manifest.md

@@ -40,6 +40,7 @@ The manifest file is a text file formatted with key=value pairs. Some keys are m
 
 | vivado tool version | field value |
 |------------------- | -----------|
+| 2019.2 |  tool_version=v2019.2 |
 | 2019.1 |  tool_version=v2019.1 |
 | 2018.3 |  tool_version=v2018.3 |
 | 2018.2 |  tool_version=v2018.2 | 

hdk/docs/AWS_Shell_Interface_Specification.md

@@ -222,9 +222,10 @@ These parameters are used to control which DDR controllers are impemented in the
               ...
  ```   
 
-### DRAM Content Preservation between AFI Loads (Future)
+### DRAM Content Preservation between AFI Loads
 
-In future Shell versions a DRAM content preservation feature will be implemented. This feature allows the DDR state to be preserved when dynamically changing CL logic. The current Shell version will not guarantee preservation of DRAM contents if the CL logic is re-loaded.
+Shell version 1.4 allows the DDR state to be preserved when dynamically changing CL logic. Any AFI generated with a v1.4 shell will enable DRAM content preservation by default.
+Please refer to the [guide on how to use the DRAM data retention mode to preserve the content of DRAM across AFI loads](./data_retention.md) for more details on utilizing this feature.
 
 <a name="dma"></a>
 ## DMA
@@ -649,12 +650,6 @@ It is ideal to place logic that interfaces to the shell in the same SLR as the S
 For the interfaces that are in both the MID/BOTTOM the recommendation is to use flops for pipelining, but don’t constrain to an SLR.  Also it is recommended to not use the SDA interface because it spans two SLR's (use BAR1 or OCL instead). You can constrain logic to a particular SLR by creating PBLOCKs (one per SLR), and assigning logic to the PBLOCKs (refer to cl_dram_dma example [cl_pnr_user.xdc](../cl/examples/cl_dram_dma/build/constraints/cl_pnr_user.xdc)).
 Dataflow should be mapped so that SLR crossing is minimized (for example a pipeline should be organized such that successive stages are mostly in the same SLR).
 
-Here’s an example post on the Xilinx forum which points to some documentation related to solving this:
-<https://forums.xilinx.com/t5/UltraScale-Architecture/Ultrascale-SLR-crossing/td-p/798435>
-
-There are some good timing closure tips in this methodology doc pointed to by the Xilinx forum post:
-<https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_1/ug949-vivado-design-methodology.pdf>
-
 <a name="impl_tips_logic_levels"></a>
 ### Logic Levels
 You can report all paths that are greater than a certain number of logic levels.  This can be used to iterate on timing in synthesis rather than waiting for place and route.  For example at 250MHz a general rule of thumb is try to keep logic levels to around 10.  The following commands report on all paths that have more than 10 logic levels:
@@ -692,13 +687,10 @@ You have to be careful that pipeline registers do not infer a shift register com
 
 <a name="impl_tips_vivado"></a>
 ### Vivado Analysis  
-Vivado has some nice analysis capabilities:
+Vivado has the following analysis capabilities:
 * report_methodology (includes CDC report)
 * clock interaction report (see if paths between async clocks are erroneously being timed)
 * congestion heat map
 * power analysis
 * physical implementation analysis (placement, routing)
 * linked timing/schematic/physical views 
-
-<https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_4/ug906-vivado-design-analysis.pdf>
-

hdk/docs/Virtual_JTAG_XVC.md

@@ -142,6 +142,7 @@ To connect the debug Xilinx Hardware Manager to Virtual JTAG XVC server on the t
 
 `> connect_hw_server -url <hostname or IP address>:3121`
 
+If the above command fails, it is most likely because hw_server is not running on target F1 instance. Please follow see this [FAQ](#hw_serverRunOnF1Instance) on how to start hw_server
 
 <img src="./images/connect_hw_server.jpg" width="600">  
 
@@ -153,7 +154,7 @@ To connect the debug Xilinx Hardware Manager to Virtual JTAG XVC server on the t
 
 **NOTES:**
 
--  If the above command fails, its most likely that either the virtual jtag server is not running, the IP/Port are wrong, or a firewall/security-group rule is blocking the connection. See the [FAQ](#faq) section in the end of this document.
+-  If the above command fails, its most likely that either the virtual jtag server or hw_server is not running, the IP/Port are wrong, or a firewall/security-group rule is blocking the connection. See the [FAQ](#faq) section in the end of this document.
 
 
 Upon successful connection, Vivado's Hardware panel will be populated with a debug bridge instance. 
@@ -228,7 +229,6 @@ The following list describes the steps to successfully setup debug in a CL:
 
 
 # Frequently Asked Questions 
-
 
 
 **Q: Do I need to run Vivado or Hardware Manager on the target EC2 instance to debug?**  
@@ -238,6 +238,11 @@ No, you may run Vivado on a "remote" host as long as your instance/VPC has the r
 
 **Q: How do I configure Linux firewalls and EC2 network security groups to enable remote debug?**
 
+If your OS has the `firewalld` service running, you can disable it for the time being for setting up remote debug by calling: 
+```sudo systemctl stop firewalld```
+
+You will also have to allow incoming and outgoing traffic to TCP ports 3121 and 10201. 
+To open up incoming and outgoing traffic on those ports for your instance, please refer to the [EC2 Security Group documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-rules-reference.html#sg-rules-other-instances)
 
 **Q: Can I have a secure connection (i.e. SSL/TLS) to the target FPGA-enable EC2 Instance running Virtual JTAG service?**
 
@@ -249,20 +254,35 @@ You may use the ssh "port forwarding" option (-L) to forward connections from th
 No, you need the Vivado Lab Edition which does not require a license.
 
 
-
 **Q: How do I stop the Virtual JTAG service on the target instance?**
 
-  
+After starting the Virtual JTAG service, you can stop it by calling `Ctrl + C` from your keyboard.  
 
 **Q: Can I debug multiple FPGAs on same target EC2 instance concurrently?**
 
 Yes, you must start the the  `$ fpga-start-virtual-jtag` with a different Slot/Port for each FPGA.  You can launch multiple Vivado sessions, and have each session connect to the corresponding TCP port associated with the FPGA.
 
-
+<a name="hw_serverRunOnF1Instance"></a>
 **Q: What are some of the best practices I should be aware when working with Virtual JTAG?**
 
 If you are running Vivado on a remote machine trying to connect to Virtual JTAG - we recommend running the hw_server on the F1 instance - to ensure optimal performance between Vivado and the Virtual JTAG server.
-
+On your target F1 Instance:
+```
+[$] sudo su 
+[$]# hw_server &
+****** Xilinx hw_server v2019.2
+  **** Build date : Oct 24 2019 at 19:23:45
+    ** Copyright 1986-2019 Xilinx, Inc. All Rights Reserved.
+ 
+INFO: hw_server application started
+INFO: Use Ctrl-C to exit hw_server application
+ 
+INFO: To connect to this hw_server instance use url: TCP:ip-xxx-xx-xx-xxx.ec2.internal:3121
+ 
+[$]# fpga-start-virtual-jtag -P 10201 -S 0
+Starting Virtual JTAG XVC Server for FPGA slot id 0, listening to TCP port 10201.
+Press CTRL-C to stop the service.
+```
 
 **Q: Can other instances running on the same F1 server access the Virtual JTAG of my instance?**
 

hdk/hdk_version.txt

@@ -1 +1 @@
-HDK_VERSION=1.4.14
+HDK_VERSION=1.4.15