rc v2.1.0 (#715)

Author: mjthimm

.gitmodules

@@ -2,3 +2,7 @@
     path = vitis/examples/Vitis_Accel_Examples
     url = https://github.com/Xilinx/Vitis_Accel_Examples.git
     branch = 2024.1
+[submodule "hdk/common/ip"]
+    path = hdk/common/ip
+    url = https://github.com/aws/aws-fpga-resources.git
+    ignore = dirty

ERRATA.md

@@ -42,10 +42,34 @@ Shell errata is [documented here](./hdk/docs/AWS_Shell_ERRATA.md)
 
 ## SDK
 
+1. The following fpga_mgmt flags are not supported for F2:
+   * `FPGA_CMD_FORCE_SHELL_RELOAD`
+   * `FPGA_CMD_DRAM_DATA_RETENTION`
+   * `FPGA_CMD_EXTENDED_METRICS_SIZE`
+
+   These flags will cause a run-time error if passed to:
+   * `fpga_mgmt_describe_local_image`
+   * `fpga_mgmt_load_local_image_flags`
+   * `fpga_mgmt_load_local_image_with_options`
+   * `fpga_mgmt_load_local_image_sync_flags`
+   * `fpga_mgmt_load_local_image_sync_with_options`
+
+   If your application passes these flags, you have two options:
+   1. Edit your application to no longer pass these flags
+   2. If your application links against `libfpga_mgmt.so`, you can uncomment the following line from the `Makefile` in the `<SDK>/userspace/fpga_libs/fpga_mgmt` directory:
+
+   ```makefile
+   #IGNORE_DEPRECATION=-DUNSUPPORTED_OPTIONS_ACKNOWLEDGED
+   ```
+
+   After editing the Makefile, run `source sdk_setup.sh` in the root of this repository. Rebuild your application as normal and the options will be ignored. Alternatively, passing `-DUNSUPPORTED_OPTIONS_ACKNOWLEDGED` to the compiler when compiling the `fpga_mgmt.c` source file will also ignore the options.
+
+2. The `-F` flag is not supported when passed to the `fpga-load-local-image` CLI. The CLI will not error, but it will print a message indicating that the option is not supported and will be ignored.
+
 ## Software defined Accelerator Development (Vitis)
 
-1. Only hardware emulation via Vitis 2024.1 is currently supported.
+1. Only hardware emulation via Vitis 2024.1 and 2024.2 is currently supported.
 
-2. Support for Vitis 2024.1 accelerator binary creation and AFI creation is not supported, but will be released at a later time.
+2. Support for Vitis 2024.1 and 2024.2 accelerator binary creation and AFI creation is not supported, but will be released at a later time.
 
 3. Support for Vitis software emulation has been deprecated by AMD, therefore, no longer supported.

RELEASE_NOTES.md

@@ -1,5 +1,11 @@
 # F2 Developer Kit Release Notes
 
+## v2.1.0
+
+* Support for Vivado and Vitis 2024.2 tools.
+* [Releasing New Developer AMI for 2024.2 tools.](http://aws.amazon.com/marketplace/pp/prodview-tcl7sjgreh6bq)
+* Updating the asynchronous fpga_mgmt_examples to poll each FPGA once before moving to the next.
+
 ## v2.0.7
 
 * Documentation updates to improve [ReadTheDocs](https://awsdocs-fpga-f2.readthedocs-hosted.com/latest/) navigation and inline snippets.

User_Guide_AWS_EC2_FPGA_Development_Kit.md

@@ -14,7 +14,6 @@ The development kit includes example designs to get you familiar with developing
     - [Hardware Development Kit (HDK)](#hardware-development-kit-hdk)
     - [Software-Defined Development Environment](#software-defined-development-environment)
     - [FPGA Developer AMI](#fpga-developer-ami)
-  - [Getting Started](#getting-started)
     - [Getting Familiar with AWS](#getting-familiar-with-aws)
   - [Next Steps](#next-steps)
 
@@ -47,7 +46,7 @@ This table lists the F2 development flows currently enabled and supported in the
 | Hardware accelerator development using Vivado (HDK) | This environment supports the Hardware Development Kit (HDK) design flow, which empowers FPGA developers to create accelerator designs from scratch, using HDL source code and IPs. <br><br>The AMD Vivado tool synthesizes, implements, and generates the Design Check Point (DCP) file used in F2 AFI creation. AWS FPGA developers benefit from the suite of scripts supplied in the HDK that help to automate different design steps. This allows for flexibility in architecting, implementing, and optimizing accelerator designs while using the HDK.| Verilog/SystemVerilog/VHDL | User-implemented DMA engine or Streaming Data Engine (SDE) | Simulation | Hardware developers with advanced FPGA experience |
 | Hardware accelerator development using Vitis | This environment supports the Vitis design flow, which enables software developers to write C++ code, which may then be compiled into RTL and used in cycle-accurate hardware simulation. After it may then be built into an accelerator design. This step is not necessary, but is encouraged. Vitis may also be used to implement accelerator designs from scratch, using HDL and IPs directly, similar to Vivado. Vitis offers additional analysis tools to aid in the refinement of designs. | Verilog/System Verilog/VHDL | XDMA Engine (coming soon) | Hardware Emulation | Advanced software developers or hardware developers with intermediate to advanced FPGA experience |
 
-On-premise environment: Customers can set up a on-premise development environment using 2024.1 AMD tools with their own licenses. Refer to this guide [here](./hdk/docs/on_premise_licensing_help.md) for licensing requirements.
+On-premise environment: Customers can set up a on-premise development environment. See the [supported AMD tool versions here.](#hardware-development-kit-hdk) Refer to this guide [here](./hdk/docs/on_premise_licensing_help.md) for licensing requirements.
 
 ### Quick Start Links
 
@@ -154,11 +153,10 @@ The [HDK directory structure](./hdk/README.md) contains:
 
 The HDK currently supports the following tool versions:
 
-| Tool                                    | Version       |
-|:----------------------------------------|:--------------|
-|AMD Vivado Design Suite                  | 2024.1        |
-|Synopsys VCS  (Bring your own license)   | U-2023.03-SP2 |
-|Siemens Questa (Bring your own license)  | 2023.3        |
+| AMD Vivado Design Suite | Synopsys VCS  (Bring your own license) | Siemens Questa (Bring your own license) |
+|:------------------------|:---------------------------------------|:----------------------------------------|
+| 2024.2                  | V-2023.12-SP1                          | 2024.1_2                                |
+| 2024.1                  | U-2023.03-SP2                          | 2023.3                                  |
 
 Our scripts require a minimum Python version of 3.10, under `/usr/bin/env python3`:
 
@@ -181,14 +179,13 @@ A free-to-use FPGA developer AMI is available for on-cloud F2 development with A
 
 | FPGA Developer AMI Version | FPGA Developer AMI ID | Vivado/Vitis Version Supported | Operating System Version    |
 |----------------------------|-----------------------|--------------------------------|-----------------------------|
+| 1.17.0                     | [ami-01198b89d80ebfdd2](https://aws.amazon.com/marketplace/pp/prodview-tcl7sjgreh6bq) | 2024.2 | Ubuntu 24.04 (kernel 6.8.0-1021-aws)|
 | 1.16.1                     | [ami-092fc5deb8f3c0f7d](https://aws.amazon.com/marketplace/pp/prodview-f5kjsenkfkz5u) | 2024.1 | Ubuntu 20.04.6 (kernel 5.15)|
 
 Given the large size of the FPGA used for F2, AMD tools work best with at least 4 vCPU’s and 32GiB Memory. We recommend [Compute Optimized and Memory Optimized instance types](https://aws.amazon.com/ec2/instance-types/) to successfully run the synthesis of acceleration code. Developers may start coding and run simulations on low-cost `General Purpose` [instances types](https://aws.amazon.com/ec2/instance-types/).
 
 Note that the tools used by the HDK are only supported on x86-based EC2 instances (Graviton-based instances are not compatible with the tools).
 
-## Getting Started
-
 ### Getting Familiar with AWS
 
 If you have never used AWS before, we recommend you start with [AWS getting started training](https://aws.amazon.com/getting-started/), focusing on the basics of the [AWS EC2](https://aws.amazon.com/ec2/) and [AWS S3](https://aws.amazon.com/s3/) services. Understanding the fundamentals of these services will further enhance the developer experience with AWS F2 instances and the FPGA Developer Kit.

docs-rtd/requirements.txt

@@ -2,7 +2,7 @@ sphinx>=6.1.0,<9.0.0
 sphinx_book_theme>=1.1.3,<2.0.0
 sphinx-sitemap==2.6.0
 
-sphinxcontrib-spelling==8.0.1
+sphinxcontrib-spelling==7.7.0
 pyenchant==3.2.2
 docutils>=0.18,<0.21
 

docs-rtd/source/ERRATA.rst

@@ -71,14 +71,42 @@ HDK
 SDK
 ---
 
-* N/A
+.. role:: raw-html(raw)
+    :format: html
+
+1. The following fpga_mgmt flags are not supported for F2:
+
+   - ``FPGA_CMD_FORCE_SHELL_RELOAD``
+   - ``FPGA_CMD_DRAM_DATA_RETENTION``
+   - ``FPGA_CMD_EXTENDED_METRICS_SIZE``
+
+   These flags will cause a run-time error if passed to:
+
+   - ``fpga_mgmt_describe_local_image``
+   - ``fpga_mgmt_load_local_image_flags``
+   - ``fpga_mgmt_load_local_image_with_options``
+   - ``fpga_mgmt_load_local_image_sync_flags``
+   - ``fpga_mgmt_load_local_image_sync_with_options``
+
+   If your application passes these flags, you have two options:
+
+   1. Edit your application to no longer pass these flags
+
+   2. If your application links against ``libfpga_mgmt.so``, you can uncomment the following line from the ``Makefile`` in the ``<SDK>/userspace/fpga_libs/fpga_mgmt`` directory:
+
+      :raw-html:`<br />`
+      ``#IGNORE_DEPRECATION=-DUNSUPPORTED_OPTIONS_ACKNOWLEDGED``
+
+      After editing the Makefile, run ``source sdk_setup.sh`` in the root of this repository. Rebuild your application as normal and the options will be ignored. Alternatively, passing ``-DUNSUPPORTED_OPTIONS_ACKNOWLEDGED`` to the compiler when compiling the ``fpga_mgmt.c`` source file will also ignore the options.
+
+2. The ``-F`` flag is not supported when passed to the ``fpga-load-local-image`` CLI. The CLI will not error, but it will print a message indicating that the option is not supported and will be ignored.
 
 Software defined Accelerator Development (Vitis)
 ------------------------------------------------
 
-1. Only hardware emulation via Vitis 2024.1 is currently supported.
+1. Only hardware emulation via Vitis 2024.1 and 2024.2 is currently supported.
 
-2. Support for Vitis 2024.1 accelerator binary creation and AFI creation is not supported, but will be released at a later time.
+2. Support for Vitis 2024.1 and 2024.2 accelerator binary creation and AFI creation is not supported, but will be released at a later time.
 
 3. Support for Vitis software emulation has been deprecated by AMD, therefore, no longer supported.
 

docs-rtd/source/RELEASE-NOTES.rst

@@ -1,6 +1,14 @@
 F2 Developer Kit Release Notes
 ==============================
 
+.. _v210:
+
+v2.1.0
+------
+
+- Support for Vivado and Vitis 2024.2 tools.
+- `Releasing New Developer AMI for 2024.2 tools. <http://aws.amazon.com/marketplace/pp/prodview-tcl7sjgreh6bq>`__
+- Updating the asynchronous fpga_mgmt_examples to poll each FPGA once before moving to the next.
 
 .. _v207:
 

docs-rtd/source/User-Guide-AWS-EC2-FPGA-Development-Kit.rst

@@ -4,32 +4,28 @@
 The development kit includes example designs to get you familiar with
 developing for AWS EC2 FPGA Instances.
 
-- `AWS EC2 FPGA Development Kit <#aws-ec2-fpga-development-kit>`__
+- `AWS EC2 F2 Instance Overview <#aws-ec2-f2-instance-overview>`__
 
-  - `AWS EC2 F2 Instance Overview <#aws-ec2-f2-instance-overview>`__
+  - `Instance Types <#instance-types>`__
+  - `Second Generation On-Cloud FPGA Accelerator
+    Card <#second-generation-on-cloud-fpga-accelerator-card>`__
+  - `Comparison to F1 <#comparison-to-f1>`__
 
-    - `Instance Types <#instance-types>`__
-    - `2nd Generation On-Cloud FPGA Accelerator
-      Card <#second-generation-on-cloud-fpga-accelerator-card>`__
-    - `Comparison to F1 <#comparison-to-f1>`__
+- `AWS EC2 F2 FPGA Development
+  Kit <#aws-ec2-f2-fpga-development-kit>`__
 
-  - `AWS EC2 F2 FPGA Development
-    Kit <#aws-ec2-f2-fpga-development-kit>`__
+  - `Development Environments <#development-environments>`__
+  - `Quick Start Links <#quick-start-links>`__
+  - `AWS Shells <#aws-shells>`__
+  - `Hardware Development Kit (HDK) <#hardware-development-kit-hdk>`__
+  - `Software-Defined Development
+    Environment <#software-defined-development-environment>`__
 
-    - `Development Environments <#development-environments>`__
-    - `Quick Start Links <#quick-start-links>`__
-    - `AWS Shells <#aws-shells>`__
-    - `Hardware Development Kit (HDK) <#hardware-development-kit-hdk>`__
-    - `Software-Defined Development
-      Environment <#software-defined-development-environment>`__
+  - `FPGA Developer AMI <#fpga-developer-ami>`__
 
-    - `FPGA Developer AMI <#fpga-developer-ami>`__
+  - `Getting Familiar with AWS <#getting-familiar-with-aws>`__
 
-  - `Getting Started <#getting-started>`__
-
-    - `Getting Familiar with AWS <#getting-familiar-with-aws>`__
-
-  - `Next Steps <#next-steps>`__
+- `Next Steps <#next-steps>`__
 
 .. _aws-ec2-f2-instance-overview:
 
@@ -65,8 +61,8 @@ Instance Types
 
 .. _second-generation-on-cloud-fpga-accelerator-card:
 
-2nd Generation On-Cloud FPGA Accelerator Card
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Second-Generation On-Cloud FPGA Accelerator Card
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 |image1|
 
@@ -130,7 +126,7 @@ supported in the development kit.
       with intermediate to advanced FPGA experiences
 
 On-premise environment: Customers can set up a on-premise development
-environment using 2024.1 AMD tools with their own licenses. Refer to
+environment. See the `supported AMD tool versions here. <#hardware-development-kit-hdk>`__ Refer to
 this guide `here <./hdk/docs/on-premise-licensing-help.html>`__ for
 licensing requirements.
 
@@ -294,15 +290,16 @@ The HDK currently supports the following tool versions:
 .. list-table::
   :header-rows: 1
   :class: user-guide-simulators-table
-  :widths: 50 30
+  :widths: 30 30 30
 
-  * - Tool
-    - Version
   * - AMD Vivado Design Suite
-    - 2024.1
-  * - Synopsys VCS (Bring your own license)
+    - Synopsys VCS (Bring your own license)
+    - Siemens Questa (Bring your own license)
+  * - 2024.2
+    - V-2023.12-SP1
+    - 2024.1_2
+  * - 2024.1
     - U-2023.03-SP2
-  * - Siemens Questa (Bring your own license)
     - 2023.3
 
 Our scripts require a minimum Python version of 3.10, under
@@ -357,6 +354,10 @@ currently released to customers:
     - FPGA Developer AMI ID
     - Vivado/Vitis Version Supported
     - Operating System Version
+  * - 1.17.0
+    - `ami-01198b89d80ebfdd2 <https://aws.amazon.com/marketplace/pp/prodview-tcl7sjgreh6bq>`__
+    - 2024.2
+    - Ubuntu 24.04 (kernel 6.8.0-1021-aws)
   * - 1.16.1
     - `ami-092fc5deb8f3c0f7d <https://aws.amazon.com/marketplace/pp/prodview-f5kjsenkfkz5u>`__
     - 2024.1
@@ -373,11 +374,6 @@ types <https://aws.amazon.com/ec2/instance-types/#General_Purpose>`__.
 Note that the tools used by the HDK are only supported on x86-based EC2
 instances (Graviton-based instances are not compatible with the tools).
 
-.. _getting-started:
-
-Getting Started
----------------
-
 .. _getting-familiar-with-aws:
 
 Getting Familiar with AWS

docs-rtd/source/hdk/README.rst

@@ -9,7 +9,7 @@ Table of Contents
 
   - `Table of Contents <#table-of-contents>`__
   - `HDK Overview <#hdk-overview>`__
-  - `Getting Started <#getting-started>`__
+  - `Getting Started <#getting-started-hdk>`__
 
     - `Build Accelerator AFI using HDK Design
       Flow <#build-accelerator-afi-using-hdk-design-flow>`__

docs-rtd/source/hdk/cl/examples/CL-TEMPLATE/README.rst

@@ -10,9 +10,9 @@ Table of Content
   - `Design <#design>`__
   - `Verification <#verification>`__
   - `Software <#software>`__
-  - `Build <#Build>`__
+  - `Build <#build-cl-template>`__
 
-- `CL Template Quick Start Guide <#cl_template-quick-start-guide>`__
+- `CL Template Quick Start Guide <#cl-template-quick-start-guide>`__
 
 Overview
 --------
@@ -135,6 +135,8 @@ CL_TEMPLATE does not yet support stand alone software tests. Please
 refer to other examples such as
 `CL_DRAM_HBM_DMA <https://github.com/aws/aws-fpga/tree/f2/hdk/cl/examples/cl_dram_hbm_dma/software>`__
 
+.. _build-cl-template:
+
 Build
 ~~~~~
 
@@ -199,6 +201,8 @@ For more information on how to populate the constraint files and build
 scripts, please refer to other examples such as
 `CL_DRAM_HBM_DMA <https://github.com/aws/aws-fpga/tree/f2/hdk/cl/examples/cl_dram_hbm_dma/build>`__.
 
+.. _cl-template-quick-start-guide:
+
 CL_TEMPLATE Quick Start Guide
 -----------------------------
 

docs-rtd/source/hdk/cl/examples/cl-dram-hbm-dma/README.rst

@@ -83,15 +83,15 @@ DDR and HBM. So, if a particular memory is disabled, then the developer
 should take care to handle transactions to that address range since
 there will be no controller to respond to the request. The address
 ranges for each controller is described below in the `dma_pcis AXI4 bus
-section <#dma_pcis>`__.
+section <#dma-pcis>`__.
 
 Test Changes
 ------------
 
 If a particular controller is disabled, make sure that the test is not
 accessing address space for that controller.
 
-Please look at `dma_pcis AXI4 bus section <#dma_pcis>`__ for address
+Please look at `dma_pcis AXI4 bus section <#dma-pcis>`__ for address
 ranges.
 
 If DDR is enabled, make sure that the DDRs are initialized using the
@@ -106,6 +106,8 @@ eg: To initialize DDR
 Make sure that the Host to Card and Card to Host DMA transfers only
 access enabled DDR controller address space.
 
+.. _dma-pcis:
+
 dma_pcis AXI4 bus
 -----------------