From 934000f9a57c0cde8786441864d5c6e0cf42fef9 Mon Sep 17 00:00:00 2001 From: Kristopher King Date: Thu, 5 Oct 2017 10:12:27 -0500 Subject: [PATCH] Doc updates only: Fixes to links and additional SDAccel updates based on customer feedback and AWS forum posts --- FAQs.md | 6 +- SDAccel/FAQ.md | 94 +++++++++---------- SDAccel/README.md | 30 +++--- SDAccel/docs/Create_Runtime_AMI.md | 77 +++++++++++++++ SDAccel/docs/Setup_AWS_CLI_and_S3_Bucket.md | 14 ++- hdk/README.md | 2 +- sdk/linux_kernel_drivers/edma/README.md | 4 +- sdk/linux_kernel_drivers/edma/edma_install.md | 2 +- .../edma/user_defined_interrupts_README.md | 2 +- 9 files changed, 157 insertions(+), 74 deletions(-) create mode 100644 SDAccel/docs/Create_Runtime_AMI.md diff --git a/FAQs.md b/FAQs.md index 8382b92b0..4cf8f1738 100644 --- 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 index c6ebc0ef0..d3b69f61b 100644 --- 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 MHz for . The frequency is being automatically changed to 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 index 34fbef8f4..e8128c3d0 100644 --- 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 ## 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) +* 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. ## Github and Environment Setup (Once per new instance or machine) @@ -56,7 +57,7 @@ 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 @@ -64,7 +65,6 @@ This quick start guide will use a simple "Hello World" SDAccel example to get yo $ source sdaccel_setup.sh ``` - # 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 @@ -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:///```) 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 diff --git a/SDAccel/docs/Create_Runtime_AMI.md b/SDAccel/docs/Create_Runtime_AMI.md new file mode 100644 index 000000000..2ae5bb545 --- /dev/null +++ b/SDAccel/docs/Create_Runtime_AMI.md @@ -0,0 +1,77 @@ +# Create a Runtime AMI Starting with an Amazon Linux AMI or Ubuntu + +## 1. Launch a Runtime Instance & Install Required Packages + +### Using Amazon Linux + +* Launch an F1 instance using an [Amazon Linux AMI](https://aws.amazon.com/marketplace/pp/B00635Y2IW) +* Install the required updates + +```` + $ sudo yum update +```` +* Reboot your Runtime Instance to ensure all updates are running. +* Install the required packages +```` + $ sudo yum install git + $ sudo yum install gcc + $ sudo yum install gcc-c++ + $ sudo yum install kernel-headers + $ sudo yum install kernel-devel + $ sudo yum --enablerepo=epel install ocl-icd ocl-icd-devel opencl-headers + $ sudo mkdir -p /etc/OpenCL/vendors/ +```` + +### Using Ubuntu + +* Launch an F1 instance using an [Ubuntu 16.04 LTS](https://aws.amazon.com/marketplace/pp/B01JBL2I8U) +* Install the required updates +```` + $ sudo apt-get update +```` +* Reboot your Runtime Instance to ensure all updates are running. +* Install the required packages +```` + $ sudo apt-get install gcc + $ sudo apt-get install g++ + $ sudo apt-get install make + $ sudo apt-get install linux-headers-`uname -r` + $ sudo apt-get install linux-libc-dev + $ sudo apt-get install ocl-icd-dev ocl-icd-libopencl1 opencl-headers ocl-icd-opencl-dev + $ sudo mkdir -p /etc/OpenCL/vendors/ +```` + + +## 2. Copy required Xilinx SDAccel Runtime Libraries to the Instance and Reboot your Runtime Instance. + +* Using an instance running [FPGA Developer AMI](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ) or an on-premises machine with access to a Xilinx SDAccel Tools Installation, run the following: + +```` + $ mkdir -p xlnxrte/lib/lnx64.o + $ mkdir -p xlnxrte/runtime/bin + $ cp $XIILNX_SDX/lib/lnx64.o/libstdc++.so* xlnxrte/lib/lnx64.o/. + $ cp $XIILNX_SDX/lib/lnx64.o/libxilinxopencl.so xlnxrte/lib/lnx64.o/. + $ cp $XIILNX_SDX/runtime/bin/xclbinsplit xlnxrte/runtime/bin + $ cp $XIILNX_SDX/runtime/bin/xclbincat xlnxrte/runtime/bin +```` + +* Copy xlnxrte directory created to $HOME on your Runtime Instance. + + +## 3. Install Runtime Drivers and run your FPGA accelerated application on your Runtime Instance. +* Log back on to the Runtime Instance: + +``` + $ export XILINX_SDX=$HOME/xlnxrte +```` +* You should be able to [run your FPGA accelerated application as described here](https://github.com/aws/aws-fpga/tree/master/SDAccel#runonf1), without needing to launch a new F1 instance + + +## 4. Create your Runtime AMI based on your Instance. + +* Once you have your application running you should be able to create a Runtime AMI based your Runtime Instance as specified [here](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-an-ami-ebs.html). + +## 5. Make Runtime AMI available on the AWS Marketplace + +* Please see [Section 5 of the AWS Marketplace Seller's Guide](https://awsmp-loadforms.s3.amazonaws.com/AWS_Marketplace_-_Seller_Guide.pdf#page=19) for more details. + diff --git a/SDAccel/docs/Setup_AWS_CLI_and_S3_Bucket.md b/SDAccel/docs/Setup_AWS_CLI_and_S3_Bucket.md index 9b60655a5..2b1bdeb4e 100644 --- a/SDAccel/docs/Setup_AWS_CLI_and_S3_Bucket.md +++ b/SDAccel/docs/Setup_AWS_CLI_and_S3_Bucket.md @@ -1,20 +1,26 @@ ## Setup CLI and Create S3 Bucket +The developer is required to create a S3 bucket for the AFI generation. The bucket will contain a tar file and logs which are generated from the AFI creation service. To install the AWS CLI, please follow the instructions here: (http://docs.aws.amazon.com/cli/latest/userguide/installing.html). + +The AWS SDAccel scripts require JSON output format and the scripts will not work properly if you use any other output format types (ex: text, table). JSON is the default output format of the AWS CLI. + ``` - $ aws configure # to set your credentials (found in your console.aws.amazon.com page) and region (us-east-1) + $ aws configure # to set your credentials (found in your console.aws.amazon.com page), region (us-east-1) and output (json) ``` -Create a bucket and folder: +This S3 bucket will be used by the AWS SDAccel scripts to upload your DCP to AWS for AFI generation which will be packaged into a tar file. +Start by creating a bucket and a folder within your new bucket: ``` $ aws s3 mb s3:// --region us-east-1 # Create an S3 bucket (choose a unique bucket name) $ aws s3 mb s3:/// # Create folder for your tarball files $ touch FILES_GO_HERE.txt # Create a temp file $ aws s3 cp FILES_GO_HERE.txt s3://// # Which creates the folder on S3 ``` -Create a folder for your log files +The AFI creation process will generate logs and will be placed in your S3 bucket. These logs can be used for debug if the AFI generation fails. +Next, create a folder for your log files: ``` $ aws s3 mb s3:/// # Create a folder to keep your logs $ touch LOGS_FILES_GO_HERE.txt # Create a temp file $ aws s3 cp LOGS_FILES_GO_HERE.txt s3://// # Which creates the folder on S3 ``` - +Once your AFI has been created successfully, you are free to delete the tar file and logs as needed. Deleting these files will not delete or modify your AFI. diff --git a/hdk/README.md b/hdk/README.md index 54129a8f3..1192f1ed7 100644 --- a/hdk/README.md +++ b/hdk/README.md @@ -82,7 +82,7 @@ Follow the [RTL simulation environment setup](./docs/RTL_Simulating_CL_Designs.m ### Build and submit the Custom Logic to AWS for generating an AFI -You can follow the [build scripts readme](./common/shell_v04151701/new_cl_template/build/README.md) for step-by-step instructions on how to setup the scripts and run the build process. +You can follow the [build scripts readme](./common/shell_v071417d3/new_cl_template/build/README.md) for step-by-step instructions on how to setup the scripts and run the build process. This [checklist](./cl/CHECKLIST_BEFORE_BUILDING_CL.md) should be consulted before you start the build process. diff --git a/sdk/linux_kernel_drivers/edma/README.md b/sdk/linux_kernel_drivers/edma/README.md index 0a155fe09..540e931b4 100644 --- a/sdk/linux_kernel_drivers/edma/README.md +++ b/sdk/linux_kernel_drivers/edma/README.md @@ -36,7 +36,7 @@ EDMA driver source code is distributed with AWS FPGA HDK and SDK. ** NOTE: Usage of EDMA is not mandatory. AWS provides memory-mapped PCIe address space for direct communication between CPU and FPGA. ** -For a complete description of the different CPU to FPGA communication options and various options available, please review the [Programmers' View](https://github.com/aws/aws-fpga/blob/master/hdk/docs/Programmer_View.md). +For a complete description of the different CPU to FPGA communication options and various options available, please review the [Programmers' View](../../../hdk/docs/Programmer_View.md). # Quick Example @@ -130,7 +130,7 @@ The EDMA can be used in any user-space program, using simple device operations f EDMA data movement commands (like `read()` and `write()`) use a buffer pointers `void*` to the instance CPU memory, while using file offset `off_t` to present the write-to/read-from address in the FPGA. -**NOTE: ** In EC2 F1 instances, the file offset represents the write-to/read-from address in the FPGA relative to AppPF BAR4 128GB address space. The DMA cannot access any other PCIe BAR space. Refer to [FPGA PCIe Memory Address Map](aws-fpga/hdk/docs/AWS_Fpga_Pcie_Memory_Map.md). +**NOTE: ** In EC2 F1 instances, the file offset represents the write-to/read-from address in the FPGA relative to AppPF BAR4 128GB address space. The DMA cannot access any other PCIe BAR space. Refer to [FPGA PCIe Memory Address Map](../../../hdk/docs/AWS_Fpga_Pcie_Memory_Map.md). diff --git a/sdk/linux_kernel_drivers/edma/edma_install.md b/sdk/linux_kernel_drivers/edma/edma_install.md index 3c323ee18..6582b7d65 100644 --- a/sdk/linux_kernel_drivers/edma/edma_install.md +++ b/sdk/linux_kernel_drivers/edma/edma_install.md @@ -1,7 +1,7 @@ # Elastic DMA (EDMA) Installation and Frequently Asked Questions -EDMA is a Linux kernel driver provided by AWS for using DMA and/or User-defined interrupts for AWS FPGAs. Please see [EDMA README](./edma_README.md) for details. +EDMA is a Linux kernel driver provided by AWS for using DMA and/or User-defined interrupts for AWS FPGAs. Please see [EDMA README](./README.md) for details. # Table of Contents diff --git a/sdk/linux_kernel_drivers/edma/user_defined_interrupts_README.md b/sdk/linux_kernel_drivers/edma/user_defined_interrupts_README.md index 2ec15d890..2365b361f 100644 --- a/sdk/linux_kernel_drivers/edma/user_defined_interrupts_README.md +++ b/sdk/linux_kernel_drivers/edma/user_defined_interrupts_README.md @@ -69,7 +69,7 @@ The next example shows how an application can register to two events (aka user-d **Q: How can I toggle an interrupt event from within the CL?** -Toggling of user interrupt event by toggling the `cl_sh_apppf_int_req` interface to an MSI-X, which gets translated to an event in Linux userspace that an application can poll() on. Follow https://github.com/aws/aws-fpga/master/blob/hdl/docs/AWS_Shell_Interface_Specification.md) for the hardware interface details. +Toggling of user interrupt event by toggling the `cl_sh_apppf_int_req` interface to an MSI-X, which gets translated to an event in Linux userspace that an application can poll() on. Follow [AWS Shell Interface Spec](../hdk/docs/AWS_Shell_Interface_Specification.md) for the hardware interface details.