Doc updates only: Fixes to links and additional SDAccel updates based…

… on customer feedback and AWS forum posts
wjblanke · Oct 5, 2017 · 934000f · 934000f
1 parent e107da6
commit 934000f
Show file tree

Hide file tree

Showing 9 changed files with 157 additions and 74 deletions.
diff --git a/FAQs.md b/FAQs.md
@@ -112,7 +112,7 @@ AWS FPGA generation and EC2 F1 instances are supported in us-east-1 (N. Virginia
 
 **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.
+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.
 
 Use the AWS CLI `describe-fpga-images` API to get information about the created AFIs using the AFI ID provided by `create-fpga-image`, or to list available AFIs for your account. See [describe-fpga-images](./hdk/docs/describe_fpga_images.md) document for details on how to use this API.
 
@@ -153,7 +153,7 @@ If a developer uses local tools and license, please check the [supported version
 
 **Q: Is there a “best practice” system template?**
 
-AWS prefers not to limit developers to a specific template in terms of how we advise to use AWS FPGAs. A good overview of these interfaces can be found [here](https://github.com/aws/aws-fpga/blob/master/hdk/docs/Programmer_View.md)
+AWS prefers not to limit developers to a specific template in terms of how we advise to use AWS FPGAs. A good overview of these interfaces can be found [here](./hdk/docs/Programmer_View.md)
 
 
 **Q: Do I need to get a Xilinx license to generate an AFI?**
@@ -374,7 +374,7 @@ Details on the Shell Interface to the FPGA Link IP blocks are provided in the [S
 
 **Q: What clock speed does the FPGA utilize?**
 
-The FPGA Shell provides a selectable frequency clocks (up to 8 clocks) from the Shell to the Custom Logic (CL) region, please refer to the [Shell Interface Specification](./hdk/docs/AWS_Shell_interface_Specification.md) and the [available clock recipe](./hdk/docs/clock_recipes.csv) for the available clocks and frequency options.
+The FPGA Shell provides a selectable frequency clocks (up to 8 clocks) from the Shell to the Custom Logic (CL) region, please refer to the [Shell Interface Specification](./hdk/docs/AWS_Shell_Interface_Specification.md) and the [available clock recipe](./hdk/docs/clock_recipes.csv) for the available clocks and frequency options.
 
 *Note: All the AXI interfaces between Shell and CL are synchronous to `clk_main_a0`, which has a default of 125Mhz using `A0` clock recipe.
 

diff --git a/SDAccel/FAQ.md b/SDAccel/FAQ.md
@@ -1,6 +1,28 @@
 # Frequently Asked Questions (FAQ)
 
-This section lists issues/perceived issue and their associated investigations or solutions.
+## Q: When I run my application on F1, I see these errors:  ERROR: Failed to load xclbin ERROR: No program executable for device ERROR: buffer (2) is not resident in device (0)", how to debug these errors?
+
+A:  First double check that your AFI has been generated successfully by reviewing the SDAccel README.  Second, check that you are running your application on F1 using sudo.  Lastly, check that your AWS CLI (configure) was configured using output format as json.   
+
+## 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.
+http://docs.aws.amazon.com/AWSEC2/latest/APIReference/ec2-api-permissions.html
+
+You may want to test you IAM policy using 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?  
+
+A:  Please confirm that you successfully compiled your kernel for HW.  For the quick start examples, you will need to have completed the quick start and successfully passed this command:  make  TARGETS=hw DEVICES=$AWS_PLATFORM all
+
+## Q: What is a xclbin or binary container on SDAccel?
+
+A:  The [xclbin](https://www.xilinx.com/html_docs/xilinx2017_2/sdaccel_doc/topics/design-flows/concept-create-compute-unit-binary.html) file or the "Binary Container" is a binary library of kernel compute units that will be loaded together into an OpenCL context for a specific device. 
+AWS uses a modified version of the xclbin called awsxclbin.  The awsxclbin contains the xclbin metadata and AFI ID.  
 
 ## 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.
@@ -29,28 +51,11 @@ A:
 1. Add assert where run fails and check same conditions for hw_emu
 1. See "Chapter 8 - Debugging Applications in the SDAccel Environment" in [latest SDAccel Environment User Guide]
 
-## Q: Host code failed to link?
-A:
-1. Is the code linking to *.so libs and are they setup correctly on the compiler command line argument
-- Note, there has been issues reported where -ldl or -lxilinxopencl needed to be put as the last argument of the comman line for the compiler; try linking on the command line and see if moving the -l options corrects the issue.
-1. Check if LD_LIBRARY_PATH is setup correctly
-
-## Q: sw_emu passes but hw_emu fails
-A: 
-1. arrow down failure: what mismatches, only LSB bits different?
-1. Differences due to floating point?
-1. Run valgrind on executable to assert no seg faults or out of bounds accesses
-1. Have a reduced testcase data size if hw_emu takes too long
-1. Have sdaccel.ini configured with [Emulation] section using launch_waveform=gui or batch to generate waveform for analysis; see "Application Timeline" 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)
 
-## Q: Using the .xcp file generated from xocc results in an error
-A:
-1. Raw xclbin (.xcp file) from xocc is not usable
-1. Directly using the .xcp file without conversion to .xclbin file will result in an error - Error: ... invalid binary
-1. See [Instructions on how to create AFI and subsequent execution process](../README.md#create-an-amazon-fpga-image-afi-for-your-kernel)
+## Q: Using the .xcp file generated from xocc results in an error?
+A: Directly using the .xcp 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#create-an-amazon-fpga-image-afi-for-your-kernel)
 
 
 # Additional Resources
@@ -60,32 +65,27 @@ The [AWS SDAccel README].
 Xilinx web portal for [Xilinx SDAccel documentation] and for [Xilinx SDAccel GitHub repository]
 
 Links pointing to **latest** version of the user guides
-[UG1023: SDAccel Environment User Guide][latest SDAccel Environment User Guide]
-[UG1021: SDAccel Environment Tutorial: Getting Started Guide (including emulation/build/running on H/W flow)][latest UG1021]
-[UG1207: SDAccel Environment Optimization Guide][latest SDAccel Environment Optimization Guide]
-[UG949: UltraFast Design Methodology Guide for the Vivado Design Suite][latest UG949]
+   * [UG1023: SDAccel Environment User Guide][latest SDAccel Environment User Guide]
+   * [UG1021: SDAccel Environment Tutorial: Getting Started Guide (including emulation/build/running on H/W flow)][latest UG1021]
+   * [UG1207: SDAccel Environment Optimization Guide][latest SDAccel Environment Optimization Guide]
+   * [UG949: UltraFast Design Methodology Guide for the Vivado Design Suite][latest UG949]
 
 Links pointing to **2017.1** version of the user guides
-[UG1023: SDAccel Environment User Guide][UG1023 2017.1]
-[UG1021: SDAccel Environment Tutorial: Getting Started Guide (including emulation/build/running on H/W flow)][UG1021 2017.1]
-[UG1207: SDAccel Environment Optimization Guide][UG1207 2017.1]
-[UG1238: SDx Development Environment Release Notes, Installation, and Licensing Guide][UG1238 2017.1]
-
-[SDAccel_landing_page]: https://www.xilinx.com/products/design-tools/software-zone/sdaccel.html
-[VHLS_landing_page]: https://www.xilinx.com/products/design-tools/vivado/integration/esl-design.html
-[Vivado_landing_page]: https://www.xilinx.com/products/design-tools/vivado.html
-
-[latest SDAccel Environment User Guide]: https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug1023-sdaccel-user-guide.pdf
-[latest UG1021]: https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug1021-sdaccel-intro-tutorial.pdf
-[latest SDAccel Environment Optimization Guide]: https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug1207-sdaccel-optimization-guide.pdf
-[latest UG949]: https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug949-vivado-design-methodology.pdf
-
-[UG1023 2017.1]: https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_1/ug1023-sdaccel-user-guide.pdf
-[UG1021 2017.1]: https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_1/ug1021-sdaccel-intro-tutorial.pdf
-[UG1207 2017.1]: https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_1/ug1207-sdaccel-optimization-guide.pdf
-[UG1238 2017.1]:http://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_1/ug1238-sdx-rnil.pdf
-[Xilinx SDAccel documentation]: https://www.xilinx.com/products/design-tools/software-zone/sdaccel.html#documentation
-[Xilinx SDAccel GitHub repository]: https://github.com/Xilinx/SDAccel_Examples
-
-[AWS SDAccel Readme]: ../README.md
-[Debug HLS Performance: Limited memory ports]: ./docs/SDAccel_HLS_Debug.md
+   * [UG1023: SDAccel Environment User Guide][UG1023 2017.1]
+   * [UG1021: SDAccel Environment Tutorial: Getting Started Guide (including emulation/build/running on H/W flow)][UG1021 2017.1]
+   * [UG1207: SDAccel Environment Optimization Guide][UG1207 2017.1]
+   * [UG1238: SDx Development Environment Release Notes, Installation, and Licensing Guide][UG1238 2017.1]
+   * [SDAccel_landing_page](https://www.xilinx.com/products/design-tools/software-zone/sdaccel.html)
+   * [Vivado HLS landing page](https://www.xilinx.com/products/design-tools/vivado/integration/esl-design.html
+   * [Vivado landing page](https://www.xilinx.com/products/design-tools/vivado.html)
+   * [SDAccel Environment User Guide](https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug1023-sdaccel-user-guide.pdf)
+   * [SDAccel Intro Tutorial](https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug1021-sdaccel-intro-tutorial.pdf)
+   * [SDAccel Environment Optimization Guide](https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug1207-sdaccel-optimization-guide.pdf)
+   * [Vivado Design Methodology](https://www.xilinx.com/cgi-bin/docs/rdoc?v=latest;d=ug949-vivado-design-methodology.pdf)
+   * [2017.1 SDAccel User Guide](https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_1/ug1023-sdaccel-user-guide.pdf)
+   * [2017.1 SDAccel Intro Tutorial](https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_1/ug1021-sdaccel-intro-tutorial.pdf)
+   * [2017.1 SDAccel Environment Optimization Guide](https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_1/ug1207-sdaccel-optimization-guide.pdf)
+   * [Xilinx SDAccel documentation](https://www.xilinx.com/products/design-tools/software-zone/sdaccel.html#documentation)
+   * [Xilinx SDAccel GitHub repository](https://github.com/Xilinx/SDAccel_Examples)
+   * [AWS SDAccel Readme](README.md)
+   * [Debug HLS Performance: Limited memory ports](./docs/SDAccel_HLS_Debug.md)
diff --git a/SDAccel/README.md b/SDAccel/README.md
@@ -5,7 +5,9 @@ There are three simple steps for accelerating your application on an AWS F1 inst
 2. Create an AFI 
 3. Run the FPGA accelerated application on AWS FPGA instances
 
-This quick start guide will use a simple "Hello World" SDAccel example to get you started
+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.
 
 
 # Table of Content
@@ -39,15 +41,14 @@ This quick start guide will use a simple "Hello World" SDAccel example to get yo
 <a name="iss"></a>
 ## AWS Account, F1/EC2 Instances, On-Premises, AWS IAM Permissions, AWS CLI and S3 Setup (One-time Setup)
 * [Setup an AWS Account](https://aws.amazon.com/free/)
-* Launch an [FPGA Developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) which comes pre-installed with SDAccel and required licenses on an F1 instance
-  * You may use this F1 instance to [Build your Host Application and Xilinx FPGA Binary](#createapp), however, it may be more cost efficient to either: 
-     * Launch a second [FPGA Developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) on a lower cost EC2 instance, with a minimum of 30GiB RAM), **OR** 
-     * Follow the [On-Premises Instructions](../../hdk/docs/on_premise_licensing_help.md) to install and obtain a license from Xilinx.
-* Setup AWS IAM permissions for creating FPGA Images (CreateFpgaImage and DescribeFpgaImages). [EC2 API Permissions are described in more detail](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/ec2-api-permissions.html) <!-- #TBF Is there a better guide (syntax/links to for explicitly making this update? -->
+* Launch an instance using the [FPGA Developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) which comes pre-installed with SDAccel and required licenses.
+  * You may use this F1 instance to [build your host application and Xilinx FPGA binary](#createapp), however, it may be more cost efficient to either: 
+     * Launch the [FPGA Developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) on a lower cost EC2 instance, with a minimum of 30GiB RAM), **OR** 
+     * Follow the [On-Premises Instructions](../../hdk/docs/on_premise_licensing_help.md) to purchase and install a license from Xilinx.
+* Setup AWS IAM permissions for creating FPGA Images (CreateFpgaImage and DescribeFpgaImages). [EC2 API Permissions are described in more detail](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/ec2-api-permissions.html).  It is highly recommended that you validate your AWS IAM permissions prior to proceeding with this quick start.  By calling the [DescribeFpgaImages API](../hdk/docs/describe_fpga_images.md) you can check that your IAM permissions are correct.
 * [Setup AWS CLI and S3 Bucket](docs/Setup_AWS_CLI_and_S3_Bucket.md) to enable AFI creation.
-
-
-
+* Install optional [packages](packages.txt) required to run all examples.  If you do not install these packages, some examples may not work properly.  The setup scripts will warn you of any missing packages.
+* Additional dependancies may get flagged during the AWS SDAccel scripts as warnings or errors.
 
 <a name="gitsetenv"></a>
 ## Github and Environment Setup (Once per new instance or machine)
@@ -56,15 +57,14 @@ This quick start guide will use a simple "Hello World" SDAccel example to get yo
     * [AWS Platform](./aws_platform/xilinx_aws-vu9p-f1_4ddr-xpr-2pr_4_0) that allows Xilinx FPGA Binary files to target AWS F1 instances 
     * [AFI Creation script](./tools/create_sdaccel_afi.sh) that generates an AFI and AWS FPGA Binary from a Xilinx FPGA Binary
     * [SDAccel HAL](./userspace) source code and binary files for mapping SDAccel/OpenCL runtime libraries to AWS FPGA instance.
-  * Installing  the required libraries and drivers
+    * Installing the required libraries and drivers
 
    ```
        $ git clone https://github.com/aws/aws-fpga.git $AWS_FPGA_REPO_DIR  
        $ cd $AWS_FPGA_REPO_DIR                                         
        $ source sdaccel_setup.sh
    ```
 
-
 <a name="createapp"></a>
 # 1. Build the host application, Xilinx FPGA binary and verify you are ready for FPGA acceleration
 
@@ -148,7 +148,7 @@ The [create_sdaccel_afi.sh](./tools/create_sdaccel_afi.sh) script is provided to
 **Save the \*.awsxclbin, you will need to copy it to your F1 instance along with your executable host application.**
 
 **NOTE**: *Attempting to load your FPGA Binary immediately on an F1 instance will result in an 'Invalid AFI ID' error.
-Please wait until you confirm the AFI is created successfully.*
+Please wait until you confirm the AFI has been created successfully.*
 
 ## Tracking the status of your registered AFI  
 
@@ -163,7 +163,7 @@ The \*_afi_id.txt file generated by the create_sdaccel_afi.sh also includes the
     An example AGFI ID is **`agfi-0f0e045f919413242`**.
 
 
-Use the [describe-fpga-images](../../hdk/docs/describe_fpga_images.md) API to check the AFI state during the background AFI generation process.  
+Use the [describe-fpga-images](../hdk/docs/describe_fpga_images.md) API to check the AFI state during the background AFI generation process.  
 
 ```
     $ aws ec2 describe-fpga-images --fpga-image-ids <AFI ID>
@@ -180,7 +180,7 @@ When AFI creation completes successfully, the output should contain:
 
 If the “State” code indicates the AFI generation has "failed", the AFI creation logs can be found in the bucket location (```s3://<bucket-name>/<logs-folder-name>```) provided to create_sdaccel_afi.sh above. These will detail the errors encountered during the AFI creation process.
 
-For help with AFI creation issues, see [create-fpga-image error codes](../../hdk/docs/create_fpga_image_error_codes.md)
+For help with AFI creation issues, see [create-fpga-image error codes](../hdk/docs/create_fpga_image_error_codes.md)
 
 
 
@@ -189,7 +189,7 @@ For help with AFI creation issues, see [create-fpga-image error codes](../../hdk
 # 3. Run the FPGA accelerated application on F1
 
 Here are the steps:
-* Start an F1 instance using [FPGA Developer AMI on AWS Marketplace](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ). Currently, the developer AMI is the only supported AMI for running SDAccel applications on F1.
+* Start an F1 instance using [FPGA Developer AMI on AWS Marketplace](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ), alternatively you can [create your own Runtime AMI](docs/Create_Runtime_AMI.md) for running your SDAccel applications on F1.
    * *Assuming the developer flow (compilation) was done on a separate instance you will need to:*
      * Copy the compiled host executable (exe) to new instance
      * Copy the \*.awsxclbin AWS FPGA binary file to the new instance