Merge pull request #455 from aws/RC_v1_4_8

Release V1.4.8

Author: deeppat

.gitmodules

@@ -5,4 +5,8 @@
 [submodule "SDAccel/examples/xilinx_2018.2"]
 	path = SDAccel/examples/xilinx_2018.2
 	url = https://github.com/Xilinx/SDAccel_Examples.git
-	branch = master
+	branch = 2018.2
+[submodule "SDAccel/examples/xilinx_2018.3"]
+	path = SDAccel/examples/xilinx_2018.3
+	url = https://github.com/Xilinx/SDAccel_Examples.git
+	branch = master	

ERRATA.md

@@ -7,9 +7,12 @@
 ## HDK
 * Multiple SDE instances per CL is not supported in this release.  Support planned for future release.
 * DRAM Data retention is not supported for CL designs with less than 4 DDRs enabled
+* Combinatorial loops in CL designs are not supported.
+* Shell Model (sh_bfm) provided with testbench for design simulations, continues to drive read data on PCIM AXI rdata channel even when rready is de-asserted. Will be fixed in future release.
 
 ## SDK
 
 ## SDAccel (For additional restrictions see [SDAccel ERRATA](./SDAccel/ERRATA.md))
 * Virtual Ethernet is not supported when using SDAccel
 * DRAM Data retention is not supported for kernels that provision less than 4 DDRs
+* Combinatorial loops in CL designs are not supported.

Jenkinsfile

@@ -26,6 +26,41 @@
          *    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.8 (See [ERRATA](./ERRATA.md) for unsupported features)
