Merge pull request #363 from aws/RC_v1_3_3

merge Rc v1 3 3

Author: kristopk

FAQs.md

@@ -104,22 +104,39 @@ It is the compiled FPGA code that is loaded into an FPGA in AWS for performing t
 
 The developer can create multiple AFIs at no extra cost, up to a defined limited (typically 100 AFIs per region per AWS account). An AFI can be loaded into as many FPGAs as needed. 
 
+
 **Q: What regions are supported?**
 
 AWS FPGA generation and EC2 F1 instances are supported in us-east-1 (N. Virginia), us-west-2 (Oregon) and ue-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.
 
 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.
 
+
 **Q: Can I load an AFI on every region AWS FPGA is supported?**
 
 Yes, but you must first copy the AFI using the [copy-fpga-image](./hdk/docs/copy_fpga_image.md) API.  You should generate AFIs in one region and use copy to make them available in other regions.  Copy preserves the Global AFI ID used to load an AFI on a EC2 instance.
 
 Use [describe-fpga-images](./hdk/docs/describe_fpga_images.md) with the [--region command line option](http://docs.aws.amazon.com/cli/latest/userguide/cli-command-line.html) to list AFIs available in a specific region.  Use `FpgaImageGlobalId` attribute and `fpga-image-global-id` filter to match AFI copies accross regions.
 
+**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](https://github.com/aws/aws-fpga/sdk). 
@@ -211,6 +228,19 @@ To be able to manage and monitor the F1 FPGAs it is required to install the [FPG
 
 Typically, you will not need the HDK nor any Xilinx Vivado tools on an F1 instance that is using prebuilt AFIs; unless, you want to do in-field debug using Vivado's ChipScope (Virtual JTAG).
 
+**Q: How do I update the AWS CLI to use the latest EC2 commands to manage my AFI's?**
+
+On the FPGA Developer AMI, you can update your AWS CLI for all users using the command:
+```
+sudo pip install awscli --upgrade 
+```
+
+If You want to upgrade the AWS CLI for just your user, you can run the following:
+```
+pip install awscli --upgrade --user
+```
+The AWS CLI [documentation page](http://docs.aws.amazon.com/cli/latest/userguide/installing.html) shows steps to update the AWS CLI.
+We recommend using the latest available version to be able to use the expanding list of commands that we add.
 
 ## Marketplace
 **Q: What does publishing my AFI/AMI to AWS Marketplace enables?**
@@ -404,4 +434,18 @@ elapsed = 00:08:59 . Memory (MB): peak = 4032.184 ; gain = 3031.297 ; free physi
 /opt/Xilinx/Vivado/2016.3/bin/loader: line 164:  8160 Killed                  "$RDI_PROG" "$@"
 Parent process (pid 8160) has died. This helper process will now exit
 
+**Q: Why am I getting an error: `A valid license was not found for feature 'XYZ' and/or device 'XYZ'` from Xilinx Vivado while trying to build by dcp/running my examples?**
+
+*For On Premise runs:* 
+
+You would need a valid [on premise license](./hdk/docs/on_premise_licensing_help.md) provided by Xilinx.
+
+*For runs using the FPGA Developer AMI:*
+
+**NOTE:** 
+>    * The license included on FPGA Developer AMI Versions 1.3.0_a and earlier expires on October 31 2017.
+>    * If you see the above error, please update to FPGA Developer AMI Version 1.3.3 or later.
+>    * All FPGA Developer AMI Versions 1.3.0_a and earlier will be deprecated once Version 1.3.3 is released.
 
+* If you are using the FPGA Developer AMI Version 1.3.3 or later, please check if the environment variable `XILINXD_LICENSE_FILE` is set to `/opt/Xilinx/license/XilinxAWS.lic`
+* If you still face the above error, please contact us on the forums and we'd be happy to help further.

RELEASE_NOTES.md

@@ -26,6 +26,9 @@
          *    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.3 (See [ERRATA](./ERRATA.md) for unsupported features)
+   *    New FPGA Image APIs for deleteing and reading/editing attributes 
+
 ## Release 1.3.2 (See [ERRATA](./ERRATA.md) for unsupported features)
    *    SDAccel general availability 
 

hdk/cl/examples/README.md

@@ -86,7 +86,7 @@ You need to prepare the following information:
 2. Generic description of the logic design *(Optional)*.
 3. Location of the tarball file object in S3.
 4. Location of an S3 directory where AWS would write back logs of the AFI creation.
-5. AWS region where the AFI will be created.  Use [copy-fpga-image](../../docs/copy-fpga-images.md) API if you need to load an AFI on a different region.
+5. AWS region where the AFI will be created.  Use [copy-fpga-image](../../docs/copy_fpga_image.md) API to copy an AFI to a different region.
 
 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)).
 For example, you can use the AWS CLI as follows:
@@ -154,7 +154,7 @@ After the AFI generation is complete, AWS will put the logs into the bucket loca
 **NOTE**: *Attempting to load the AFI immediately on an instance will result in an `Invalid AFI ID` error.
 Please wait until you confirm the AFI is created successfully.*
 
-The [copy-fpga-image](../../docs/copy-fpga-images.md) API allows you copy AFIs to other regions and avoid the time consuming `create-fpga-image` process. Copy will also preserve the source Global AFI ID and minimize region-specific changes to your instance code or scripts.
+The [copy-fpga-image](../../docs/copy_fpga_image.md) API allows you to copy the AFI to other regions and avoid the time consuming `create-fpga-image` process. Copy will also preserve the source Global AFI ID and minimize region-specific changes to your instance code or scripts.
 
 ## Step by step guide how to load and test a registered AFI from within an F1 instance
 

hdk/common/verif/include/sh_dpi_tasks.svh

@@ -393,7 +393,7 @@ end
              input logic [5:0] id = 6'h0); 
        logic [63:0] tmp;
        `SLOT_MACRO_TASK(peek(.addr(addr), .data(tmp), .id(id), .size(DataSize::UINT32), .intf(AxiPort::PORT_OCL)))
-       data = tmp[31:0];
+      data = {32'h0, tmp[31:0]};
    endtask
 
    //=================================================
@@ -431,7 +431,7 @@ end
              input logic [5:0] id = 6'h0); 
        logic [63:0] tmp;
        `SLOT_MACRO_TASK(peek(.addr(addr), .data(data), .id(id), .size(DataSize::UINT32), .intf(AxiPort::PORT_SDA)))
-       data = tmp[31:0];
+      data = {32'h0, tmp[31:0]};
    endtask
 
    //=================================================
@@ -467,9 +467,9 @@ end
              logic [63:0] addr, 
              output logic [63:0] data, 
              input logic [5:0] id = 6'h0); 
-       logic [63:0] tmp;
-       `SLOT_MACRO_TASK(peek(.addr(addr), .data(data), .id(id), .size(DataSize::UINT32), .intf(AxiPort::PORT_BAR1)))
-       data = tmp[31:0];
+      logic [63:0] tmp;
+      `SLOT_MACRO_TASK(peek(.addr(addr), .data(data), .id(id), .size(DataSize::UINT32), .intf(AxiPort::PORT_BAR1)))
+      data = {32'h0, tmp[31:0]};
    endtask
 
    function bit is_dma_to_cl_done(input int slot_id = 0, input int chan);

hdk/docs/Virtual_JTAG_XVC.md

@@ -8,9 +8,11 @@
 
 3. [Enabling Debug on FPGA-enabled EC2 Instance, using XVC](#startVJtag)
 
-4. [Connecting Xilinx Hardware Manager(Vivado Lab Edition) to the Debug Target FPGA-enabled EC2 Instance](#connectToTarget)
+4. [Connecting Xilinx Hardware Manager(Vivado Lab Edition) running on local F1 instance to the Debug Target FPGA-enabled EC2 Instance](#connectToTargetLocally)
 
-5. [Frequently Asked Questions](#faq)
+5. [Connecting Xilinx Hardware Manager(Vivado Lab Edition) running on remote machine to the Debug Target FPGA-enabled EC2 Instance](#connectToTargetRemotely)
+
+6. [Frequently Asked Questions](#faq)
 
 
 
@@ -88,10 +90,12 @@ You could call `sudo fpga-start-virtual-jtag -?` for further details on the avai
 
 
 
-<a name="connectToTarget"></a>
-# Connecting Xilinx Hardware Manager (Vivado Lab Edition) to the Debug Target FPGA-enabled EC2 Instance 
+<a name="connectToTargetLocally"></a>
+# Connecting Xilinx Hardware Manager (Vivado Lab Edition) running on local F1 instance to the Debug Target FPGA-enabled EC2 Instance 
+
+Xilinx Hardware Manager (Vivado Lab Edition) running on the target instance (i.e. the F1 itself). The TCP port on which the Virtual JTAG XVC Server is listening must be accessible to the host running Xilinx Hardware Management (See [FAQ](#faq) for configuring Linux firewall and AWS EC2 Network Security Groups). 
 
-Xilinx Hardware Manager (Vivado Lab Edition) running on the target instance (i.e. the F1 itself) or it can be running remotely on a different host. The TCP port on which the Virtual JTAG XVC Server is listening must be accessible to the host running Xilinx Hardware Management (See [FAQ](#faq) for configuring Linux firewall and AWS EC2 Network Security Groups). 
+<img src="./images/Virtual_JTAG_XVC_Server_F1_instance.jpg" width="600">
 
 To connect the debug Xilinx Hardware Manager to Virtual JTAG XVC server on the target, the following should be called on the machine hosting Vivado:
 
@@ -120,7 +124,7 @@ To connect the debug Xilinx Hardware Manager to Virtual JTAG XVC server on the t
 
 **NOTES:**
 
-- If you are running Vivado's Lab Edition on the same instance as the target instance, use IP address 127.0.0.1, which is the localhost.
+- Since you are running Vivado's Lab Edition on the same instance as the target instance, use IP address 127.0.0.1, which is the localhost.
 
 -  If the above command fails, its most likely that either the virtual jtag server is not running, the IP/Port are wrong, or a firewall/security-group rule is blocking the connection. See the [FAQ](#faq) section in the end of this document.
 
@@ -147,7 +151,72 @@ Vivado can now be used to debug your design: the next figure shows how a CL desi
 The connection Vivado and the target instance can be terminated by closing the XVC server from Vivado using the right click menu. If the target FPGA PCIe connection is lost, a new AFI is loaded or the Virtual JTAG Server application stops running, the connection to the FPGA and associated debug cores will also be lost. 
 
 **NOTE:** Xilinx Hardware Manager (Vivado Lab Edition) should not be connected to the target Virtual JTAG XVC Server when the AFI is not in READY state. If the AFI going to go through `fpga-clear-image` or `fpga-load-local-image`, Vivado should be disconnected, and the Virtual JTAG XVC Server should be terminated by killing the process the runs the JTAG XVC Server.
+ 
+  
+<a name="connectToTargetRemotely"></a>
+# Connecting Xilinx Hardware Manager (Vivado Lab Edition) running on a remote machine to the Debug Target FPGA-enabled EC2 Instance 
+
+<img src="./images/Virtual_JTAG_XVC_Server_remote_instance.jpg" width="600">
+
+
+Xilinx Hardware Manager (Vivado Lab Edition) running on a remote machine. The TCP port on which the hw_server and the Virtual JTAG XVC Server is listening must be accessible to the host running Xilinx Hardware Management (See [FAQ](#faq) for configuring Linux firewall and AWS EC2 Network Security Groups).
+Note: Running the hw_server locally on the F1 instance ensures superior performance between Vivado running on the remote machine to connect and debug the design running on the F1 instance. 
+
+To connect the debug Xilinx Hardware Manager to Virtual JTAG XVC server on the target, the following should be called on the machine hosting Vivado:
+
+1)	Launch Vivado Lab Edition (or full featured Vivado) 
+
+2)	Select “Open HW Manager” as shown in the next figure:
+  
+  
+<img src="./images/Open_HW_Manager.jpg" width="600">
 
+  
+  
+
+3)	Start Vivado hw_server using the following command in Vivado's .tcl console
+
+`> connect_hw_server -url <hostname or IP address>:3121`
+  
+  
+<img src="./images/connect_hw_server.jpg" width="600">  
+  
+   
+ 
+  
+
+4)	Connect to the target instance Virtual JTAG XVC server using the following command in Vivado's tcl console. 
+
+`> open_hw_target -xvc_url <hostname or IP address>:10201`
+
+**NOTES:**
+
+-  If the above command fails, its most likely that either the virtual jtag server is not running, the IP/Port are wrong, or a firewall/security-group rule is blocking the connection. See the [FAQ](#faq) section in the end of this document.
+
+
+Upon successful connection, Vivado's Hardware panel will be populated with a debug bridge instance. 
+ 
+5)	Select the debug bridge instance from the Vivado Hardware panel
+
+6)      You will need a "Probes file" in the next step.  A "Probes file" with an ".ltx" extension is generated during the build process and written to the checkpoints directory.   
+
+7)	In the Hardware Device Properties window select the appropriate “Probes file” for your design by clicking the icon next to the “Probes file” entry, selecting the file, and clicking “OK”. This will refresh the hardware device and it should now show the debug cores present in your design.  Note the Probes file is written out during the design implementation, and is typically has the extension ".ltx".
+
+<img src="./images/select_probes_file.jpg" width="600">  
+
+   
+     
+     
+Vivado can now be used to debug your design: the next figure shows how a CL design with two ILAs and one VIO would look in Vivado Lab Edition Hardware Manager, once the steps 1-6 mentioned earlier are followed
+
+<img src="./images/cl_vio_ila_screen.jpg">  
+
+## Other considerations
+
+The connection Vivado and the target instance can be terminated by closing the XVC server from Vivado using the right click menu. If the target FPGA PCIe connection is lost, a new AFI is loaded or the Virtual JTAG Server application stops running, the connection to the FPGA and associated debug cores will also be lost. 
+
+**NOTE:** Xilinx Hardware Manager (Vivado Lab Edition) should not be connected to the target Virtual JTAG XVC Server when the AFI is not in READY state. If the AFI going to go through `fpga-clear-image` or `fpga-load-local-image`, Vivado should be disconnected, and the Virtual JTAG XVC Server should be terminated by killing the process the runs the JTAG XVC Server.
+   
 
 <a name="faq"></a>
 # Frequently Asked Questions 
@@ -164,6 +233,8 @@ No, you may run Vivado on a "remote" host as long as your instance/VPC has the r
 
 **Q: Can I have a secure connection (i.e. SSL/TLS) to the target FPGA-enable EC2 Instance running Virtual JTAG service?**
 
+You may use the ssh "port forwarding" option (-L) to forward connections from the F1 instance via the SSH client, then to a destination server. You can now use this destination server in the Vivado Hardware Manager running on a remote machine to connect to the hw_server and Virtual JTAG server running on the F1 instance.  
+
 
 **Q: Do I need a Vivado license to use Virtual JTAG and Xilinx' VIO / LIA debug capabilities?**
 
@@ -182,6 +253,8 @@ Yes, you must start the the  `$ fpga-start-virtual-jtag` with a different Slot/P
 
 **Q: What are some of the best practices I should be aware when working with Virtual JTAG?**
 
+If you are running Vivado on a remote machine trying to connect to Virtual JTAG - we recommend running the hw_server on the F1 instance - to ensure optimal performance between Vivado and the Virtual JTAG server.
+
 
 **Q: Can other instances running on the same F1 server access the Virtual JTAG of my instance?**
 
@@ -203,4 +276,4 @@ This could mean there is already a server running with thtat TCP port.  Either f
 
 Xilinc Virtual Cable (XVC) is a protocol for transferring JTAG commands over TCP/IP network connection between a debug tool (like Vivado Lab Edition Hardware Manager) and a debug target.
 
-The full specification for XVC version 1.0 is available [here](https://github.com/Xilinx/XilinxVirtualCable/blob/master/README.md).  
+More information including a link to the full specification for XVC version 1.0 is available [here](https://www.xilinx.com/products/intellectual-property/xvc.html).  

hdk/docs/copy_fpga_image.md

@@ -9,13 +9,6 @@ To allow copies, the source AFI must meet the following requirements:
 * AFI must be owned by caller.  Access to an AFI does not grant sufficient permissions to copy it.
 * AFI must be in `available` state.  Copy is not allowed if source AFI is in `pending`, `failed` or `unavailable` states.
 
-## Load preview AWS cli model
-
-`copy-fpga-image` is currently a preview API available after loading the preview json model included in the SDK:
-```
-   $ aws configure add-model --service-name ec2 --service-model file://./sdk/aws-cli-preview/ec2_copy-fpga-image.json
-```
-
 ## Example usage
 
 * Show command manual page: