initial 1.3.3 changes

wjblanke · Sep 22, 2017 · e774084 · e774084
1 parent 7d2e50c
commit e774084
Show file tree

Hide file tree

Showing 10 changed files with 344 additions and 19,926 deletions.
diff --git a/FAQs.md b/FAQs.md
@@ -120,6 +120,20 @@ Yes, but you must first copy the AFI using the [copy-fpga-image](./hdk/docs/copy
 
 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). 

diff --git a/hdk/cl/examples/README.md b/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
 

diff --git a/hdk/common/verif/include/sh_dpi_tasks.svh b/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);

diff --git a/hdk/docs/Virtual_JTAG_XVC.md b/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).  
diff --git a/hdk/docs/copy_fpga_image.md b/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:

diff --git a/hdk/docs/delete_fpga_image.md b/hdk/docs/delete_fpga_image.md
@@ -0,0 +1,67 @@
+# AWS EC2 API delete-fpga-image
+
+Use `aws ec2 delete-fpga-image` to delete an AFI.  Delete operations are restricted to the target region determined by the aws-cli default region or 
+[region](http://docs.aws.amazon.com/cli/latest/userguide/cli-command-line.html) argument.  Deleting an AFI in one region has no effect on AFIs in other regions.
+
+Delete is not allowed if the AFI is public or shared with other accounts.  Use [describe-fpga-image-attribute](./fpga_image_attributes.md) to check if an AFI is shared,
+and [reset-fpga-image-attribute](./fpga_image_attributes.md) to remove all load permissions.
+
+Deleting an AFI does not affect AFIs already loaded onto FPGAs. Deleting only prevents new attempts to load an AFI onto an FPGA.  Note that, within a region, an AFI will 
+continue to be loadable as long as its Global AFI ID is available. Use [describe-fpga-images](./describe_fpga_images.md) with `fpga-image-global-id` filter to find AFIs with the same Global AFI ID.
+
+An AFI will not be recoverable after deleting all copies in all regions.  Use [IAM Policies for Amazon EC2](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-policies-for-amazon-ec2.html)
+to restrict access to the API unless explicitly required (See [IAM best practices](http://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege)). 
+For example, include the following statement in your IAM policy to deny access to `DeleteFpgaImage`:
+
+```
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": [
+        "ec2:DeleteFpgaImage"
+      ],
+      "Effect": "Deny",
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+## Example usage
+
+* Show command manual page:
+```
+    $ aws ec2 delete-fpga-image help
+```
+
+* Delete AFI:
+```
+    $ aws ec2 --region us-east-1 delete-fpga-image --fpga-image-id afi-0e5361a69d2af203d
+    {
+        "Return": true
+    }
+```
+
+## Common Error Messages
+
+* Describe an AFI after delete:
+```
+    $ aws ec2 --region us-east-1 describe-fpga-images --fpga-image-ids afi-0e5361a69d2af203d
+
+    An error occurred (InvalidFpgaImageID.NotFound) when calling the DescribeFpgaImages operation: Image ID 'afi-0e5361a69d2af203d' not found.
+```
+
+* Delete shared AFI
+```
+    $ aws ec2 --region us-east-1 delete-fpga-image --fpga-image-id afi-0e5361a69d2af203d
+
+    An error occurred (OperationNotPermitted) when calling the DeleteFpgaImage operation: Operation not permitted for shared AFI
+```
+
+* Delete public AFI
+```
+    $ aws ec2 --region us-east-1 delete-fpga-image --fpga-image-id afi-0e5361a69d2af203d
+
+    An error occurred (OperationNotPermitted) when calling the DeleteFpgaImage operation: Operation not permitted for public AFI
+```