+  * FPGA developer kit supports Xilinx SDx/Vivado 2018.3
+    * We recommend developers upgrade to v1.4.8 to benefit from the new features, bug fixes, and optimizations. To upgrade, use [Developer AMI v1.6.0](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) on AWS Marketplace.  The Developer Kit scripts (hdk_setup.sh or sdaccel_setup.sh) will detect the tool version and update the environment based on requirements needed for Xilinx 2018.3 tools. 
+ * Ease of Use features:
+    * Support for importing results into SDx GUI - By importing results from a script-based flow into SDx IDE, developers can leverage the tools for debug/profiling while keeping flexibility of the script-based flow
+    * Vivado HLS developers can now import designs into SDAccel environment to leverage emulation, debug and run-time software
+ * New functionality:
+    * The following HLS Video Processing cores are now license free and come installed with Vivado (VPSS, Video Mixer, Video TPG, Frame Buffer WR/RD, Gamma LUT, Demosaic, VTC) 
+    * Improved XCLBIN utilities designed for automating the management of accelerator designs
+    * Incremental compile reduces build times
+    * [Python bindings for AWS FPGA MGMT Tools](sdk/userspace/python_bindings/README.md)
+
+  * Fixed Issues
+    * [Fixes printf in main of fpga_local_cmd](https://github.com/aws/aws-fpga/pull/450)
+    * [Fixes SV dma read function to work with unprintable chars](https://github.com/aws/aws-fpga/pull/412)
+    * [Fixes Segmentation Fault in cl_sde simulation test](https://forums.aws.amazon.com/thread.jspa?threadID=298946&tstart=0)
+    * [Fixes test issues in cl_dram_dma example when using the AXI memory model for faster simulations](./hdk/cl/examples/cl_dram_dma/verif/README.md)
+ 
+  * Deprecated Features
+    * As announced in HDK 1.4.6 all EDMA driver code has been removed and deprecated from the developer kit. 
+        * AWS recommends using the [XDMA](sdk/linux_kernel_drivers/xdma/README.md) driver for your applications.
+   
+  * Package versions used for validation
+  
+   | Package | AMI 1.6.0 [2018.3] |AMI 1.5.0 [2018.2] | AMI 1.4.0 [2017.4] |
+   |---------|------------------------|------------------------|-----------------------|
+   | OS      | Centos 7.6 | Centos 7.5, 7.6 | Centos 7.4 |
+   | kernel  | 3.10.0-957.5.1.el7.x86_64 | 3.10.0-862.11.6.el7.x86_64, 3.10.0-957.1.3.el7.x86_64  | 3.10.0-693.21.1.el7.x86_64 |
+   | kernel-devel | 3.10.0-957.5.1.el7.x86_64 | 3.10.0-862.11.6.el7.x86_64, 3.10.0-957.1.3.el7.x86_64 | 3.10.0-693.21.1.el7.x86_64 |
+   | LIBSTDC++ | libstdc++-4.8.5-36.el7.x86_64 | libstdc++-4.8.5-36.el7.x86_64 | libstdc++-4.8.5-16.el7_4.2.x86_64 |
+   
+
+
+
+
 ## Release 1.4.7 (See [ERRATA](./ERRATA.md) for unsupported features)
 
   * Adds [Xilinx Runtime (XRT)](https://github.com/Xilinx/XRT/releases/tag/2018.2_XDF.RC5) Support for Linux kernel 3.10.0-957.1.3.el7.x86_64 & Centos 7.6
@@ -50,7 +85,7 @@
      * Please see XRT installation instructions [here](hdk/docs/SDxPatch_AR71715_and_XRT_installation_instructions.md#installing-xilinx-runtime-xrt-20182_xdfrc4)  
   * EDMA Driver is no longer supported. 
       * AWS strongly recommends moving your applications to [XDMA](sdk/linux_kernel_drivers/xdma/README.md).
-      * [EDMA Driver](sdk/linux_kernel_drivers/edma/README.md) will be fully removed from Developer kit 1.4.7+.
+      * EDMA Driver will be fully removed from Developer kit 1.4.7+.
   * Fixed Issues
     * [NULL definition include in header file](https://github.com/aws/aws-fpga/pull/414)
     * [Improved messaging for AFI builder script](https://github.com/aws/aws-fpga/pull/407)
@@ -122,7 +157,7 @@
 * Developers that choose to develop on-premises need to have Xilinx license 'EF-VIVADO-SDX-VU9P-OP' installed. For more help, please refer to the [on-premises licensing help](./hdk/docs/on_premise_licensing_help.md)
 * The following simulators are supported with this HDK:
 **Vivado XSIM RTL simulator
-** MentorGraphic's Questa RTL simulator (with a separate license from MentorGraphics)
+** Mentor Graphics' Questa RTL simulator (with a separate license from MentorGraphics)
 ** Synopsys' VCS RTL simulator (with a separate license from Synopsys)
 
 ## License Requirements
@@ -177,8 +212,8 @@ The following major features are included in this HDK release:
 * Multi-queue in each direction is now supported
 * The DMA bus toward the CL is multiplexed over sh_cl_dma_pcis AXI4 interface so the same address space can be accessed via DMA or directly via PCIe AppPF BAR4 
 * DMA usage is covered in the new [CL_DRAM_DMA example](./hdk/cl/examples/cl_dram_dma) RTL verification/simulation and Software 
-* A corresponding AWS Elastic DMA ([EDMA](./sdk/linux_kernel_drivers/edma)) driver is provided.
-* [EDMA Installation Readme](./sdk/linux_kernel_drivers/edma/edma_install.md) provides installation and usage guidelines
+* A corresponding AWS Elastic DMA (EDMA) driver is provided.
+* EDMA Installation Readme provides installation and usage guidelines
 * See [Kernel_Drivers_README](./sdk/linux_kernel_drivers/README.md) for more information on restrictions for this release
 
 
@@ -245,7 +280,7 @@ See example for more details [CL_HELLO_WORLD_VHDL](./hdk/cl/examples/cl_hello_wo
 
 ### Release 1.3.5 (See [ERRATA](./ERRATA.md) for unsupported features)
   * [Amazon FPGA Images (AFIs) Tagging](hdk/docs/describe_fpga_images.md) - To help with managing AFIs, you can optionally assign your own metadata to each AFI in the form of tags. Tags are managed using the AWS EC2 CLI commands create-tags, describe-tags and delete-tags.  Tags are custom key/value pairs that can be used to identify or group EC2 resources, including AFIs.  Tags can be used as filters in the describe-fpga-images API to search and filter the AFIs based on the tags you add.
-  * [EDMA driver fixes and improvements](sdk/linux_kernel_drivers/edma/README.md), including polled DMA descriptor completion mode which improves performance on smaller IO (<1MB).
+  * EDMA driver fixes and improvements, including polled DMA descriptor completion mode which improves performance on smaller IO (<1MB).
   * [AFI Power metrics and warnings](hdk/docs/afi_power.md) – developers can avoid power violations by monitoring metrics that provide recent FPGA power, maximum FPGA power, and average FPGA power. CL designs can use power state pins to help developers throttle CL to avoid power violation. 
   * Improved IPI 3rd party simulator support.
   * Simulation model fixes.
@@ -326,16 +361,16 @@ See example for more details [CL_HELLO_WORLD_VHDL](./hdk/cl/examples/cl_hello_wo
 #### 2.    Integrated DMA in Beta Release. AWS Shell now includes DMA capabilities on behalf of the CL
 * The DMA bus toward the CL is multiplexed over sh_cl_dma_pcis AXI4 interface so the same address space can be accessed via DMA or directly via PCIe AppPF BAR4 
 * DMA usage is covered in the new [CL_DRAM_DMA example](./hdk/cl/examples/cl_dram_dma) RTL verification/simulation and Software 
-* A corresponding AWS Elastic DMA ([EDMA](./sdk/linux_kernel_drivers/edma)) driver is provided.
-* [EDMA Installation Readme](./sdk/linux_kernel_drivers/edma/edma_install.md) provides installation and usage guidelines
+* A corresponding AWS Elastic DMA (EDMA) driver is provided.
+* EDMA Installation Readme provides installation and usage guidelines
 * The initial release supports a single queue in each direction
 * DMA support is in Beta stage with a known issue for DMA READ transactions that cross 4K address boundaries.  See [Kernel_Drivers_README](./sdk/linux_kernel_drivers/README.md) for more information on restrictions for this release
 
 
 #### 3.    CL  User-defined interrupt events.  The CL can now request sending MSI-X to the instance CPU
 * * Usage covered in new [CL_DRAM_DMA example](./hdk/cl/examples/cl_dram_dma)
-* A corresponding AWS EDMA driver is provided under [/sdk/linux_kernel_drivers/edma](./sdk/linux_kernel_drivers/edma)
-* [EDMA Installation](./sdk/linux_kernel_drivers/edma/edma_install.md) provides installation and usage guidlines
+* A corresponding AWS EDMA driver is provided under `/sdk/linux_kernel_drivers/edma`
+* EDMA Installation Readme provides installation and usage guidelines
 * The initial release supports a single user-defined interrupt 
 
 #### 4.    Added a Mandatory Manifest.txt file submitted with each DCP via create-fpga-image API

RELEASE_NOTES.md

@@ -1,5 +1,5 @@
 # Known Restrictions
 * OpenCL support is limited to OpenCL 1.0 core specifications.
-   * For complete list of the supported OpenCL APIs, please refer to [Appendix B in Xilinx' UG1023](https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_1/ug1023-sdaccel-user-guide.pdf)
+   * For a complete list of the supported OpenCL APIs, please refer to [Appendix B in Xilinx' UG1023 2018.3](https://www.xilinx.com/support/documentation/sw_manuals/xilinx2018_3/ug1023-sdaccel-user-guide.pdf)
 * On device - only Global memory (i.e. external DRAM) is supported.
 * Shared Virtual Memory (SVM) is not supported.

SDAccel/ERRATA.md

@@ -6,13 +6,10 @@ A:  First double check that your AFI has been generated successfully by reviewin
 
 ## Q: During AFI generation (create_sdaccel_afi.sh), how do I resolve this error: "An error occurred (AuthFailure) when calling the CreateFpgaImage operation: AWS was not able to validate the provided access credentials"?
 
-A: The script has output an error, therefore, for AFI generation to complete you will need to resolve this error.
-"An error occurred (AuthFailure) when calling the CreateFpgaImage operation: AWS was not able to validate the provided access credentials"
-
-This error message means your AWS credentials were not setup properly or your IAM does not have access to the API (CreateFpgaImage). Here is some additional info on how to setup IAM privileges.
+A: For an AFI generation to complete all errors must be resolved.  This error ("An error occurred (AuthFailure) when calling the CreateFpgaImage operation: AWS was not able to validate the provided access credentials") message means your AWS credentials were not setup properly or your IAM does not have access to the API (CreateFpgaImage). Here is some additional info on how to setup IAM privileges.
 http://docs.aws.amazon.com/AWSEC2/latest/APIReference/ec2-api-permissions.html
 
-You may want to test you IAM policy using DescribeFpgaImage API:
+AWS Accounts require IAM permisions to access API functions.  To test your IAM permissions use DescribeFpgaImage API:
 https://github.com/aws/aws-fpga/blob/master/hdk/docs/describe_fpga_images.md
 
 ## Q: During AFI generation (create_sdaccel_afi.sh), my AFI failed to generate and I see this error message in the log:  "Provided clocks configuration is illegal. See AWS FPGA HDK documentation for supported clocks configuration. Frequency 0 is lower than minimal supported frequency of 80", how do I debug this message?  
@@ -26,12 +23,12 @@ AWS uses a modified version of the xclbin called awsxclbin.  The awsxclbin conta
 
 ## Q: What can we investigate when xocc fails with a path not meeting timing? 
 A: An example is WARNING: [XOCC 60-732] Link warning: One or more timing paths failed timing targeting <ORIGINAL_FREQ> MHz for <CLOCK_NAME>. The frequency is being automatically changed to <NEW_SCALED_FREQ> MHz to enable proper functionality.
-1. Generally speaking, lowering the clock will make the design functional in terms of operations (since there will not be timing failures) but the design might not operate at the performance needed due this clock frequency change. We can review what can be done.
-1. If CLOCK_NAME is `kernel clock 'DATA_CLK'` then this is the clock that drives the kernels. Try reduce kernel clock frequency see --kernel_frequency option to xocc in [latest SDAccel Environment User Guide]
+1. Generally speaking, lowering the clock will make the design functionally operational in terms of operations (since there will not be timing failures) but the design might not operate at the performance needed due this clock frequency change. We can review what can be done.
+1. If CLOCK_NAME is `kernel clock 'DATA_CLK'` then this is the clock that drives the kernels. Try reducing the kernel clock frequency see --kernel_frequency option to xocc in [latest SDAccel Environment User Guide]
 1. If CLOCK_NAME is `system clock 'clk_main_a0'` then this is the clock clk_main_a0 which drives the AXI interconnect between the AWS Shell and the rest of the platform (SDAccel peripherals and user kernels). Using --kernel_frequency as above does not have any direct effect but might have side effect in changing the topology/placement of the design and improve this issue.
 1. If OCL/C/C++ kernels were also used, investigate VHLS reports / correlate with kernel source code to see if there are functions with large number of statements in basic block, examples: might have unrolled loops with large loop-count, might have a 100++ latency; the VHLS runs and log files are located in the directory named `_xocc*compile*`
 1. Try `xocc -O3` to run bitstream creation process with higher efforts.
-1. Open vivado implementation project ```vivado `find -name ipiimpl.xpr` ``` to analyze the design; needs Vivado knowledge; see [UltraFast Design Methodology Guide for the Vivado][latest UG949]
+1. Open a Vivado implementation project using ```vivado `find -name ipiimpl.xpr` ``` to analyze the design; needs Vivado knowledge; see [UltraFast Design Methodology Guide for the Vivado][latest UG949]
 
 ## Q: xocc issues message WARNING: [XOCC 204-69] Unable to schedule ...due to limited memory ports.
 A: This may lower the performance of the implementation.   
@@ -41,24 +38,23 @@ Details on this are provided in [Debug HLS Performance: Limited memory ports]
 A: Examine utilization reports.  If OCL/C/C++ kernels were also used, look into the source code for excessive unroll happening.
 
 ## Q: How do I open the design as a Vivado project (.xpr)?
-A: There are 2 vivado project files: 
+A: There are 2 Vivado project files: 
 1. CL Design - from command line: ```vivado `find -name ipiprj.xpr\` ``` to see the connectivity of the created design
 1. Implementation project - from command line: ```vivado `find -name ipiimpl.xpr\` ``` to analyze the design in the place and routing design phases.  For an additional Vivado Design reference, see [UltraFast Design Methodology Guide for the Vivado][latest UG949]
 
 ## Q: What should I do if FPGA instance execution gets the wrong results or gets stuck?
 A: 
-1. Verify hw_emu works as expected.  Using less data in hw_emu
-1. Add assert where run fails and check same conditions for hw_emu
+1. Verify hw_emu works as expected
 1. See "Chapter 4 - Debugging Applications in the SDAccel Environment" in [latest SDAccel Environment User Guide]
 
 ## Q: Bitstream creation fails to create design less that 60 MHz?
-A: SDAccel flow does not allow clocks running less that 60 MHz kernel clock, therefore, you will need to debug further using [HLS Debug suggestions](./docs/SDAccel_HLS_Debug.md)
+A: SDAccel flow does not allow clocks running less than 60 MHz kernel clock, therefore, you will need to debug further using [HLS Debug suggestions](./docs/SDAccel_HLS_Debug.md)
 
 ## Q: Using the .dcp file generated from xocc results in an error?
-A: Directly using the .dcp file without conversion to .xclbin file will result in an error - Error: ... invalid binary.  See [Instructions on how to create AFI and subsequent execution process](./README.md#createafi)
+A: Directly using the .dcp file without conversion to .awsxclbin file will result in an error - Error: ... invalid binary.  See [Instructions on how to create AFI and subsequent execution process](./README.md#createafi)
 
 ## Q: Debugging using gdb in SDX gui is not working? 
-A: Please make sure you executed the following commands before launching SDX gui.
+A: Please make sure you executed the following commands before launching the SDx gui.
   1.	mv /usr/local/Modules/init init.bak
   2.	unset –f switchml
   3.	unset –f _moduleraw