v1.2.4 release

Author: kristopk

FAQs.md

@@ -112,7 +112,7 @@ The developer can create multiple AFIs at no extra cost, up to a defined limited
 
 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 bring my own bitstream for loading on an F1 FPGA?**
 
@@ -128,7 +128,7 @@ Yes, on-premises tools can be used to develop the Design Checkpoint needed for c
 If a developer uses local tools and license, please check the [supported versions of Vivado](./hdk/supported_vivado_versions.txt) for the exact Xilinx Vivado tool version supported by the HDK.  Developers have access to Xilinx Vivado running in the AWS by using the [FPGA Developer AMI on AWS Marketplace](https://aws.amazon.com/marketplace/pp/B06VVYBLZZ)
 
 
-**Q: Is there a “best practice” system template? **
+**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)
 
@@ -384,7 +384,7 @@ The Shell consumes about 20% of the FPGA resources, and that includes the PCIe G
 
 
 ## Troubleshooting
-**Q: Why do I see error “vivado not found” while running hdk_setup.sh*?**
+**Q: Why do I see error “vivado not found” while running hdk_setup.sh?**
 
 This is an indication that Xilinx Vivado tool set are not installed. Try installing the tool if you are working on your own environment, or alternative use AWS FPGA Development AMI available on AWS Marketplace, which comes with pre-installed Vivado toolset and license.
 

RELEASE_NOTES.md

@@ -27,6 +27,11 @@ See [Errata](./ERRATA.md) for additional documentation of unsupported features a
          *     1 DDR controller implemented in the SH (always available)
          *     3 DDR controllers implemented in the CL (configurable number of implemented controllers allowed)
 
+# Release 1.2.4
+   *    AWS SDK API `aws ec2 describe-fpga-images` released. See [describe-fpga-images](./hdk/docs/describe_fpga_images.md) document for details on how to use this API.
+   *    Fix cl_dram_dam debug probes (.ltx) generation in build scripts
+   *    Fixed bugs with DMA in the simulation model and testbench
+
 # Release 1.2.3
    *    New [Errata](./ERRATA.md) 
    *    Added debug probes (.ltx) generation to build scripts

hdk/cl/examples/README.md

@@ -170,12 +170,35 @@ Once your policy passes the checks, your ready to start AFI creation.
 The output of this command includes two identifiers that refer to your AFI:
 - **FPGA Image Identifier** or **AFI ID**: this is the main ID used to manage your AFI through the AWS EC2 CLI commands and AWS SDK APIs.
     This ID is regional, i.e., if an AFI is copied across multiple regions, it will have a different unique AFI ID in each region.
-    An example AFI ID is **`agfi-0f0e045f919413242`**.
+    An example AFI ID is **`afi-06d0ffc989feeea2a`**.
 - **Glogal FPGA Image Identifier** or **AGFI ID**: this is a global ID that is used to refer to an AFI from within an F1 instance.
     For example, to load or clear an AFI from an FPGA slot, you use the AGFI ID.
     Since the AGFI IDs is global (by design), it allows you to copy a combination of AFI/AMI to multiple regions, and they will work without requiring any extra setup.
     An example AGFI ID is **`agfi-0f0e045f919413242`**.
 
+The [describe-fpga-images](../../docs/describe_fpga_images.md) API allows you to check the AFI state during the background AFI generation process.  You must provide the **FPGA Image Identifier** returned by `create-fpga-image`:
+```
+    $ aws ec2 describe-fpga-images --fpga-image-ids afi-06d0ffc989feeea2a
+```
+
+The AFI can only be loaded to an instance once the AFI generation completes and the AFI state is set to `available`: 
+```
+    {
+        "FpgaImages": [
+            {
+			    ...
+                "State": {
+                    "Code": "available"
+                },
+			    ...
+                "FpgaImageId": "afi-06d0ffc989feeea2a",
+			    ...
+            }
+        ]
+    }
+
+```
+
 After the AFI generation is complete, AWS will put the logs into the bucket location (```s3://<bucket-name>/<logs-folder-name>```) provided by the developer. The presence of these logs is an indication that the creation process is complete. Please look for either a “State” file indicating the state of the AFI (e.g., available or failed), or the Vivado logs detailing errors encountered during the creation process.  For help with AFI creation issues, see [create-fpga-image error codes](../../docs/create_fpga_image_error_codes.md)
 
 

hdk/cl/examples/cl_dram_dma/build/scripts/create_dcp_from_cl.tcl

