aws · mjthimm · Oct 7, 2025 · Oct 2, 2025 · Oct 2, 2025 · Oct 3, 2025
diff --git a/.gitignore b/.gitignore
@@ -39,6 +39,7 @@ fpga_utils.c
 *.a
 *.ko
 fio
+.coverage
 
 !SDAccel/aws_platform/xilinx_aws-vu9p-f1_1ddr-xpr-2pr_4_0/sw/lib/x86_64/libxilinxopencl.so
 !SDAccel/aws_platform/xilinx_aws-vu9p-f1_4ddr-xpr-2pr_4_0/sw/lib/x86_64/libxilinxopencl.so
@@ -139,3 +140,8 @@ slurm*.out
 
 # RTD Builds
 docs-rtd/build/*
+
+# HLx files
+*.tmp
+**/example_projects/
+*.pb
diff --git a/.gitmodules b/.gitmodules
@@ -6,4 +6,7 @@
     path = hdk/common/ip
     url = https://github.com/aws/aws-fpga-resources.git
     ignore = dirty
-	branch = Vivado_2025.1-hdk/common/ip
+[submodule "hdk/common/shell_stable/hlx"]
+    path = hdk/common/shell_stable/hlx
+    url = https://github.com/aws/aws-fpga-resources.git
+    ignore = dirty
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -1,13 +1,40 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-24.04
   tools:
-    python: "3.10"
+    python: "3.12"
+    nodejs: "22"
+    rust: "1.82"
+    golang: "1.23"
+
 
 python:
   install:
     - requirements: docs-rtd/requirements.txt
 
 sphinx:
   configuration: docs-rtd/source/conf.py
+  builder: html
+  fail_on_warning: true
+
+search:
+  ranking:
+    index.html: 10
+    all-links.html: 7
+    User-Guide-AWS-EC2-FPGA-Development-Kit.html: 9
+    hdk/README.html: 9
+    hdk/cl/CHECKLIST-BEFORE-BUILDING-CL.html: 8
+    hdk/cl/examples/cl-dram-hbm-dma/README.html: 8
+    hdk/cl/examples/cl-mem-perf/README.html: 8
+    hdk/cl/examples/cl-sde/README.html: 8
+    hdk/cl/examples/CL-TEMPLATE/README.html: 8
+    hdk/docs/AWS-CLI-FPGA-Commands.html: 8
+    hdk/docs/AWS-Shell-Interface-Specification.html: 8
+    hdk/docs/List-AFI-on-Marketplace.html: 8
+    sdk/README.html: 9
+    sdk/apps/msix-interrupts/README.html: 8
+    sdk/apps/virtual-ethernet/README.html: 8
+    sdk/docs/F2-Software-Performance-Optimization-Guide.html: 8
+    vitis/README.html: 9
+    developer-resources/Amazon-DCV-Setup-Guide.html: 8
diff --git a/ERRATA.md b/ERRATA.md
@@ -41,6 +41,10 @@ Shell errata is [documented here](./hdk/docs/AWS_Shell_ERRATA.md)
 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.
 
+## HLx
+
+1. When executing the `aws::make_ipi` command in Vivado to set up the HLx IPI environment, the AWS IP instance may default to the name `f1_inst`. This is a known Vivado behavior and can be safely ignored. Users can rename this instance according to their preference.
+
 ## SDK
 
 1. The following fpga_mgmt flags are not supported for F2:
@@ -74,3 +78,7 @@ timing difficult in the implementation stage. AMD has responded to this issue on
 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.
+
+## Amazon DCV
+
+1. Amazon DCV does not support Rocky Linux 8.10 at this time.
diff --git a/Jenkinsfile b/Jenkinsfile
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 
-![f2_headline_graphic](./shared/assets/f2_headline_graphic.png)
+![f2_headline_graphic](./docs-rtd/source/_static/f2_headline_graphic.png)
 
 # AWS F2
 

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,5 +1,15 @@
 # F2 Developer Kit Release Notes
 
