fix typos, streamline description (#97)

clarify role of aws_build_dcp_from_cl
clarify that FPGA Dev AMI have tools and license pre-installed
remove redundant text
explain that logs directory parameter is option, but needed for debug

Author: AWSNB

hdk/common/shell_current/new_cl_template/build/README.md

@@ -1,4 +1,4 @@
-# How to build and submit your Custom Logic (CL) to AWS 
+# How to Build and Submit your Custom Logic (CL) to AWS (RTL Flow)
 
 # Table of Contents
 
@@ -13,29 +13,31 @@
 
 ## Overview <a name="buildoverview"></a>
 
-Once the developer has a functional design, the next steps are to: synthesize the design into basic FPGA cells, perform place-and-route, and check that the design meets the timing/frequency constraints. This could be an iterative process. Upon success, the developer will need to pass the output of the flow to AWS for final AFI creation.
+Once the developer has a functional RTL design, the next steps are to: synthesize the design into basic FPGA cells, perform place-and-route, and check that the design meets the timing/frequency constraints. This could be an iterative process. Upon success, the developer will need to pass the output of the flow to AWS for final AFI creation.
 
-The developer needs to transfer to AWS a tar file that includes the encrypted placed-and-routed design checkpoints (referred to as DCP throughout this document) and [manifest](https://github.com/aws/aws-fpga/tree/master/hdk/docs/AFI_manifest.md): The DCP includes the complete developer design that meets timing/frequency constraints, placement boundaries  within the allocated CL area on the FPGA, and the functional requirements laid out in the [Shell Interface Specification](https://github.com/aws/aws-fpga/blob/master/hdk/docs/AWS_Shell_Interface_Specification.md#overview).  The [manifest.txt](https://github.com/aws/aws-fpga/tree/master/hdk/docs/AFI_manifest.md) should include key parameters needed for registering and loading the AFI like target frequency.
+The developer needs to transfer to AWS a tar file that includes the encrypted placed-and-routed design checkpoints (referred to as DCP throughout this document) and [manifest](https://github.com/aws/aws-fpga/tree/master/hdk/docs/AFI_manifest.md): The DCP includes the complete developer design that meets timing/frequency constraints, placement boundaries within the allocated CL area on the FPGA, and the functional requirements laid out in the [Shell Interface Specification](https://github.com/aws/aws-fpga/blob/master/hdk/docs/AWS_Shell_Interface_Specification.md#overview).  The [manifest.txt](https://github.com/aws/aws-fpga/tree/master/hdk/docs/AFI_manifest.md) should include key parameters needed for registering and loading the AFI like target frequency.
 
-To assist in this process, AWS provides a reference DCP that includes the shell (SH) logic with a black-boxed CL under: `$HDK_SHELL_DIR/build/checkpoints/from_aws/SH_CL_BB_routed.dcp`
+Few reference [CL examples](https://github.com/aws/aws-fpga/blob/master/hdk/cl/examples) can serve as starting points for new designs.  
 
-AWS also provides out-of-the-box generic script called `aws_build_dcp_from_cl.sh` that is used for test compile a few examples like `CL_simple` design as if they were developer code. These reference examples can serve as starting points for new designs. The output of AWS-provided scripts will create a a tar file, with both the encrypted placed-and-routed DCP and the corresponding `manifest.txt`, which AWS will use to generate final bitstreams.
+AWS provides out-of-the-box generic script called `aws_build_dcp_from_cl.sh` that performs complete build process from RTL (verilog for example). The output of AWS-provided scripts will create a a tar file, with both the encrypted placed-and-routed DCP and the corresponding `manifest.txt`, which AWS will use to generate final bitstreams.
 
-To ease and experiment with multiple implementation methods for DCP to meet placement and timing constrains, the `aws_build_dcp_from_cl.sh` provides multiple choices for implementation strategy , invoked by the `-strategy` option. Please call `aws_build_dcp_from_cl.sh -help` for the list of supported capabilities.
+To ease and experiment with multiple implementation methods for DCP to meet placement and timing constrains, the `aws_build_dcp_from_cl.sh` provides multiple choices for implementation strategy, invoked by the `-strategy` option. Please call `aws_build_dcp_from_cl.sh -help` for the list of supported capabilities.
 
-Advanced developers can use different scripts, tools, and techniques (e.g., regioning),  with the  condition that they submit both the `manifest.txt` and "encrypted placed-and-routed design checkpoints (DCP)" in a single tar file, that passes final checks which are included in the build scripts.  (TBD - final_check_dcp).
+Advanced developers can use different scripts, tools, and techniques (e.g., regioning),  with the  condition that they submit both the `manifest.txt` and **encrypted placed-and-routed design checkpoints (DCP)** in a single tar file, that passes final checks which are included in the build scripts.  (TBD - final_check_dcp).
 
 ## Build Procedure <a name="stepbystep"></a>
 
 The following describes the step-by-step procedure to build developer CLs. Some of these steps can be modified or adjusted based on developer experience and design needs. 
 
-A developer can execute `$HDK_SHELL_DIR/build/scripts/aws_build_dcp_from_cl.sh` to check the environment, setup the build directory, invoke Xilinx Vivado to create the encrypted placed-and-routed DCP (which include AWS Shell + Developer CL), create the [`manifest.txt`](https://github.com/aws/aws-fpga/tree/master/hdk/docs/AFI_manifest.md) that AWS will ingest through the CreateFpgaImage EC2 API. Executing this script also entails encryption of developer-specified RTL files. Further details on invoking the script from Vivado are provided below.
+A developer can execute `$HDK_SHELL_DIR/build/scripts/aws_build_dcp_from_cl.sh` which validates that the environment variables and directory structure is set properly, setup the build directory, invoke Xilinx Vivado to create the encrypted placed-and-routed DCP (which include AWS Shell + Developer CL), create the [`manifest.txt`](https://github.com/aws/aws-fpga/tree/master/hdk/docs/AFI_manifest.md) that AWS will ingest through the `create-fpga-mage` EC2 API. Executing this script also entails encryption of developer-specified RTL files. Further details on invoking the script from Vivado are provided below.
 
 ### 1) Pre-requisite: Environment Variables and Tools
 
- 1. The environment variable `HDK_SHELL_DIR` should have been set. This is usually done by executing `source hdk_setup.sh` from the HDK root directory
+ 1. The environment variables `HDK_DIR` and `HDK_SHELL_DIR` should have been set. This is usually done by executing `source hdk_setup.sh` from the HDK root directory  
+ 
  2. The environment variable `CL_DIR` should have been set pointing to the root directory where the CL exists. The CL root directory should have the `/build` and `/design` subdirectories. One way to make sure to have the right directory is to execute `source $(HDK_DIR)/cl/developer_designs/prepare_new_cl.sh`
- 3. Developer have Xilinx Vivado tools installed, with the supported version by the HDK, and with proper license. If the developer is using AWS supplied [FPGA Development AMI](https://aws.amazon.com/marketplace/AmazonFPGAAmi) from AWS marketplace, it includes the README.md how to setup up the tools and license.  
+ 
+ 3. Developer have Xilinx Vivado tools installed, with the supported version by the HDK, and with proper license. If the developer is using AWS supplied [FPGA Development AMI](https://aws.amazon.com/marketplace/AmazonFPGAAmi) from AWS marketplace, it already include Vivado tools and license.  
 
 ### 2) Encrypt Source Files
 
@@ -44,7 +46,7 @@ As a pre-cursor to the build process,  modify the `$CL_DIR/build/scripts/encrypt
 ### 3) Prepare for the CL Build 
 
 Modify the `$CL_DIR/build/scripts/create_dcp_from_cl.tcl` script to include: 
- 1. The list of CL encrypted files in `$CL_DIR/build/src_post_encryption`.
+ 1. The list of CL encrypted files in `$CL_DIR/build/src_post_encryption`. (They can be the duplicate file list of what in `$CL_DIR/build/scripts/encrypt.tcl`)
  2. The list of CL specific timing and placement constraints in `$CL_DIR/build/constraints`.
  3. The specific constraints and design file for IP any included in your CL (e.g., DDR4).
 
@@ -97,9 +99,9 @@ In addition, in order to aid developers with build verification, there is a fina
 The outputs of the build script are:
  - `$CL_DIR/build/checkpoints/*`: Various checkpoints generated during the build process.
  - `$CL_DIR/build/to_aws/SH_CL_routed.dcp`: Encrypted placed-and-routed design checkpoint for AWS ingestion.
+ - `$CL_DIR/build/to_aws/manifest.txt`: Encrypted placed-and-routed design checkpoint for AWS ingestion.
  - `$CL_DIR/build/reports/*`: Various build reports (generally, check_timing/report_timing).
  - `$CL_DIR/build/src_post_encryption/*`: Encrypted developer source.
- - `$CL_DIR/build/constraints/*`: Implementation constraints.
 
 A developer may need to iterate multiple times through this process until arriving upon an error-free run.
 
@@ -110,12 +112,12 @@ You need to prepare the following information:
 
 1. Name of the logic design *(Optional)*.
 2. Generic description of the logic design *(Optional)*.
-3. PCI IDs: Device, Vendor, Subsystem, SubsystemVendor.
+3. PCI IDs: Device, Vendor, Subsystem, SubsystemVendor (See https://github.com/aws/aws-fpga/blob/master/hdk/docs/Choosing_PCIe_ID_for_AFI.md)
 4. Location of the tarball file object in S3.
-5. Location of an S3 directory where AWS would write back logs of the AFI creation.
-6. Version of the AWS Shell.
+5. Location of an S3 directory where AWS would write back logs of the AFI creation *(Optional)*. This would be required to get the **.ltx** file needed if Virtual JTAG and Xilinx LIA/VIO debug cores to be used.
+6. Version of the AWS Shell. (Eventually AWS will use the shell_version in the manifest.txt and ignore the parameter passed to create-fpga-image)
 
-**NOTE**: *The PCI IDs for the example CLs should be found in the README files in the respective CL example directory.
+**NOTE**: *The PCI IDs for the example CLs should be found in the README files in the respective CL example directory.*
 If you are building a custom CL, then you need to incorporate these values in your design as shown in the [AWS Shell Interface Specifications](https://github.com/aws/aws-fpga/blob/master/hdk/docs/AWS_Shell_Interface_Specification.md#pcie-ids).*
 
 To upload your tarball file to S3, you can use any of [the tools supported by S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/UploadingObjects.html)).