v1.3.5 Release (#385)

Author: kristopk

ERRATA.md

@@ -21,7 +21,7 @@
 * FPGA to FPGA over the 400Gbps Ring for F1.16xl
 * Aurora and Reliable Aurora modules for the FPGA-to-FPGA 
 * Preserving the DRAM content between different AFI loads (by the same running instance)
-* Cadence RTL simulations tools
+* Cadence Xcelium simulations tools
 * PCIM and DMA-PCIS AXI-4 interfaces do not support AxSIZE other than 3'b110 (64B)
 
 ## Known Bugs/Issues

FAQs.md

@@ -110,6 +110,7 @@ The developer can create multiple AFIs at no extra cost, up to a defined limited
 AWS FPGA generation and EC2 F1 instances are supported in us-east-1 (N. Virginia), us-west-2 (Oregon) and eu-west-1 (Ireland).
 
 
+
 **Q: What is the process for creating an AFI?**
 
 The AFI process starts by creating Custom Logic (CL) code that conforms to the [Shell Specification](./hdk/docs/AWS_Shell_Interface_Specification.md). Then, the CL must be compiled using the HDK scripts which leverages Vivado tools to create a Design Checkpoint (DCP). That DCP is submitted to AWS for generating an AFI using the `aws ec2 create-fpga-image` API.
@@ -137,6 +138,20 @@ Yes, use [delete-fpga-image](./hdk/docs/delete_fpga_image.md) to delete an AFI i
 
 Use [delete-fpga-image](./hdk/docs/delete_fpga_image.md) carefully. Once all AFIs of the same global AFI ID are deleted, the AFIs cannot be recovered from deletion.  Review [IAM policy best practices](http://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) to restrict access to this API.
 
+**Q: Can I share an AFI with other AWS accounts?**
+
+Yes, sharing allows accounts other than the owner account to load and use an AFI.  Use [modify-fpga-image-attribute](./hdk/docs/fpga_image_attributes.md) API to update `loadPermission` attribute to grant/remove AFI load permission.  AWS AFIs support two load permission types:
+* `UserId`: share AFI with specific AWS accounts using account IDs.
+* `UserGroups`: only supports `all` group to make an AFI public or private.
+
+Use [reset-fpga-image-attribute](./hdk/docs/fpga_image_attributes.md) API to revoke all load permissions.
+
+**Q: Can I delete an AFI?**
+
+Yes, use [delete-fpga-image](./hdk/docs/delete_fpga_image.md) to delete an AFI in a specific region.  Deleting an AFI in one region does not affect AFIs in other regions.
+
+Use [delete-fpga-image](./hdk/docs/delete_fpga_image.md) carefully. Once all AFIs of the same global AFI ID are deleted, the AFIs cannot be recovered from deletion.  Review [IAM policy best practices](http://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) to resrict access to this API.
+
 **Q: Can I bring my own bitstream for loading on an F1 FPGA?**
 
 No. There is no mechanism for loading a bitstream directly onto the FPGAs of an F1 instance. All Custom Logic is loaded onto the FPGA by calling `$ fpga-local-load-image` tool at [AWS FPGA SDK](./sdk). 
@@ -170,7 +185,7 @@ No. AWS supports a cloud-only development model and provides the necessary eleme
 
 **Q: Do I need to design for a specific power envelope?**
 
-Yes, the design scripts provided in the HDK include checks for power consumption that exceeds the allocated power for the Custom Logic (CL) region. Developers do not need to include design considerations for DRAM, Shell, or Thermal. AWS includes the design considerations for those as part of providing the power envelop for the CL region.
+Yes, the Xilinx UltraScale+ FPGA devices used on the F1 instances have a maximum power limit that must be maintained.  If a loaded AFI consumes maximum power, the F1 instance will automatically gate the input clocks provided to the AFI in order to prevent errors within the FPGA. Developers are provided warnings when power (Vccint) is greater than 85 watts.  Above that level, the CL is in danger of being clock gated.  [Additional details on AFI power](hdk/docs/afi_power.md)
 
 
 **Q: What IP blocks are provided in the HDK?**

Jenkinsfile

@@ -26,6 +26,14 @@
          *    1 DDR controller implemented in the SH (always available)
          *    3 DDR controllers implemented in the CL (configurable number of implemented controllers allowed)
 
+## 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)
+   *    [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
+   *    SDAccel improvements - Removal of settings64 script from SDAccel setup and switching between DSAs	
+
 ## Release 1.3.4 (See [ERRATA](./ERRATA.md) for unsupported features)
    *    EDMA/XDMA Driver improvements
    *    Additional SDAccel Platforms

RELEASE_NOTES.md

@@ -7,7 +7,7 @@ There are three simple steps for accelerating your application on an AWS F1 inst
 
 This quick start guide will use a simple "Hello World" SDAccel example to get you started.  
 
-It is highly recommended you read the documentation and utilize software and hardware emulation prior to running on F1.  The F1 HW compile time is 4-5hrs, therefore, software and hardware emulation should be used during development.
+It is highly recommended you read the documentation and utilize software and hardware emulation prior to running on F1.  The F1 HW compile time is ~4hrs (4DDR) and ~1hr (1DDR), therefore, software and hardware emulation should be used during development.
 
 
 # Table of Content
@@ -64,17 +64,19 @@ It is highly recommended you read the documentation and utilize software and har
        $ cd $AWS_FPGA_REPO_DIR                                         
        $ source sdaccel_setup.sh
    ```
+    * Select a platform:
+      * AWS_PLATFORM_4DDR - Default AWS F1 platform with 4 DDRs and profiling support. Optimized for multi DDR use cases. This platform should be used for all production applications which require more than 1 DDR bank.
+      * AWS_PLATFORM_4DDR_DEBUG - This platform is a debug variant of the 4DDR platform and should be used for hardware debugging of kernels. This version consists of an additional debug feature which allows advanced users to insert ILA’s in the kernels for debugging purposes. All other features are identical to the AWS_PLATFORM_4DDR platform.  
+      * AWS_PLATFORM_1DDR - This platform consist of 1 DDR that is located in the shell region. This allow maximum space for kernels. This also allows much faster compile times for all the use cases which require only 1 DDR bank.  This platform does not support APM and hence no profiling data can be obtained.
 
+   ```
+       $ export AWS_PLATFORM=$AWS_PLATFORM_1DDR 
+   ```
 <a name="createapp"></a>
 # 1. Build the host application, Xilinx FPGA binary and verify you are ready for FPGA acceleration
 
 This section will walk you through creating, emulating and compiling your host application and FPGA Binary
 
-Start by sourcing the setup for the Xilinx SDAccel Emulation and Build Environment
-```
-    $ source $XILINX_SDX/settings64.sh 
-```
-
 <a name="emu"></a>
 # Emulate your Code
 

SDAccel/README.md

@@ -62,23 +62,20 @@ mv tmp twid_radix4_8.cl
 * To run in software emulation mode, use the following commands.
  ```
 make clean
-source $XILINX_SDX/settings64.sh
 make TARGETS=sw_emu DEVICES=$AWS_PLATFORM all
 ./main -hw=sw_emu
 ```
 
 * To run in hardware emulation mode, use the following commands.
  ```
 make clean
-source $XILINX_SDX/settings64.sh
 make TARGETS=hw_emu DEVICES=$AWS_PLATFORM all
 ./main -hw=hw_emu
 ```
 
 * To run on an F1 instance, use the following commands.
  ```
 make clean
-source $XILINX_SDX/settings64.sh
 make TARGETS=hw DEVICES=$AWS_PLATFORM all
 ./main
 ```

SDAccel/docs/README_third_party.md

@@ -23,10 +23,11 @@
 
 def pytest_addoption(parser):
     parser.addoption("--examplePath", action="store", required=False, type=str,
-        help="Path to the Xilinx Example to test")
+        help="Path to the Xilinx Example to test", default="SDAccel/examples/xilinx/getting_started/host/helloworld_ocl")
 
 def pytest_generate_tests(metafunc):
-    if metafunc.module.__name__ == 'test_run_sdaccel_examples' :
+
+    if metafunc.cls.ADD_EXAMPLEPATH:
         print("Configuring parameters of {}::{}".format(metafunc.module.__name__, metafunc.function.__name__))
         print("examplePath = " + metafunc.config.getoption('examplePath'))
         metafunc.parametrize("examplePath", [metafunc.config.getoption('examplePath')])

SDAccel/tests/conftest.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python2.7
+
+# 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.
+'''
+Pytest module:
+
+Call using ```pytest test_build_sdaccel_examples.py```
+
+See TESTING.md for details.
+'''
+
+from __future__ import print_function
+import os
+from os.path import dirname, realpath, basename
+import json
+try:
+    import aws_fpga_utils
+    import aws_fpga_test_utils
+    from aws_fpga_test_utils.AwsFpgaTestBase import AwsFpgaTestBase
+except ImportError as e:
+    traceback.print_tb(sys.exc_info()[2])
+    print("error: {}\nMake sure to source shared/bin/setup_test_env.sh".format(sys.exc_info()[1]))
+    sys.exit(1)
+
+logger = aws_fpga_utils.get_logger(__name__)
+
+class TestBuildSDAccelExample(AwsFpgaTestBase):
+    '''
+    Pytest test class.
+
+    NOTE: Cannot have an __init__ method.
+
+    '''
+    ADD_EXAMPLEPATH = True
+
+    @classmethod
+    def setup_class(cls):
+        '''
+        Do any setup required for tests.
+        '''
+
+        AwsFpgaTestBase.setup_class(cls, __file__)
+
+        AwsFpgaTestBase.assert_sdk_setup()
+        AwsFpgaTestBase.assert_sdaccel_setup()
+
+        return
+
+    def test_sw_emu(self, examplePath):
+        target = "sw_emu"
+        self.base_test(examplePath=examplePath, target=target, check=True)
+
+    def test_hw_emu(self, examplePath):
+        target = "hw_emu"
+        self.base_test(examplePath=examplePath, target=target, check=True)
+
+    def test_hw_build(self, examplePath):
+        target = "hw"
+        self.base_test(examplePath=examplePath, target=target, check=False)
+
+    def check_build(self, examplePath, target):
+
+        xclbin_path = self.get_sdaccel_xclbin_dir(examplePath)
+
+        logger.info("Checking if SDAccel Example xclbin path={} exists".format(xclbin_path))
+        assert os.path.exists(xclbin_path), "SDAccel Example xclbinpath={} does not exist".format(xclbin_path)
+
+        logger.info("Checking that a non zero size xclbin file exists in {}".format(xclbin_path))
+        xclbin = self.assert_non_zero_file(os.path.join(xclbin_path, "*.{}.*.xclbin".format(target)))
+        logger.info("xclbin: {}".format(xclbin))
+
+        return xclbin
+
+    def base_test(self, examplePath, target, clean=True, check=True):
+
+        full_example_path = self.get_sdaccel_example_fullpath(examplePath=examplePath)
+        logger.info("SDAccel Example path={}".format(full_example_path))
+
+        assert os.path.exists(full_example_path), "SDAccel Example path={} does not exist".format(full_example_path)
+
+        os.chdir(full_example_path)
+
+        if clean:
+            (rc, stdout_lines, stderr_lines) = self.run_cmd("make clean")
+            assert rc == 0, "SDAccel build failed while cleaning with rc={}".format(rc)
+
+        check_string = ""
+        if check:
+            check_string = "check"
+
+        (rc, stdout_lines, stderr_lines) = self.run_cmd("make {0} TARGETS={1} DEVICES={2} all".format(check_string, target, os.environ['AWS_PLATFORM']))
+        assert rc == 0, "SDAccel build failed with rc={}".format(rc)
+
+        # Check for non zero xclbin
+        xclbin = self.check_build(examplePath=examplePath, target=target)
+
+        xclbin_key = os.path.join(self.get_sdaccel_example_s3_xclbin_tag(examplePath=examplePath, target=target), basename(xclbin))
+
+        logger.info("Uploading xclbin to {}".format(os.path.join(self.s3_bucket, xclbin_key)))
+        self.s3_client().upload_file(xclbin, self.s3_bucket, xclbin_key)
+
+        return