+## v2.2.1
+
+* [Release of FPGA Developer AMI 1.18.0 (Rocky Linux 8.10)](http://aws.amazon.com/marketplace/pp/prodview-7mukkbz7l2uvu) with Vivado/Vitis 2025.1 tools pre-installed
+* [Release of Vivado HLx flow](./User_Guide_AWS_EC2_FPGA_Development_Kit.md#development-environments)
+* Fixed TCL glob expression to properly read both .sv and .v files. Credit to @pyz-creeper and @dsw for this update!
+* Updated error codes in create-fpga-image for unsupported design logic
+* Updated the Virtual Ethernet Application to write the DMA buffer descriptors using the byte alignment required by the CL_SDE example, preventing data alignment errors on Rocky
+* [Added Amazon FPGA Image (AFI) creation Python script](./hdk/README.md#step-6-submit-generated-dcp-for-afi-creation)
+* Updated XRT version which includes stability fixes for Vitis
+
 ## 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)

diff --git a/User_Guide_AWS_EC2_FPGA_Development_Kit.md b/User_Guide_AWS_EC2_FPGA_Development_Kit.md
@@ -25,15 +25,15 @@ This documentation is relevant to F2 only. Therefore, it applies to all branches
 
 ### Instance Types
 
-![f2_instances](./shared/assets/instance_sizes_20250110.png)
+![f2_instances](./docs-rtd/source/_static/instance_sizes.png)
 
 ### 2nd Generation On-Cloud FPGA Accelerator Card
 
-![f2_instances](./shared/assets/accel_card_specs_20250110.png)
+![accel_card_specs](./docs-rtd/source/_static/accel_card_specs.png)
 
 ### Comparison to F1
 
-![f2_f1_comp](./shared/assets/f2_f1_comp_20250110.png)
+![f2_f1_comp](./docs-rtd/source/_static/f2_f1_comp.png)
 
 ## AWS EC2 F2 FPGA Development Kit
 
@@ -43,10 +43,11 @@ This table lists the F2 development flows currently enabled and supported in the
 
 | Development Environment | Description | Accelerator Language | Hardware Interface | Debug Options | Typical Developer |
 | ------------------------|-------------|----------------------|--------------------|---------------|-------------------|
-| 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 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, Virtual JTAG | 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 |
+| Hardware accelerator development using Vivado IP Integrator (IPI) and High Level Design (HLx) | This environment supports the Vivado high-level design flow using IP integrator in the GUI. | Block Design in IP Integrator | AWS IP for HLx | Simulation, Virtual JTAG | Hardware developers with intermediate FPGA experience |
 
-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.
+On-premise environment: Customers can set up a [on-premise development (with licensing requirements listed)](./hdk/docs/on_premise_licensing_help.md) environment for [supported AMD tool versions.](#hardware-development-kit-hdk).
 
 ### Quick Start Links
 
@@ -116,12 +117,48 @@ On-premise environment: Customers can set up a on-premise development environmen
     <td style="text-align: center"><a href="https://github.com/Xilinx/Vitis_Accel_Examples/blob/main/hello_world/src/vadd.cpp">Design Source</a></td>
   </tr>
   <tr>
-    <td style="text-align: center"><a href="https://github.com/Xilinx/Vitis_Accel_Examples/blob/main/hello_world/src/host.cpp#L92">Testbench</a></td>
+    <td style="text-align: center"><a href="https://github.com/Xilinx/Vitis_Accel_Examples/blob/main/hello_world/src/host.cpp">Testbench</a></td>
   </tr>
   <tr>
     <td style="text-align: center"><a href="https://github.com/Xilinx/Vitis_Accel_Examples/blob/main/hello_world/src/host.cpp">Runtime Software</a></td>
   </tr>
-
+  <tr>
+    <td style="text-align: center" rowspan="9">HLx</td>
+    <td style="text-align: center" rowspan="3"><a href="https://github.com/aws/aws-fpga/tree/f2/hdk/cl/examples/hello_world_hlx">hello_world_hlx</a></td>
+    <td style="text-align: center" rowspan="3">Demonstrates simple register peek and poke using GPIO and VLED</td>
+    <td style="text-align: center" rowspan="3"><a href="./hdk/docs/IPI-GUI-Vivado-Setup.md">Vivado IPI Setup Guide</a></td>
+    <td style="text-align: center"><a href="./hdk/cl/examples/hello_world_hlx/README.md">Design Spec</a></td>
+  </tr>
+  <tr>
+    <td style="text-align: center"><a href="https://github.com/aws/aws-fpga-resources/tree/Hlx_1.0-hdk/common/shell_stable/hlx/hlx_examples/build/IPI/hello_world/verif">Testbench</a></td>
+  </tr>
+  <tr>
+    <td style="text-align: center"><a href="https://github.com/aws/aws-fpga-resources/tree/Hlx_1.0-hdk/common/shell_stable/hlx/hlx_examples/build/IPI/hello_world/software">Runtime Software</a></td>
+  </tr>
+  <tr>
+    <td style="text-align: center" rowspan="3"><a href="https://github.com/aws/aws-fpga/tree/f2/hdk/cl/examples/hello_world_mb_hlx">hello_world_mb_hlx</a></td>
+    <td style="text-align: center" rowspan="3">Demonstrates integrating MicroBlaze soft processor in HLx design</td>
+    <td style="text-align: center" rowspan="3"></td>
+    <td style="text-align: center"><a href="./hdk/cl/examples/hello_world_mb_hlx/README.md">Design Spec</a></td>
+  </tr>
+  <tr>
+    <td style="text-align: center"><a href="https://github.com/aws/aws-fpga-resources/tree/Hlx_1.0-hdk/common/shell_stable/hlx/hlx_examples/build/IPI/hello_world_mb/verif">Testbench</a></td>
+  </tr>
+  <tr>
+    <td style="text-align: center"><a href="https://github.com/aws/aws-fpga-resources/tree/Hlx_1.0-hdk/common/shell_stable/hlx/hlx_examples/build/IPI/hello_world_mb/software">Runtime Software</a></td>
+  </tr>
+  <tr>
+    <td style="text-align: center" rowspan="3"><a href="https://github.com/aws/aws-fpga/tree/f2/hdk/cl/examples/cl_ipi_cdma_test_hlx">cl_ipi_cdma_test_hlx</a></td>
+    <td style="text-align: center" rowspan="3">Demonstrates direct memory access to the DDR and HBM in AWS IP</td>
+    <td style="text-align: center" rowspan="3"></td>
+    <td style="text-align: center"><a href="./hdk/cl/examples/cl_ipi_cdma_test_hlx/README.md">Design Spec</a></td>
+  </tr>
+  <tr>
+    <td style="text-align: center"><a href="https://github.com/aws/aws-fpga-resources/tree/Hlx_1.0-hdk/common/shell_stable/hlx/hlx_examples/build/IPI/cl_ipi_cdma_test/verif">Testbench</a></td>
+  </tr>
+  <tr>
+    <td style="text-align: center"><a href="https://github.com/aws/aws-fpga-resources/tree/Hlx_1.0-hdk/common/shell_stable/hlx/hlx_examples/build/IPI/cl_ipi_cdma_test/software">Runtime Software</a></td>
+  </tr>
 </table>
 
 ### AWS Shells
@@ -178,8 +215,9 @@ To get started, please see the [README for a hello world accelerator example](./
 
 A free-to-use FPGA developer AMI is available for on-cloud F2 development with AMD tools pre-installed on a variety of AWS EC2 instance types. Customers can use this AMI to design, simulate, and build their designs. The table below lists the FPGA Developer AMI(s) currently released to customers:
 
-| FPGA Developer AMI Version | FPGA Developer AMI ID | Vivado/Vitis Version Supported | Operating System Version    |
-|----------------------------|-----------------------|--------------------------------|-----------------------------|
+| FPGA Developer AMI Version | FPGA Developer AMI ID (us-east-1) | Vivado/Vitis Version Supported | Operating System Version    |
+|----------------------------|-----------------------------------|--------------------------------|-----------------------------|
+| 1.18.0                     | [ami-04b57de2833b499b1](http://aws.amazon.com/marketplace/pp/prodview-7mukkbz7l2uvu) | 2025.1 | Rocky Linux 8.10 (4.18.0-553.36.1.el8_10.x86_64)|
 | 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)|
 
@@ -193,13 +231,15 @@ If you have never used AWS before, we recommend you start with [AWS getting star
 
 ## Next Steps
 
-Before you create your own AWS FPGA design, we recommend that you go through the [step-by-step quickstart guide for customer hardware development](./hdk/README.md).
+Once developers are familiar with the F2 development kit and the HDK development environment, we recommend exploring all the design features and examples offered in the AWS EC2 FPGA Development Kit:
+
+1. **Get Started**: Follow the [step-by-step quickstart guide for customer hardware development](./hdk/README.md) before creating your own AWS FPGA design
+2. **Learn by Example**: Explore [CL examples](./hdk/README.md#cl-examples) to understand shell-to-CL connectivity, memory interfaces (DDR & HBM), and the [CL clock generation block](./hdk/docs/AWS_CLK_GEN_spec.md)
+
+    - [Run RTL simulations](./hdk/docs/RTL_Simulation_Guide_for_HDK_Design_Flow.md) for design verification of existing CL examples.
+    - Review the [AWS F2 Shell-CL interfaces](./hdk/docs/AWS_Shell_Interface_Specification.md), e.g. [the HBM monitor interface](./hdk/docs/AWS_Shell_Interface_Specification.md#hbm-monitor-interface)
 
-Once developers are familiar with the F2 development kit and the HDK development environment, we recommend exploring the following contents to master all the design features and examples offered in the AWS EC2 FPGA Development Kit:
+3. **Create Your Design**: Use the [CL_TEMPLATE](./hdk/cl/examples/CL_TEMPLATE/README.md) example as a starting point
 
-- [Run RTL simulations](./hdk/docs/RTL_Simulation_Guide_for_HDK_Design_Flow.md) provided in CL examples to learn the design verification setup in the HDK development environment.
-- Familiarize with the [AWS F2 Shell-CL interfaces](./hdk/docs/AWS_Shell_Interface_Specification.md), e.g. [the HBM monitor interface](./hdk/docs/AWS_Shell_Interface_Specification.md/#hbm-monitor-interface)
-- Familiarize with the [shell floorplan](./hdk/docs/shell_floorplan.md) and locations of major shell interfaces.
-- Deep dive into [CL examples](./hdk/README.md#cl-examples) to explore shell-to-CL connectivity, CL resources e.g. DDR and HBM, and features e.g. [CL clock generation block](./hdk/docs/AWS_CLK_GEN_spec.md).
-- Create a custom CL design using the [CL_TEMPLATE](./hdk/cl/examples/CL_TEMPLATE/README.md) example.
-- Connect to a custom CL design in FPGA through [Virtual JTAG](./hdk/docs/Virtual_JTAG_XVC.md) to run hardware debug.
+    - Review the [shell floorplan](./hdk/docs/shell_floorplan.md) and locations of major shell interfaces.
+    - Connect to debug cores within a custom FPGA CL design through the [Virtual JTAG](./hdk/docs/Virtual_JTAG_XVC.md) interface to debug hardware issues.
diff --git a/developer_resources/Amazon_DCV_Setup_Guide.md b/developer_resources/Amazon_DCV_Setup_Guide.md
@@ -32,7 +32,7 @@ graphical user interface (GUI) to visualize FPGA development in the cloud.
 ### Prerequisites
 
 1. [Instance and IAM Configuration for DCV Licensing](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-license.html#dcv-lic-req)
-2. [Depenency Installation](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-gui)
+2. [Dependency Installation](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-gui)
     - :warning: DO NOT PERFORM STEP 3! Upgrading may impact the stability of development kit software!
 3. [Protocol Setup](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-wayland)
 4. [Driver Installation and Setting Virtual Display Resolution](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-nongpu)

diff --git a/docs-rtd/Makefile b/docs-rtd/Makefile
@@ -154,7 +154,16 @@ doctest:
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
 spelling:
-	$(SPHINXBUILD) -b spelling source/ build/
+	$(SPHINXBUILD) -b spelling source/ build/ && \
+	echo "Spelling check complete" >&2 && \
+	if [ -n "$$(find build -name "*.spelling" 2>/dev/null)" ]; then \
+		find build -name "*.spelling" -exec cat {} \; | \
+			sed 's/^\(.*\.rst\):\([0-9]*\): (\([^)]*\)).*/- \3 (in \1, line \2)/' | \
+			sort | uniq >&2 && \
+			echo "Spelling errors found. Total misspelled words: $$(find build -name "*.spelling" -exec cat {} \; | wc -l)" >&2; \
+	else \
+		echo "No spelling errors found." >&2; \
+	fi
 
 links:
 	make clean && make html && python3 ../shared/bin/check_doc_links.py