Merge pull request #742 from aws/rc/2.2.0

Release v2.2.0 - Vivado/Vitis 2025.1 Support

Author: mjthimm

.gitmodules

@@ -6,3 +6,4 @@
     path = hdk/common/ip
     url = https://github.com/aws/aws-fpga-resources.git
     ignore = dirty
+	branch = Vivado_2025.1-hdk/common/ip

ERRATA.md

@@ -7,7 +7,6 @@ Shell errata is [documented here](./hdk/docs/AWS_Shell_ERRATA.md)
 
 ## HDK
 
-
 1. Address Aliasing Bug in AMD HBM IP with Customer Address Mapping
 
    * An address aliasing bug has been identified in AMD HBM IP when the IP's "Customer Address Map" option is enabled for a 16GB HBM implementation. The bug allows a single memory entry to be accessed via two different addresses, which might lead to data corruption. More information about this bug will be published by AMD in the Ultrascale+ product errata.
@@ -39,6 +38,8 @@ Shell errata is [documented here](./hdk/docs/AWS_Shell_ERRATA.md)
 
 8. HBM simulation using XSIM requires a fix described in this [AMD Answer Record](https://adaptivesupport.amd.com/s/article/000035639?language=en_US).
 
+9. Vivado 2025.1 introduces a `set_property DONT_TOUCH` to the HBM model that makes meeting
+timing difficult in the implementation stage. AMD has responded to this issue on their AR, stating that it will be fixed in a future version of Vivado. [See here for more details](https://adaptivesupport.amd.com/s/article/000038502?language=en_US&t=1754923887312). All HDK CL examples have been updated to address this issue. Customers should follow this AR when creating their own designs.
 
 ## SDK
 

README.md

@@ -3,19 +3,15 @@
 
 # AWS F2
 
-## F2 FPGA Development Kit Overview
-
-The documentation and assets provided on this branch (and other branches prefixed with `f2`) are relevant to F2 instances only.
-
-The F2 FPGA Development Kit is a hardware-software development kit that enables developers to create accelerators for the high-performance accelerator cards on EC2 F2 instances. Using the development kit, you can architect, simulate, optimize, and test your designs.
+## F2 FPGA Developer Kit Documentation on ReadTheDocs
 
-## F2 FPGA Development Kit Documentation
+The documentation for the F2 FPGA Developer Kit including our User Guide, tutorials, code snippets, and more can now be found on [our ReadTheDocs webstie](https://awsdocs-fpga-f2.readthedocs-hosted.com).
 
-For full documentation, including a user guide, code snippets, and tutorials, see the [AWS EC2 FPGA Development Kit User Guide](./User_Guide_AWS_EC2_FPGA_Development_Kit.md)
+**Please note that the documentation and assets provided on this branch and others prefixed with `f2` are relevant to F2 instances only!**
 
-## F2 FPGA ReadTheDocs (Beta)
+## F2 FPGA Development Kit Overview
 
-We are currently migrating our F2 documentation to comply with the ReadTheDocs standard. To familiarize yourself with the new layout, please [click here](https://awsdocs-fpga-f2.readthedocs-hosted.com).
+The F2 FPGA Development Kit is a hardware-software development kit that enables developers to create accelerators for the high-performance accelerator cards on EC2 F2 instances. Using the development kit, you can architect, simulate, optimize, and test your designs.
 
 # ❗Amazon EC2 F1 End of Life Notice❗
 
@@ -32,4 +28,4 @@ Only existing F1 customers who have run F1 instances anytime between Dec 2023 -
 
 For any issues with this developer kit documentation or code, please open a [GitHub issue](https://github.com/aws/aws-fpga/issues) with all steps to reproduce.
 
-For questions, please open a [re:Post issue with the 'FPGA Development' tag](https://repost.aws/tags/TAc7ofO5tbQRO57aX1lBYbjA/fpga-development).
+For questions, please open a [re:Post issue with the 'FPGA Development' tag](https://repost.aws/tags/TAc7ofO5tbQRO57aX1lBYbjA/fpga-development).

RELEASE_NOTES.md

@@ -1,5 +1,12 @@
 # F2 Developer Kit Release Notes
 
+## v2.2.0
+
+* Release of Vivado/Vitis 2025.1 Tools on [FPGA Developer AMI 1.18.0 (Ubuntu)](http://aws.amazon.com/marketplace/pp/prodview-tcl7sjgreh6bq)
+* Introduced [MSI-X PCIe Interrupts Guided Example](./sdk/apps/msix-interrupts/README.md)
+* Added [Loopback performance test for CL_SDE](./hdk/cl/examples/cl_sde/software/src/README.md)
+* [ReadTheDocs navigation improvements](https://awsdocs-fpga-f2.readthedocs-hosted.com/latest/)
+
 ## v2.1.2
 
 * Introduced Python Bindings to the SDK

User_Guide_AWS_EC2_FPGA_Development_Kit.md

@@ -155,6 +155,7 @@ The HDK currently supports the following tool versions:
 
 | AMD Vivado Design Suite | Synopsys VCS  (Bring your own license) | Siemens Questa (Bring your own license) |
 |:------------------------|:---------------------------------------|:----------------------------------------|
+| 2025.1                  | W-2024.09-SP1                          | 2024.3_3                                |
 | 2024.2                  | V-2023.12-SP1                          | 2024.1_2                                |
 | 2024.1                  | U-2023.03-SP2                          | 2023.3                                  |
 
@@ -179,7 +180,7 @@ 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.18.0                     | [ami-098b2ed4c92602975](http://aws.amazon.com/marketplace/pp/prodview-tcl7sjgreh6bq) | 2025.1 | 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/).

docs-rtd/requirements.txt

@@ -9,4 +9,5 @@ docutils>=0.18,<0.21
 sphinx-copybutton>=0.5.2
 
 termcolor==2.5.0
-requests==2.32.3
+requests<3.0.0
+

docs-rtd/source/ERRATA.rst

@@ -68,6 +68,11 @@ HDK
 8. HBM simulation using XSIM requires a fix described in this
    `AMD Answer Record <https://adaptivesupport.amd.com/s/article/000035639?language=en_US>`__.
 
+9. Vivado 2025.1 introduces a ``set_property DONT_TOUCH`` to the HBM model that makes meeting
+   timing difficult in the implementation stage. AMD has responded to this issue on their AR, stating that it will be fixed in a future version of Vivado.
+   `See here for more details <https://adaptivesupport.amd.com/s/article/000038502?language=en_US&t=1754923887312>`__.
+   All HDK CL examples have been updated to address this issue. Customers should follow this AR when creating their own designs.
+
 SDK
 ---
 

docs-rtd/source/RELEASE-NOTES.rst

@@ -1,14 +1,24 @@
 F2 Developer Kit Release Notes
 ==============================
 
+.. _v220:
+
+v2.2.0
+------
+
+- Release of Vivado/Vitis 2025.1 Tools on `FPGA Developer AMI 1.18.0 (Ubuntu) <http://aws.amazon.com/marketplace/pp/prodview-tcl7sjgreh6bq>`__
+- Introduced `MSI-X PCIe Interrupts Guided Example <./sdk/apps/msix-interrupts/README.html>`__
+- Added `Loopback performance test for CL_SDE <./hdk/cl/examples/cl-sde/software/src/README.html>`__
+- `ReadTheDocs navigation improvements <https://awsdocs-fpga-f2.readthedocs-hosted.com/latest/>`__
+
 .. _v212:
 
 v2.1.2
 ------
 
 - Introduced Python Bindings to the SDK
-- Added `documentation <./sdk/userspace/cython-bindings/README.html>` for Python binding usage and setup
-- `Examples <https://github.com/aws/aws-fpga/blob/f2/sdk/userspace/cython_bindings>` demonstrating Python-based FPGA control
+- Added `documentation <./sdk/userspace/cython-bindings/README.html>`__ for Python binding usage and setup
+- `Examples <https://github.com/aws/aws-fpga/blob/f2/sdk/userspace/cython_bindings>`__ demonstrating Python-based FPGA control
 - Added link to instructions for DCV licensing setup. Credit to @morgnza for this update!
 - Added verbiage to DCV setup guide to show where to set virtual display resolution
 - Fix to Bandwidth Calculation
@@ -20,7 +30,7 @@ v2.1.1
 
 - Added global register offset for the SDE IP. See `CL_SDE software examples <./hdk/cl/examples/cl-sde/software/src/README.html>`__.
 - Added `CL_SDE software exmaple <https://github.com/aws/aws-fpga/blob/f2/hdk/cl/examples/cl_sde/software/src/sde_c2h_user_buffers.c>`__ for a user allocated DMA buffer.
-- `Documentation <./hdk/docs/List-AFI-on-Marketplace.html>`__` to assist F2 customers with releasing AFIs and AMIs on the AWS Marketplace.
+- `Documentation <./hdk/docs/List-AFI-on-Marketplace.html>`__ to assist F2 customers with releasing AFIs and AMIs on the AWS Marketplace.
 - `Documentation <./developer-resources/Amazon-DCV-Setup-Guide.html>`__ to assist in creating a virtual desktop based on the FPGA Developer AMI running graphics-intensive applications remotely on Amazon EC2 instances.
 - Fixed the BW calculation and tolerance calculation in the test_hbm_perf_random in the `cl_mem_perf <./hdk/cl/examples/cl-mem-perf/verif/README.html#test-hbm-perf-randomsv-mem>`__.
 

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

@@ -295,6 +295,9 @@ The HDK currently supports the following tool versions:
   * - AMD Vivado Design Suite
     - Synopsys VCS (Bring your own license)
     - Siemens Questa (Bring your own license)
+  * - 2025.1
+    - W-2024.09-SP1
+    - 2024.3_3
   * - 2024.2
     - V-2023.12-SP1
     - 2024.1_2
@@ -354,9 +357,9 @@ 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
+  * - 1.18.0
+    - `ami-098b2ed4c92602975 <http://aws.amazon.com/marketplace/pp/prodview-tcl7sjgreh6bq>`__
+    - 2025.1
     - Ubuntu 24.04 (kernel 6.8.0-1021-aws)
   * - 1.16.1
     - `ami-092fc5deb8f3c0f7d <https://aws.amazon.com/marketplace/pp/prodview-f5kjsenkfkz5u>`__

docs-rtd/source/hdk/cl/examples/cl-sde/software/src/README.rst

@@ -147,10 +147,10 @@ Example Usage
 Examples
 --------
 
-Build the sde_examples from the
-$(HDK)/cl/examples/cl_sde/software/runtime directory.
-
-``make sde_examples``
+Build the sde_examples by navigating to the ${HDK_DIR}/cl/examples/cl_sde/software/runtime
+directory and running ``make sde_examples``. Prior to building the examples, this target
+will build and install the libsde.so shared object. These targets also serve as an example
+for building against the libsde.so shared object.
 
 .. _1-card-to-host-c2h-simple-transfer:
 
@@ -161,6 +161,8 @@ $(HDK)/cl/examples/cl_sde/software/runtime directory.
 - Demonstrates basic card-to-host data transfer
 - Configures SDE for reading data into a user-allocated buffer
 
+.. _usage-1:
+
 Usage
 ^^^^^
 
@@ -176,7 +178,7 @@ Usage
 - Demonstrates basic host-to-card data transfer
 - Writes data from a user-allocated buffer to the SDE
 
-.. _usage-1:
+.. _usage-2:
 
 Usage
 ^^^^^
@@ -193,7 +195,7 @@ Usage
 - Demonstrates bidirectional data transfer
 - Writes data to SDE and reads it back
 
-.. _usage-2:
+.. _usage-3:
 
 Usage
 ^^^^^
@@ -211,7 +213,7 @@ Usage
 - Tests high-throughput data transfer
 - Choose large packet sizes for better performance
 
-.. _usage-3:
+.. _usage-4:
 
 Usage
 ^^^^^
@@ -228,14 +230,46 @@ Usage
 - Measures maximum performance for host-to-card transfers
 - Tests high-throughput data transfer
 
-.. _usage-4:
+.. _usage-5:
 
 Usage
 ^^^^^
 
 ``sudo ./sde_h2c_perf_test <num_millions_packets> <packet_size> <slot_id>``
 ``sudo ./sde_h2c_perf_test 1 131072 0``
 
+.. _6-card-to-host-transfer-with-user-managed-buffers:
+
+6. Card-to-Host Transfer with User Managed Buffers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- File: ``sde_c2h_user_buffers``
+- Demonstrates basic card-to-host data transfer with user managed buffers
+- Configures SDE for reading data into a user-managed DMA buffer
+
+.. _usage-6:
+
+Usage
+
+``sudo ./sde_c2h_user_buffers <num_packets> <packet_size> <slot_id>``
+``sudo ./sde_c2h_user_buffers 1 4096 0``
+
+.. _7-loopback-performance-test:
+
+7. Loopback Performance Test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- File: ``sde_loopback_perf_test``
+- Tests bidirectional high-throughput data transfer
+- Choose large packet sizes for better performance
+
+.. _usage-7:
+
+Usage
+
+``sudo ./sde_loopback_perf_test <num_millions_packets> <packet_size> <slot_id>``
+``sudo ./sde_loopback_perf_test 1 131072 0``
+
 Performance Metrics
 -------------------