Release v2.0.1 (#665)

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
+
+python:
+  install:
+    - requirements: docs-rtd/requirements.txt
+
+sphinx:
+  configuration: docs-rtd/source/conf.py

ERRATA.md

@@ -7,13 +7,15 @@ Shell errata is [documented here](./hdk/docs/AWS_Shell_ERRATA.md)
 
 ## HDK
 
-1. CL simulation might show the following "error" message if the [CL clock generator](./hdk/docs/AWS_CLK_GEN_spec.md) is contained in the design. By default, the generator blocks all output clocks (except for `o_clk_main_a0`) and asserts all output resets. This behavior violates the built-in reset check in the [AXI SmartConnect IP](https://www.xilinx.com/products/intellectual-property/smartconnect.html#overview). This message can be safely ignored. A Fix for this issue is in progress.
+1. Support for the XDMA Shell in the HDK design flow is not available at this time. CL builds using the XDMA Shell will result in a build failure.
+
+2. CL simulation might show the following "error" message if the [CL clock generator](./hdk/docs/AWS_CLK_GEN_spec.md) is contained in the design. By default, the generator blocks all output clocks (except for `o_clk_main_a0`) and asserts all output resets. This behavior violates the built-in reset check in the [AXI SmartConnect IP](https://www.xilinx.com/products/intellectual-property/smartconnect.html#overview). This message can be safely ignored. A Fix for this issue is in progress.
 
     ```bash
     # ** Error: [SmartConnect 500-33] s_sc_aresetn should be asserted for at least 16 cycles of m_sc_aclk. tb.card.fpga.CL.CL_HBM.HBM_PRESENT_EQ_1.AXI_CONVERTER_AXI4_AXI3.cl_axi_sc_1x1_i.smartconnect_0.inst.s00_nodes.s00_aw_node.inst.<protected>.<protected>
     ```
 
-2. CL simulation might show the following "error" message. This message can be safely ignored. A Fix for this issue is in progress.
+3. CL simulation might show the following "error" message. This message can be safely ignored. A Fix for this issue is in progress.
 
     ```bash
     # Initializing memory from data in 'ddr4_ddr_10.mem'.
@@ -22,11 +24,9 @@ Shell errata is [documented here](./hdk/docs/AWS_Shell_ERRATA.md)
     #   ERROR: Failed to write data burst length to 16. Only <4,8> are valid.
     ```
 
-3. XSIM simulator does not support a cycle-accurate simulation model for the HBM IP. We’re observing significantly longer simulation times compared to VCS and Questa simulators. This is caused by the HBM BFM used in XSIM. Therefore, running HBM simulation using VCS or Questa is strongly recommended.
-
-4. XDMA driver interrupt mode doesn't work currently on instances. Runtime examples have temporarily switched to use the polling mode and the interrupt mode test has been temporarily removed. Refer to the [XDMA driver installation guide](./hdk/docs/XDMA_Install.md) for instructions on how to load XDMA driver using the polling mode.
+4. XSIM simulator does not support a cycle-accurate simulation model for the HBM IP. We’re observing significantly longer simulation times compared to VCS and Questa simulators. This is caused by the HBM BFM used in XSIM. Therefore, running HBM simulation using VCS or Questa is strongly recommended.
 
-5. The following hdk tests are not supported in XSIM currently and will report not supported warning if ran:
+5. The following HDK tests are currently not supported in XSIM and will report not supported warning if ran:
 
    - cl_mem_perf:
      - test_dram_dma_4k_crossing
@@ -40,10 +40,18 @@ Shell errata is [documented here](./hdk/docs/AWS_Shell_ERRATA.md)
 
 6. Simulation of the [HBM monitor interface](./hdk/docs/AWS_Shell_Interface_Specification.md/#hbm-monitor-interface) is not supported in this release. The HBM IP always passes initialization and remains in an operating state for all tests. Simulation support for the HBM monitor will be added in a future release.
 
-7. AFIs created based on HDK XDMA shell or Vitis are not supported on F2 instances at this time.
+7. AFIs created based on HDK XDMA shell or Vitis are not supported on F2
+   instances at this time.
+
+8. The following ddr simulation backdoor test is not working with 64GB memory:
+   - test_ddr_peek_bdr_walking_ones
 
 ## SDK
 
 ## Software defined Accelerator Development (Vitis)
 
-- Support for 2024.1 and hardware emulation only. Software emulation and F2 instance support is not supported at this time.
+1. Only hardware emulation via Vitis 2024.1 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.
+
+3. Support for Vitis software emulation has been deprecated by AMD, therefore, no longer supported.

README.md

@@ -12,6 +12,10 @@ The F2 FPGA Development Kit is a hardware-software development kit that enables
 
 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)
 
+## F2 FPGA ReadTheDocs (Beta)
+
+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).
+
 ## Support
 
 To raise an issue or receive support, please [open an issue on the official GitHub page](https://github.com/aws/aws-fpga/issues).

RELEASE_NOTES.md

@@ -1,4 +1,7 @@
 # F2 Developer Kit Release Notes
 
+## v2.0.1
+Updates to HDK, SDK, and Vitis documentation. Added check for XRT install to enable Vitis hardware emulation. XRT install can now be performed automatically by running a command presented during `vitis_setup.sh`.
+
 ## v2.0.0
-Initial release. F2 general-availability companion.
+Initial release. F2 general-availability companion.

docs-rtd/Makefile

@@ -0,0 +1,156 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -a -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/F2.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/F2.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/F2"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/F2"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+spelling:
+	$(SPHINXBUILD) -b spelling source/ build/

docs-rtd/requirements.txt

@@ -0,0 +1 @@
+sphinx==5.3.0

docs-rtd/source/ERRATA.rst

@@ -0,0 +1,83 @@
+F2 Developer Kit Errata
+=======================
+
+Shell Errata
+------------
+
+Shell errata is `documented here <./hdk/docs/AWS_Shell_ERRATA.md>`__
+
+HDK
+---
+
+1. Support for the XDMA Shell in the HDK design flow is not available at this time.
+   CL builds using the XDMA Shell will result in a build failure.
+
+2. CL simulation might show the following "error" message if the `CL
+   clock generator <./hdk/docs/AWS_CLK_GEN_spec.md>`__ is contained in
+   the design. By default, the generator blocks all output clocks
+   (except for ``o_clk_main_a0``) and asserts all output resets. This
+   behavior violates the built-in reset check in the `AXI SmartConnect
+   IP <https://www.xilinx.com/products/intellectual-property/smartconnect.html#overview>`__.
+   This message can be safely ignored. A Fix for this issue is in
+   progress.
+
+   .. code:: bash
+
+      # ** Error: [SmartConnect 500-33] s_sc_aresetn should be asserted for at least 16 cycles of m_sc_aclk. tb.card.fpga.CL.CL_HBM.HBM_PRESENT_EQ_1.AXI_CONVERTER_AXI4_AXI3.cl_axi_sc_1x1_i.smartconnect_0.inst.s00_nodes.s00_aw_node.inst.<protected>.<protected>
+
+3. CL simulation might show the following "error" message. This message
+   can be safely ignored. A Fix for this issue is in progress.
+
+   .. code:: bash
+
+      # Initializing memory from data in 'ddr4_ddr_10.mem'.
+      #   Reading data in x8 and bl:8 mode (Change with 'config <4,8,16> <4,8>' in this file).
+      #   'ddr4_ddr_10.mem' set write data width to x4.
+      #   ERROR: Failed to write data burst length to 16. Only <4,8> are valid.
+
+4. XSIM simulator does not support a cycle-accurate simulation model for
+   the HBM IP. We’re observing significantly longer simulation times
+   compared to VCS and Questa simulators. This is caused by the HBM BFM
+   used in XSIM. Therefore, running HBM simulation using VCS or Questa
+   is strongly recommended.
+
+5. The following hdk tests are not supported in XSIM currently and will
+   report not supported warning if ran:
+
+   - cl_mem_perf:
+
+     - test_dram_dma_4k_crossing
+     - test_dram_dma
+     - test_dram_dma_align_addr_4k
+     - test_dram_dma_single_beat_4k
+     - test_dram_dma_rnd
+
+   - cl_dram_hbm_dma:
+
+     - test_dram_dma_4k_crossing
+
+6. Simulation of the `HBM monitor
+   interface <./hdk/docs/AWS_Shell_Interface_Specification.md/#hbm-monitor-interface>`__
+   is not supported in this release. The HBM IP always passes
+   initialization and remains in an operating state for all tests.
+   Simulation support for the HBM monitor will be added in a future
+   release.
+
+7. AFIs created based on HDK XDMA shell or Vitis are not supported on F2
+   instances at this time.
+
+8. The following ddr simulation backdoor test is not working with 64GB memory:
+
+   - test_ddr_peek_bdr_walking_ones
+
+SDK
+---
+
+Software defined Accelerator Development (Vitis)
+------------------------------------------------
+
+1. Only hardware emulation via Vitis 2024.1 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.
+
+3. Support for Vitis software emulation has been deprecated by AMD, therefore, no longer supported.

docs-rtd/source/RELEASE_NOTES.rst

@@ -0,0 +1,19 @@
+F2 Developer Kit Release Notes
+==============================
+
+.. _v201:
+
+v2.0.1
+------
+
+Updates to HDK, SDK, and Vitis documentation.
+Added check for XRT install to enable Vitis hardware emulation.
+XRT install can now be performed automatically by running a
+command presented during `vitis_setup.sh`.
+
+.. _v200:
+
+v2.0.0
+------
+
+Initial release. F2 general-availability companion.