@@ -352,6 +352,7 @@ write_checkpoint -force $CL_DIR/build/checkpoints/${timestamp}.CL.post_synth.dcp
 write_debug_probes -force -no_partial_ltxfile -file $CL_DIR/build/checkpoints/${timestamp}.debug_probes.ltx
 
 close_project
+
 #Set param back to default value
 set_param sta.enableAutoGenClkNamePersistence 1
 
@@ -585,6 +586,10 @@ report_timing_summary -file $CL_DIR/build/reports/${timestamp}.SH_CL_final_timin
 puts "AWS FPGA: ([clock format [clock seconds] -format %T]) writing final DCP to to_aws directory.";
 
 write_checkpoint -force $CL_DIR/build/checkpoints/to_aws/${timestamp}.SH_CL_routed.dcp
+
+# Generate debug probes file
+write_debug_probes -force -no_partial_ltxfile -file $CL_DIR/build/checkpoints/${timestamp}.debug_probes.ltx
+
 close_project
 
 # ################################################

hdk/cl/examples/cl_dram_dma/verif/tests/test_dram_dma.sv

@@ -117,12 +117,6 @@ module test_dram_dma();
 
        $display("[%t] : starting C2H DMA channels ", $realtime);
 
-       //Start transfers of data from CL DDR
-       tb.start_que_to_buffer(.chan(0));   
-       tb.start_que_to_buffer(.chan(1));   
-       tb.start_que_to_buffer(.chan(2));   
-       tb.start_que_to_buffer(.chan(3));   
-
        // read the data from cl and put it in the host memory 
        host_memory_buffer_address = 64'h0_0001_0800;
        tb.que_cl_to_buffer(.chan(0), .dst_addr(host_memory_buffer_address), .cl_addr(64'h0000_0000_0002), .len(len0) );  // move DDR0 to buffer
@@ -136,6 +130,12 @@ module test_dram_dma();
        host_memory_buffer_address = 64'h0_0004_3800;                                                                                        
        tb.que_cl_to_buffer(.chan(3), .dst_addr(host_memory_buffer_address), .cl_addr(64'h0000_3000_0000), .len(len3) );  // move DDR3 to buffer
 
+       //Start transfers of data from CL DDR
+       tb.start_que_to_buffer(.chan(0));   
+       tb.start_que_to_buffer(.chan(1));   
+       tb.start_que_to_buffer(.chan(2));   
+       tb.start_que_to_buffer(.chan(3));   
+
        // wait for dma transfers to complete
        timeout_count = 0;       
        do begin
@@ -152,7 +152,8 @@ module test_dram_dma();
           error_count++;
        end
 
-
+       #1us;
+       
        // DDR 0
        // Compare the data in host memory with the expected data
        $display("[%t] : DMA buffer from DDR 0", $realtime);

hdk/common/verif/models/sh_bfm/sh_bfm.sv

@@ -497,6 +497,8 @@ module sh_bfm #(
    } DMA_OP;
 
    DMA_OP h2c_dma_list[0:3][$];
+   int    h2c_dma_wr_cmd_cnt[0:3];
+   
    DMA_OP c2h_dma_list[0:3][$];
    DMA_OP c2h_data_dma_list[0:3][$];
 
@@ -682,6 +684,12 @@ module sh_bfm #(
    //
    //=================================================
 
+   // initial various counts for DMA operations
+   initial begin
+      for(int i=0; i<4; i++)
+        h2c_dma_wr_cmd_cnt[i] = 0;
+   end
+   
    //
    // sh->cl Address Write Channel
    //
@@ -732,7 +740,11 @@ module sh_bfm #(
             if (debug) begin
                $display("[%t] : DEBUG popping wr data fifo - %d", $realtime, sh_cl_wr_data.size());
             end
-            h2c_dma_done[sh_cl_wr_data[0].id] = 1'b1; 
+
+            if (sh_cl_dma_pcis_wlast)
+              h2c_dma_wr_cmd_cnt[sh_cl_wr_data[0].id]--;
+            
+            h2c_dma_done[sh_cl_wr_data[0].id] =  (h2c_dma_wr_cmd_cnt[sh_cl_wr_data[0].id] == 0); 
             sh_cl_wr_data.pop_front();
          end
 
@@ -1918,7 +1930,8 @@ module sh_bfm #(
                 axi_cmd.id   = chan;
                 axi_cmd.size = 6;
                 sh_cl_wr_cmds.push_back(axi_cmd);
-
+                h2c_dma_wr_cmd_cnt[chan]++;
+                 
                 // loop to do multiple data beats
                 for(int j = 0; j <= axi_cmd.len; j++) begin
                   axi_data.data = 0;
@@ -1978,9 +1991,13 @@ module sh_bfm #(
                 end
                 byte_cnt[chan]++;
               end
-              c2h_dma_done[chan] = 1'b1;
+              c2h_dma_done[chan] = (c2h_data_dma_list[chan].size() == 0);
+
+              if ((cl_sh_rd_data[0].last == 1) && (byte_cnt[chan] >= dop.len)) // end of current DMA op, reset byte count
+                byte_cnt[chan] = 0;
+               
               cl_sh_rd_data.pop_front();
-            end
+            end // if (chan == cl_sh_rd_data[0].id)
           end
         end
       end

hdk/docs/describe_fpga_images.md

@@ -0,0 +1,191 @@
+# AWS EC2 API describe-fpga-images
+
+Use `aws ec2 describe-fpga-images` API to get information about all AFIs available to your AWS account.  The set of AFIs returned by `describe-fpga-images` includes:
+
+* AFIs owned by your AWS account.
+* AFIs owned by other AWS accounts for which you have been granted load permissions.
+* Public AFIs.
+
+The API provides various filters to get information about specific AFIs.  Invoke `aws ec2 describe-fpga-images help` to get an up-to-date list of available filters.  See **Example usage** section in this document for common filters.
+
+AFI information is accessible using `describe-fpga-images` immediately after `create-fpga-image` returns with a valid `afiId`.  The information provided by `describe-fpga-images` includes AFI states to check the result of the bitstream generation process:
+
+* `pending` AFI bitstream generation is in progress.
+* `available` AFI is available for use by F1 instances.
+* `failed` AFI bitstream generation failed.  The `State.Message` field provides the specific error code as described in [create-fpga-image error codes](create_fpga_image_error_codes.md).
+* `unavailable` AFI is no longer available for use by F1 instances.
+
+
+## Example response
+
+The following response shows the AFI information provided by `describe-fpga-images`.  The AFIs shown in this case are the public AFIs generated from the example CLs in the HDK.
+
+```
+    {
+        "FpgaImages": [
+            {
+                "OwnerAlias": "amazon",
+                "UpdateTime": "2017-04-19T17:15:26.000Z",
+                "Name": "cl_hellow_world_04151701",
+                "PciId": {
+                    "SubsystemVendorId": "0xfedd",
+                    "VendorId": "0x1d0f",
+                    "DeviceId": "0xf000",
+                    "SubsystemId": "0x1d51"
+                },
+                "FpgaImageGlobalId": "agfi-0f0e045f919413242",
+                "State": {
+                    "Code": "available"
+                },
+                "ShellVersion": "0x04151701",
+                "OwnerId": "095707098027",
+                "FpgaImageId": "afi-0f0927bc2649e6259",
+                "CreateTime": "2017-04-19T17:15:25.000Z",
+                "Description": "cl_hello_world for shell 0x04151701"
+            },
+            {
+                "OwnerAlias": "amazon",
+                "UpdateTime": "2017-04-17T15:58:54.000Z",
+                "Name": "cl_dram_dma_0415",
+                "PciId": {
+                    "SubsystemVendorId": "0xfedc",
+                    "VendorId": "0x1d0f",
+                    "DeviceId": "0xf001",
+                    "SubsystemId": "0x1d51"
+                },
+                "FpgaImageGlobalId": "agfi-0d873e8b409f8e806",
+                "State": {
+                    "Code": "available"
+                },
+                "ShellVersion": "0x04151701",
+                "OwnerId": "095707098027",
+                "FpgaImageId": "afi-06d0ffc989feeea2a",
+                "CreateTime": "2017-04-17T15:58:54.000Z",
+                "Description": "cl_dram_dma_0415"
+            }
+        ]
+    }
+```
+
+## Example usage
+
+* Get all AFIs accessible to caller AWS account
+```
+    $ aws ec2 describe-fpga-images
+```
+
+* Get AFI using specific AFI ID.  Information is provided only if caller has access to AFI.
+```
+    $ aws ec2 describe-fpga-images --fpga-image-ids afi-06d0ffc989feeea2a
+```
+
+* Get multiple AFIs by AFI IDs
+```
+    $ aws ec2 describe-fpga-images --fpga-image-ids afi-06d0ffc989feeea2a afi-0f0927bc2649e6259
+```
+
+* Get AFIs owned by caller AWS account.  Exludes public AFIs and AFIs with load permissions.
+```
+    $ aws ec2 describe-fpga-images --owners self
+```
+
+* Get public AFIs owned by Amazon (this is the command use to retrive the example response)
+```
+    $ aws ec2 describe-fpga-images --owners amazon
+```
+
+* Get AFIs owned by AWS marketplace.
+```
+    $ aws ec2 describe-fpga-images --owners aws-marketplace
+```
+
+* Get AFIs using explicit AWS account ID.
+```
+    $ aws ec2 describe-fpga-images --owners 095707098027
+```
+
+### Use filters parameter
+
+* Get AFIs using various filters
+```
+    # Get AFI by name
+    $ aws ec2 describe-fpga-images --filters "Name=name,Values=cl_dram_dma_0415"
+
+    # Get AFIs in 'available' state
+    $ aws ec2 describe-fpga-images --filters "Name=state,Values=available"
+
+    # Get AFIs with shell version 0x04151701
+    $ aws ec2 describe-fpga-images --filters "Name=shell-version,Values=0x04151701"
+
+    # Get AFI created at a specific time
+    $ aws ec2 describe-fpga-images --filters "Name=create-time,Values=2017-04-17T15:58:54.000Z"
+```
+
+* Get AFIs using wildcard filters (wildcards only usable in `filters` parameter)
+```
+    # Get AFIs created on 2017-04-17
+    $ aws ec2 describe-fpga-images --filters "Name=create-time,Values=2017-04-17*"
+
+    # Get AFIs if name starts with 'cl_'
+    $ aws ec2 describe-fpga-images --filters "Name=name,Values=cl_*"
+
+    # Get AFIs with multiple wildcards
+    $ aws ec2 describe-fpga-images --filters "Name=name,Values=*_world_*"
+```
+
+
+### Combine filters to find groups of AFIs
+
+* Get all failed AFIs owned by caller AWS account
+```
+    $ aws ec2 describe-fpga-images --owners self --filters "Name=state,Values=failed"
+```
+
+* Multiple filter values are evaluated as `OR` conditions
+```
+    # Get both example AFIs by name
+    $ aws ec2 describe-fpga-images --filters "Name=name,Values=cl_dram_dma_0415,cl_hellow_world_04151701"
+
+    # Get AFIs created on 2017-04-17 or 2017-04-19
+    $ aws ec2 describe-fpga-images --filters "Name=create-time,Values=2017-04-17*,2017-04-19*"
+```
+
+* Multiple filters are evaluated as `AND` conditions
+```
+    # Get AFIs by name AND created on 2017-04-17
+    $ aws ec2 describe-fpga-images --filters "Name=name,Values=cl_dram_dma_0415,cl_hellow_world_04151701" "Name=create-time,Values=2017-04-17*"
+
+    # Same filter can be use multiple times, which can return an empty set
+    $ aws ec2 describe-fpga-images --filters "Name=name,Values=cl_dram_dma_0415" "Name=name,Values=cl_hellow_world_04151701"
+```
+
+## Common Error Messages
+
+
+* Invalid owner ID or filter alias
+```
+    $ aws ec2 describe-fpga-images --owners 12345
+
+    An error occurred (InvalidUserID.Malformed) when calling the DescribeFpgaImages operation: User ID '12345' is invalid
+```
+
+* Invalid AFI ID
+```
+    $ aws ec2 describe-fpga-images --fpga-image-ids afi-06d0ffc989feeeXXX
+
+    An error occurred (InvalidFpgaImageID.Malformed) when calling the DescribeFpgaImages operation: Image ID 'afi-06d0ffc989feeeXXX' is invalid
+```
+
+* AFI ID not found
+```
+    $ aws ec2 describe-fpga-images --fpga-image-ids afi-03d027a3318440a77
+
+    An error occurred (InvalidFpgaImageID.NotFound) when calling the DescribeFpgaImages operation: Image ID 'afi-03d027a3318440a77' not found
+```
+
+* Invalid filter name
+```
+    $ aws ec2 describe-fpga-images --filters "Name=bad-filter,Values=value"
+
+    An error occurred (InvalidParameterValue) when calling the DescribeFpgaImages operation: The filter 'bad-filter' is invalid
+```

hdk/hdk_version.txt

@@ -1 +1 @@
-HDK_VERSION=1.2.3
+HDK_VERSION=1.2.4