diff --git a/.github/workflows/top-level.yml b/.github/workflows/top-level.yml new file mode 100644 index 00000000..31676810 --- /dev/null +++ b/.github/workflows/top-level.yml @@ -0,0 +1,92 @@ +on: + push: + branches: + - main + pull_request: + +jobs: + build-doc: + runs-on: ubuntu-latest + + steps: + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.x" + + - uses: actions/checkout@v4 + with: + lfs: 'true' + + - name: Install pip packages + working-directory: docs + run: | + pip install pip --upgrade + pip install -r requirements.txt --upgrade + + - name: Build doc + working-directory: docs + run: | + make html + + - name: Store the generated doc + uses: actions/upload-artifact@v4 + with: + name: html + path: docs/_build/html + + deploy: + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' + needs: [build-doc] + permissions: + contents: write + + steps: + - run: | + git config --global user.name "${{ github.event.head_commit.committer.name }}" + git config --global user.email "${{ github.event.head_commit.committer.email }}" + + - uses: actions/checkout@v4 + - name: Create gh-pages branch + run: > + git ls-remote --exit-code --heads origin refs/heads/gh-pages || + ( + git reset --hard ; + git clean -fdx ; + git checkout --orphan gh-pages ; + git reset --hard; + git commit -m "empty" --allow-empty ; + git push origin gh-pages:gh-pages + ) + + - uses: actions/checkout@v4 + with: + ref: 'gh-pages' + lfs: 'false' + + - name: Empty gh-pages + run: | + git rm -r . --quiet || true + + - uses: actions/download-artifact@v4 + with: + name: html + + - name: Patch doc build + run: | + rm -r _sources + touch .nojekyll + + - name: Commit gh-pages + run: | + author=$(git log -1 --pretty=format:'%an') + email=$(git log -1 --pretty=format:'%ae') + commit=$(git rev-parse --short HEAD) + + git add . >> /dev/null + git commit -m "deploy: ${GITHUB_SHA}" --allow-empty + + - name: Push to gh-pages + run: >- + git push origin gh-pages:gh-pages diff --git a/docs/Makefile b/docs/Makefile new file mode 100755 index 00000000..955dbcdb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,13 @@ +SHELL = /bin/bash +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100755 index 00000000..478c0dff --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,42 @@ +# -- Project information ------------------------------------------------------ + +repository = 'testbenches' +project = 'Testbenches' +copyright = '2024, Analog Devices, Inc.' +author = 'Analog Devices, Inc.' + +# -- General configuration ---------------------------------------------------- + +extensions = [ + "sphinx.ext.todo", + "sphinxcontrib.wavedrom", + "adi_doctools" +] + +needs_extensions = { + 'adi_doctools': '0.3.47' +} + +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +source_suffix = '.rst' + +# -- External docs configuration ---------------------------------------------- + +interref_repos = ['doctools', 'hdl'] + +# -- Custom extensions configuration ------------------------------------------ + +hide_collapsible_content = True +validate_links = False + +# -- todo configuration ------------------------------------------------------- + +todo_include_todos = True +todo_emit_warnings = True + +# -- Options for HTML output -------------------------------------------------- + +html_theme = 'cosmic' +html_static_path = ['sources'] +html_css_files = ["custom.css"] +html_favicon = "sources/icon.svg" diff --git a/docs/index.rst b/docs/index.rst new file mode 100755 index 00000000..3d451ca8 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,27 @@ +HDL Testbenches +=============================================================================== + +.. attention:: + + Work-in-progress, not all content has been included yet. + +.. image:: sources/HDL_logo.svg + :align: center + :scale: 100% + +`Analog Devices Inc. `_ +HDL testbenches for various reference design and prototyping systems. +This repository contains HDL code (SystemVerilog) and the required Tcl scripts +to create and build a specific FPGA testbench example design using Xilinx toolchain. + +.. hdl-build-status:: + +Contents +=============================================================================== + +.. toctree:: + :maxdepth: 1 + + user_guide/index + library/index + testbenches/index diff --git a/docs/library/drivers/common/index.rst b/docs/library/drivers/common/index.rst new file mode 100644 index 00000000..8f765b96 --- /dev/null +++ b/docs/library/drivers/common/index.rst @@ -0,0 +1,14 @@ +.. _common: + +Common +================================================================================ + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + Monitor + Scoreboard + Watchdog diff --git a/docs/library/drivers/common/monitor/index.rst b/docs/library/drivers/common/monitor/index.rst new file mode 100644 index 00000000..f6cd7202 --- /dev/null +++ b/docs/library/drivers/common/monitor/index.rst @@ -0,0 +1,5 @@ +.. _monitor: + +Monitor +================================================================================ + diff --git a/docs/library/drivers/common/scoreboard/index.rst b/docs/library/drivers/common/scoreboard/index.rst new file mode 100644 index 00000000..d486a25b --- /dev/null +++ b/docs/library/drivers/common/scoreboard/index.rst @@ -0,0 +1,5 @@ +.. _scoreboard: + +Scoreboard +================================================================================ + diff --git a/docs/library/drivers/common/watchdog/index.rst b/docs/library/drivers/common/watchdog/index.rst new file mode 100644 index 00000000..1a374b56 --- /dev/null +++ b/docs/library/drivers/common/watchdog/index.rst @@ -0,0 +1,5 @@ +.. _watchdog: + +Watchdog +================================================================================ + diff --git a/docs/library/drivers/data_offload/index.rst b/docs/library/drivers/data_offload/index.rst new file mode 100644 index 00000000..5639976c --- /dev/null +++ b/docs/library/drivers/data_offload/index.rst @@ -0,0 +1,5 @@ +.. _data_offload: + +Data Offload +================================================================================ + diff --git a/docs/library/drivers/dmac/index.rst b/docs/library/drivers/dmac/index.rst new file mode 100644 index 00000000..d4cd605e --- /dev/null +++ b/docs/library/drivers/dmac/index.rst @@ -0,0 +1,5 @@ +.. _dmac: + +DMAC +================================================================================ + diff --git a/docs/library/drivers/index.rst b/docs/library/drivers/index.rst new file mode 100644 index 00000000..ad595075 --- /dev/null +++ b/docs/library/drivers/index.rst @@ -0,0 +1,17 @@ +.. _drivers: + +Drivers +================================================================================ + +Contents +------------------------------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + common/index + data_offload/index + dmac/index + jesd/index + spi_engine/index + xcvr/index diff --git a/docs/library/drivers/jesd/index.rst b/docs/library/drivers/jesd/index.rst new file mode 100644 index 00000000..b78339bd --- /dev/null +++ b/docs/library/drivers/jesd/index.rst @@ -0,0 +1,5 @@ +.. _jesd: + +JESD +================================================================================ + diff --git a/docs/library/drivers/spi_engine/index.rst b/docs/library/drivers/spi_engine/index.rst new file mode 100644 index 00000000..0d10a112 --- /dev/null +++ b/docs/library/drivers/spi_engine/index.rst @@ -0,0 +1,5 @@ +.. _spi_engine: + +SPI Engine +================================================================================ + diff --git a/docs/library/drivers/xcvr/index.rst b/docs/library/drivers/xcvr/index.rst new file mode 100644 index 00000000..5afc736e --- /dev/null +++ b/docs/library/drivers/xcvr/index.rst @@ -0,0 +1,5 @@ +.. _xcvr: + +XCVR +================================================================================ + diff --git a/docs/library/index.rst b/docs/library/index.rst new file mode 100644 index 00000000..ee520a7f --- /dev/null +++ b/docs/library/index.rst @@ -0,0 +1,37 @@ +.. _library: + +Library +=============================================================================== + +Drivers +------------------------------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + drivers/index + +Registermaps +------------------------------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + regmaps/index + +Utilities +------------------------------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + utilities/index + +VIPs +------------------------------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + vip/index + diff --git a/docs/library/regmaps/index.rst b/docs/library/regmaps/index.rst new file mode 100644 index 00000000..802ee822 --- /dev/null +++ b/docs/library/regmaps/index.rst @@ -0,0 +1,8 @@ +.. _regmaps: + +Registermaps +================================================================================ + +Contents +-------- + diff --git a/docs/library/utilities/index.rst b/docs/library/utilities/index.rst new file mode 100644 index 00000000..233c394f --- /dev/null +++ b/docs/library/utilities/index.rst @@ -0,0 +1,11 @@ +.. _utilities: + +Utilities +================================================================================ + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + diff --git a/docs/library/vip/adi/index.rst b/docs/library/vip/adi/index.rst new file mode 100644 index 00000000..bd48ccfb --- /dev/null +++ b/docs/library/vip/adi/index.rst @@ -0,0 +1,13 @@ +.. _adi_vip: + +ADI VIPs +================================================================================ + +Contents +-------- + +.. toctree:: + :maxdepth: 1 + + SPI VIP + diff --git a/docs/library/vip/adi/spi_vip/index.rst b/docs/library/vip/adi/spi_vip/index.rst new file mode 100644 index 00000000..5e9428cb --- /dev/null +++ b/docs/library/vip/adi/spi_vip/index.rst @@ -0,0 +1,33 @@ +.. _spi_vip: + +SPI VIP +================================================================================ + +Description + +Features +-------------------------------------------------------------------------------- + +Files +-------------------------------------------------------------------------------- + +VIP interface + +Configuration parameters +-------------------------------------------------------------------------------- + +Interface +-------------------------------------------------------------------------------- + +Functions +-------------------------------------------------------------------------------- + +Known Issues +-------------------------------------------------------------------------------- + +Technical Support +-------------------------------------------------------------------------------- + +References +-------------------------------------------------------------------------------- + diff --git a/docs/library/vip/amd/axi_vip/index.rst b/docs/library/vip/amd/axi_vip/index.rst new file mode 100644 index 00000000..e463c72f --- /dev/null +++ b/docs/library/vip/amd/axi_vip/index.rst @@ -0,0 +1,34 @@ +.. _xilinx_axi_vip: + +Xilinx AXI Verification IP (VIP) +================================================================================ + +Overview +------------------------------------------------------------------------------- + +`[1] `__ + +m_axi_sequencer +------------------------------------------------------------------------------- + +Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +s_axi_sequencer +------------------------------------------------------------------------------- + +Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +References +------------------------------------------------------------------------------- + +`[1] "AXI Verification IP LogiCORE IP Product Guide (PG267)", Xilinx, 2019 +`__ + diff --git a/docs/library/vip/amd/axis_vip/index.rst b/docs/library/vip/amd/axis_vip/index.rst new file mode 100644 index 00000000..06066bbd --- /dev/null +++ b/docs/library/vip/amd/axis_vip/index.rst @@ -0,0 +1,33 @@ +.. _xilinx_axis_vip: + +Xilinx AXI Stream Verification IP (VIP) +================================================================================ + +Overview +-------------------------------------------------------------------------------- + +`[1] `__ + +m_axi_sequencer +-------------------------------------------------------------------------------- + +Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +s_axi_sequencer +-------------------------------------------------------------------------------- + +Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +References +------------------------------------------------------------------------------- + +`[1] "AXI4-Stream Verification IP v1.1 LogiCORE IP Product Guide (PG277)", +Xilinx, 2019 `__ diff --git a/docs/library/vip/amd/clk_vip/index.rst b/docs/library/vip/amd/clk_vip/index.rst new file mode 100644 index 00000000..a4bc45eb --- /dev/null +++ b/docs/library/vip/amd/clk_vip/index.rst @@ -0,0 +1,18 @@ +.. _xilinx_clk_vip: + +Xilinx Clock Verification IP (VIP) +================================================================================ + +Overview +------------------------------------------------------------------------------- + +`[1] `__ + + +References +------------------------------------------------------------------------------- + +`[1] "Clock Verification IP v1.0 Product Guide (PG291)", Xilinx, 2019 +`__ + + diff --git a/docs/library/vip/amd/index.rst b/docs/library/vip/amd/index.rst new file mode 100644 index 00000000..fc2a0582 --- /dev/null +++ b/docs/library/vip/amd/index.rst @@ -0,0 +1,16 @@ +.. _amd_vip: + +AMD VIPs +================================================================================ + +Contents +-------- + +.. toctree:: + :maxdepth: 1 + + AXI VIP + AXIS VIP + Clock VIP + Reset VIP + diff --git a/docs/library/vip/amd/rst_vip/index.rst b/docs/library/vip/amd/rst_vip/index.rst new file mode 100644 index 00000000..c28672a5 --- /dev/null +++ b/docs/library/vip/amd/rst_vip/index.rst @@ -0,0 +1,16 @@ +.. _xilinx_rst_vip: + +Xilinx Reset Verification IP (VIP) +================================================================================ + +Overview +------------------------------------------------------------------------------- + +`[1] `__ + + +References +------------------------------------------------------------------------------- + +`[1] "Reset Verification IP Product Guide (PG298)", Xilinx, 2019 +`__ diff --git a/docs/library/vip/index.rst b/docs/library/vip/index.rst new file mode 100644 index 00000000..99c1f418 --- /dev/null +++ b/docs/library/vip/index.rst @@ -0,0 +1,13 @@ +.. _vip: + +Verification IPs (VIP) +================================================================================ + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + ADI + AMD diff --git a/docs/make.bat b/docs/make.bat new file mode 100755 index 00000000..922152e9 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..25985289 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx +https://github.com/analogdevicesinc/doctools/releases/download/latest/adi-doctools.tar.gz +sphinxcontrib.wavedrom diff --git a/docs/sources/HDL_logo.png b/docs/sources/HDL_logo.png new file mode 100644 index 00000000..6a226287 Binary files /dev/null and b/docs/sources/HDL_logo.png differ diff --git a/docs/sources/HDL_logo.svg b/docs/sources/HDL_logo.svg new file mode 100644 index 00000000..e167c9f6 --- /dev/null +++ b/docs/sources/HDL_logo.svg @@ -0,0 +1,538 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + IP CORES & REFERENCE DESIGNS + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FPGA + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/sources/HDL_logo_w.png b/docs/sources/HDL_logo_w.png new file mode 100644 index 00000000..0b95818e Binary files /dev/null and b/docs/sources/HDL_logo_w.png differ diff --git a/docs/sources/icon.svg b/docs/sources/icon.svg new file mode 100755 index 00000000..86d6c3b5 --- /dev/null +++ b/docs/sources/icon.svg @@ -0,0 +1,313 @@ + + + +FPGA diff --git a/docs/testbenches/common/more_information.rst b/docs/testbenches/common/more_information.rst new file mode 100644 index 00000000..9fe421bd --- /dev/null +++ b/docs/testbenches/common/more_information.rst @@ -0,0 +1,4 @@ +More information +------------------------------------------------------------------------------- + +To be done. diff --git a/docs/testbenches/common/support.rst b/docs/testbenches/common/support.rst new file mode 100644 index 00000000..1da1844f --- /dev/null +++ b/docs/testbenches/common/support.rst @@ -0,0 +1,12 @@ +Support +------------------------------------------------------------------------------- + +`Analog Devices, Inc.`_ will provide **limited** online support for anyone +using the :git-testbenches:`reference design <>` with `ADI`_ components via +the :ez:`fpga` FPGA reference designs forum. + +It should be noted, that the older the tools' versions and release branches +are, the lower the chances to receive support from `ADI`_ engineers. + +.. _Analog Devices, Inc.: https://www.analog.com/en/index.html +.. _ADI: https://www.analog.com/en/index.html diff --git a/docs/testbenches/index.rst b/docs/testbenches/index.rst new file mode 100644 index 00000000..050e9313 --- /dev/null +++ b/docs/testbenches/index.rst @@ -0,0 +1,27 @@ +Testbenches +=============================================================================== + +.. note:: + + This page lists only testbenches that have been ported to the new + documentation format. + +Contents +------------------------------------------------------------------------------- + +IP Based Testbenches +------------------------------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + ip_based/index + +Project Based Testbenches +------------------------------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + project_based/index + diff --git a/docs/testbenches/ip_based/index.rst b/docs/testbenches/ip_based/index.rst new file mode 100644 index 00000000..294fa09a --- /dev/null +++ b/docs/testbenches/ip_based/index.rst @@ -0,0 +1,13 @@ +.. _ip_based: + +IP Based +================================================================================ + +Contents +------------------------------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + template/index + diff --git a/docs/testbenches/ip_based/template/index.rst b/docs/testbenches/ip_based/template/index.rst new file mode 100644 index 00000000..cd8e7976 --- /dev/null +++ b/docs/testbenches/ip_based/template/index.rst @@ -0,0 +1,50 @@ +.. _ip_based_template: + +IP based test bench template +================================================================================ + +Overview +------------------------------------------------------------------------------- + +Block design +------------------------------------------------------------------------------- + +Block diagram +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Configuration parameters and modes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Build parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Tests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Available configurations & tests combinations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Clock scheme +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CPU/Memory interconnects addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Interrupts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Building the test bench +------------------------------------------------------------------------------- + +Test stimulus +------------------------------------------------------------------------------- + +Resources +------------------------------------------------------------------------------- + +.. include:: ../../common/more_information.rst + +.. include:: ../../common/support.rst diff --git a/docs/testbenches/project_based/ad7616/index.rst b/docs/testbenches/project_based/ad7616/index.rst new file mode 100644 index 00000000..ddb1182c --- /dev/null +++ b/docs/testbenches/project_based/ad7616/index.rst @@ -0,0 +1,9 @@ +:orphan: + +.. _ad7616: + +AD7616 Test bench +================================================================================ + +Overview +------------------------------------------------------------------------------- diff --git a/docs/testbenches/project_based/index.rst b/docs/testbenches/project_based/index.rst new file mode 100644 index 00000000..cf93201c --- /dev/null +++ b/docs/testbenches/project_based/index.rst @@ -0,0 +1,13 @@ +.. _project_based: + +Project Based +================================================================================ + +Contents +------------------------------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + template/index + diff --git a/docs/testbenches/project_based/template/index.rst b/docs/testbenches/project_based/template/index.rst new file mode 100644 index 00000000..ec666329 --- /dev/null +++ b/docs/testbenches/project_based/template/index.rst @@ -0,0 +1,193 @@ +.. _project_based_template: + +Project based test bench template +================================================================================ + +Overview +------------------------------------------------------------------------------- + +Block design +------------------------------------------------------------------------------- + +Block diagram +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. + MUST: Use SVG format for the diagram + +.. + TIP: Block diagrams should contain subtitles only if there are at least two + different diagrams + +.. image:: ../template/project_based_template_bd.svg + :width: 800 + :align: center + :alt: Template/Testbench block diagram + +Configuration parameters and modes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. + MENTION IF ANY MODES ARE AVAILABLE FOR CONFIGURATION + +Build parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following are the parameters of this project that can be configured: + +- CLK_MODE: defines clocking mode of the device's digital interface: + Options: 0 - SPI mode, 1 - Echo-clock or Master clock mode +- NUM_OF_SDI: defines the number of MOSI lines of the SPI interface: + Options: 1 - Interleaved mode, 2 - 1 lane per channel, + 4 - 2 lanes per channel, 8 - 4 lanes per channel +- CAPTURE_ZONE: defines the capture zone of the next sample. + There are two capture zones: 1 - from negative edge of the BUSY line + until the next CNV positive edge -20ns, 2 - from the next consecutive CNV + positive edge +20ns until the second next consecutive CNV positive edge -20ns +- DDR_EN: defines the type of data transfer. In echo and master clock mode + the SDI lines can have Single or Double Data Rates. + Options: 0 - MISO runs on SDR, 1 - MISO runs on DDR. + +Configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. + MENTION IF ANY CONFIGURATION FILES ARE AVAILABLE FOR TESTS + +The following are available configurations for the test bench: + + +-----------------------+-----------------------------------------------+ + | Configuration mode | Parameters | + | +----------+------------+--------------+--------+ + | | CLK_MODE | NUM_OF_SDI | CAPTURE_ZONE | DDR_EN | + +=======================+==========+============+==============+========+ + | cfg_cm0_sdi2_cz1_ddr0 | 0 | 2 | 1 | 0 | + +-----------------------+----------+------------+--------------+--------+ + | cfg_cm0_sdi2_cz2_ddr0 | 0 | 2 | 2 | 0 | + +-----------------------+----------+------------+--------------+--------+ + | cfg_cm0_sdi4_cz2_ddr0 | 0 | 4 | 2 | 0 | + +-----------------------+----------+------------+--------------+--------+ + | cfg_cm0_sdi8_cz2_ddr0 | 0 | 8 | 2 | 0 | + +-----------------------+----------+------------+--------------+--------+ + | cfg_cm1_sdi1_cz2_ddr0 | 1 | 1 | 2 | 0 | + +-----------------------+----------+------------+--------------+--------+ + | cfg_cm1_sdi2_cz2_ddr0 | 1 | 2 | 2 | 0 | + +-----------------------+----------+------------+--------------+--------+ + | cfg_cm1_sdi2_cz2_ddr1 | 1 | 2 | 2 | 1 | + +-----------------------+----------+------------+--------------+--------+ + | cfg_cm1_sdi4_cz2_ddr0 | 1 | 4 | 2 | 0 | + +-----------------------+----------+------------+--------------+--------+ + | cfg_cm1_sdi4_cz2_ddr1 | 1 | 4 | 2 | 1 | + +-----------------------+----------+------------+--------------+--------+ + | cfg_cm1_sdi8_cz2_ddr0 | 1 | 8 | 2 | 0 | + +-----------------------+----------+------------+--------------+--------+ + | cfg_cm1_sdi8_cz2_ddr1 | 1 | 8 | 2 | 1 | + +-----------------------+----------+------------+--------------+--------+ + +Tests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. + MENTION IF ANY MODES ARE AVAILABLE FOR TESTS + +The following test program files are available: + +=============== ========================================== +Test program Usage +=============== ========================================== +test_program_si Tests the parallel interface capabilities. +test_program_pi Tests the serial interface capabilities. +=============== ========================================== + +Available configurations & tests combinations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +============= =============== =================================== +Configuration Test Build command +============= =============== =================================== +cfg_si test_program_si make CFG=cfg_si TST=test_program_si +cfg_pi test_program_pi make CFG=cfg_pi TST=test_program_pi +============= =============== =================================== + +.. warning:: + + Mixing a wrong pair of CFG and TST will result in a building errror. + Please checkout the proposed combinations before running a custom test. + +Clock scheme +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CPU/Memory interconnects addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Interrupts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Building the test bench +------------------------------------------------------------------------------- + +The testbench is built upon ADI's generic HDL reference design framework. +ADI does not distribute compiled files of these projects so they must be built +from the sources available :git-hdl:`here ` and :git-testbenches:`here `, +with the specified hierarchy described :ref:`build_tb set_up_tb_repo`. +To get the source you must +`clone `__ +the HDL repository, and then build the project as follows:. + +**Linux/Cygwin/WSL** + +*Example 1* + +Build all the possible combinations of tests and configurations, using only the +command line. + +.. shell:: + :showuser: + + $cd testbenches/ad7616 + $make + +*Example 2* + +Build all the possible combinations of tests and configurations, using the +Vivado GUI. This command will launch Vivado, will run the simulation and display +the waveforms. + +.. shell:: + :showuser: + + $cd testbenches/ad7616 + $make MODE=gui + +*Example 3* + +Build a particular combination of test and configuration, using the Vivado GUI. +This command will launch Vivado, will run the simulation and display the +waveforms. + +.. shell:: + :showuser: + + $cd testbenches/ad7616 + $make MODE=gui CFG=cfg_pi TST=test_program_pi + +The built projects can be found in the ``runs`` folder, where each configuration specific +build has it's own folder named after the configuration file's name. +Example: if the following command was run for a single configuration in the clean folder +(no runs folder available): + +``make CFG=cfg_pi`` + +Then the subfolder under ``runs`` name will be: + +``cfg_pi`` + +Test stimulus +------------------------------------------------------------------------------- + +Resources +------------------------------------------------------------------------------- + +.. include:: ../../common/more_information.rst + +.. include:: ../../common/support.rst diff --git a/docs/testbenches/project_based/template/project_based_template_bd.svg b/docs/testbenches/project_based/template/project_based_template_bd.svg new file mode 100644 index 00000000..229aec07 --- /dev/null +++ b/docs/testbenches/project_based/template/project_based_template_bd.svg @@ -0,0 +1,1908 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + MEMORY INTERCONNECT + + + + TEST MODULE + + TESTBENCH + + AD7616_DMA + 80MHz + + + + + + + + MISO/SDI + SPI ENGINE FRAMEWORK + CS + SCLK + + + + + + OFFLOAD + + INTER-CONNECT + + + EXECUTION + + AXI REGMAP + + + sys_clk = 100MHz + + + + + + + + AXI PWM GEN + + AXI CLKGEN + spi_clk = 160MHz + + + + + + + + + DDR VIP + + PS AXI VIP + PROJECT LEVEL BLOCK DESIGN (DUT) + + + + RX_CNVST + + TOP MODULE + + 64b + + + 16b + trigger + + diff --git a/docs/user_guide/architecture.rst b/docs/user_guide/architecture.rst new file mode 100644 index 00000000..d5cd24a1 --- /dev/null +++ b/docs/user_guide/architecture.rst @@ -0,0 +1,145 @@ +.. _architecture: + +Testbenches Architecture +=============================================================================== + +File structure of a project +------------------------------------------------------------------------------- + +.. tip:: + + In ``testbenches/ip/base/`` you can find a test bench base design. + +Project files for test benches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``library`` --- common files that are used in many projects + + - ``drivers`` --- drivers and APIs used for controlling IPs as well as VIPs; + these modules can use register map files, VIPs and other APIs + - ``regmaps`` --- register map files created for simulations based on the + HDL IP register maps along with a couple of utility files; these are macro + functions that are used to access a specific IP's register's field in a + given variable that is passed to these functions + - ``utilities`` --- common scripts, modules and macros that are used for + testbench design and environment creation + - ``vip`` --- ADI verification IPs (VIP) and additional auxiliary classes + which are vendor specific + +- ``scripts`` --- used for creating and running the testbenches + +- ``testbenches`` + + - ``cfgs`` --- projects might have various parameters that can only be set + during project creation, these parameters are set in one of these + configuration files and can be passed to the simulation environment; + they might also contain parameters that aid in building various block designs + + - ``tests`` --- main simulation files, they control and monitor the DUT(s) + + - ``waves`` --- waveforms for various configuration options (only used in + GUI mode) + + - ``Makefile`` --- lists the required System Verilog files, Tcl scripts, + libraries used, and configuration-test_program combinations (if it’s the + case, otherwise all configurations run one and the same default test program) + + - ``system_project.tcl`` --- creates the project, the base block design based + on the test_harness_system_bd and sets up a couple of definitions for the + environment and test program + + - ``system_bd.tcl`` --- adds the DUT(s) to the block design with the configuration + files (even if no configuration parameter is used, a configuration file must + exist) + + - ``system_tb.sv`` --- connects the block design with the test program + + +Creating a new testbench +------------------------------------------------------------------------------- + +- Create the ``Makefile`` and list all of the currently known dependencies +- Create the ``system_project.tcl`` script and add the currently known + simulation dependencies there as well +- Create at least one ``configuration file`` (it can be left empty) +- Create the ``system_bd.tcl`` script, which creates the block design (consider + using Verification IPs as these are created to make testing easier and facilitates + faster testbench bring-up as well as less bugs in general) +- Create the ``system_tb.sv`` file that connects the testbench with the block design +- Consider creating ``classes`` that encapsulate the variables and functions, so it + can be used in other testbenches +- Create the ``test_program.sv`` to run the simulation +- Update the ``Makefile`` and ``system_project.tcl`` with the new dependencies + if needed. + +Adding a new configuration to a test bench +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + Simple, all of the configurations are compatible with all of the test programs. + +Requirements: + +- New ``configuration`` doesn't change the connections between the block design and + the ``test program``. +- ``Test program`` can be used with the new ``configuration`` without modifications. + +Process: + +- Create a ``new configuration`` in ``cfg`` folder. +- Check if the ``Makefile`` automatically includes the newly created ``configuration``, + otherwise add it to the list manually. +- If a ``new parameter`` needs to be added, make sure all of the other ``configuration`` + files are updated with the new parameter name and a new value as well +- Test the configuration with the existing test program. + +Adding a new test program to a test bench +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + Simple, all of the configurations are compatible with all of the test programs. + +Requirements: + +- Connections between the block design and the test program don't change. +- All of the existing ``configurations`` must be compatible with the new + ``test program``. + +Process: + +- Create a ``new test program`` in tests folder. +- Check if the ``Makefile`` automatically includes the newly created + ``configuration``, otherwise add it to the list manually. +- Test the program with the existing configurations. + +Creating a modified block design in the same project folder +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + + Advanced, not all configurations are compatible with the test programs. + +Requirements: + +- New ``configuration file(s)`` must be created for the new block design. + +Process: + +- Create a new parameter that tells the ``system_bd.tcl`` what to build. + - this parameter must be included in all of the existing and new + configuration files; + - if the design already has multiple variations of the block design, + update the existing parameter with the new value which corresponds + to the new block design +- Modify the ``system_bd.tcl`` script to use the created parameter to create the + old or new block design. +- In ``system_tb.sv`` use the parameter to connect the new block design with a + new ``test program``. +- Create the ``new test program``. +- In the ``Makefile``, modify the TESTS list to not be automatically generated + and add the test program:config options to the list that you want to run. +- In the ``system_project.tcl`` add a switch that chooses between the test programs + based on the parameter. +- Write and test the new ``test program``. diff --git a/docs/user_guide/build_tb.rst b/docs/user_guide/build_tb.rst new file mode 100644 index 00000000..0e615611 --- /dev/null +++ b/docs/user_guide/build_tb.rst @@ -0,0 +1,165 @@ +.. _build_tb: + +Build a test bench +=============================================================================== + +**Please note that ADI only provides the source files necessary to create and +build the designs. This means that you are responsible for modifying and +building these projects.** + +Here, we are giving you a quick rundown on how we build things. That said, +the steps below are **not a recommendation**, but a suggestion. +How you want to build these projects is entirely up to you. +The only catch is that if you run into problems, you have to resolve them independently. + +The build process depends on certain software and tools, which you could use in +many ways. We use **command line** and mostly **Linux systems**. On Windows, we +use **Cygwin**. + +.. _build_tb set_up_tb_repo: + +Set up the Testbenches repository +------------------------------------------------------------------------------- + +.. caution:: + + Before building any testbench, you **must**: + + #. Clone the :git-hdl:`HDL repository ` + + #. Check the Vivado version needed by entering the + :git-hdl:`hdl/scripts/adi_env.tcl ` file. If you do + not want to use that (although **we strongly advise you to use it**) + then you have the alternative of setting ``export ADI_IGNORE_VERSION_CHECK=1`` + before building the project. Otherwise your project will fail. + + #. :external+hdl:ref:`Set up the HDL repository ` + + +The :git-testbenches:`Testbenches repository ` has to be cloned under the +:git-hdl:`HDL repository ` as follows: + +.. shell:: + + $cd hdl + $git clone git@github.com:analogdevicesinc/testbenches.git + +The above command clones the **default** branch, which is the **main** for +Testbenches. The **main** branch always points to the latest stable release +branch, but it also has features **that are not fully tested**. If you +want to switch to any other branch you need to checkout that branch: + +.. shell:: + + $cd testbenches/ + $git branch + $git checkout 2022_r2 + +Building a test bench +------------------------------------------------------------------------------- + +.. caution:: + + Before building any test bench, you must have the environment prepared and the + proper tools. + +The way of building a test bench in Cygwin and WSL is almost the same. +In this example, it is building the **AD7616** test bench. + +.. shell:: + + $cd ad7616 + $make + +The ``make`` builds all the libraries first and then builds the test bench. +This assumes that you have the tools and licenses set up correctly. If +you don't get to the last line, the make failed to build one or more +targets: it could be a library component or the project itself. There is +nothing you can gather from the ``make`` output (other than which one +failed). The actual information about the failure is in a log file inside +the project directory. By default, ``make`` builds all of the available +configurations and runs all of the ``test programs`` that are predefined +in the ``Makefile``. + +Also, there's an option to use ``make`` using GUI, so that at the end of the +build it will launch Vivado and start the simulation with the waveform viewer +started as well. + +.. shell:: + + $make MODE=gui + +Some projects support adding additional ``make`` parameters to configure +the project. This option gives you the ability to build only the configuration +that you're interested in, without building the rest of the available +configurations, as well as running the chosen test program, if it is the case. + +If parameters were used, the result of the build will be in a folder under runs/, +named by the configuration used. + +**Example** + +Running the command below will create a folder named +**cfg_si** for the following file combination: **cfg_si** configuration file and +the **test_program_si** test program. + +.. shell:: + + $make MODE=gui CFG=cfg_si TST=test_program_si + +Environment +------------------------------------------------------------------------------- + +As mentioned above, our recommended build flow is to use ``make`` and the +command line version of the tools. This method facilitates our +overall build and release process as it automatically builds the +required libraries and dependencies. + +Linux environment setup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All major distributions should have ``make`` installed by default. If not, +if you try the command, it should tell you how to install it with the +package name. + +You may have to install ``git`` (``sudo apt-get install git``) +and the AMD tools. These tools come with certain **settings*.sh** scripts that +you may source in your **.bashrc** file to set up the environment. +You may also do this manually (for better or worse); the following snippet is +from a **.bashrc** file. Please note that unless you are an expert at manipulating +these things, it is best to leave it to the tools to set up the environment. + +.. shell:: + + $export PATH=$PATH:/opt/Xilinx/Vivado/202x.x/bin:/opt/Xilinx/Vitis/202x.x/bin + +Windows environment setup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The best option on Windows is to use +`Cygwin `__. When installing it, select the +``make`` and ``git`` packages. You should do changes to your **.bashrc** in a +similar manner to the Linux environment. + +.. shell:: + + $export PATH=$PATH:/cygdrive/d/Xilinx/Vivado/202x.x/bin:/cygdrive/d/Xilinx/Vitis/202x.x/bin + +A very good alternative to Cygwin is +`WSL `__. The +manual changes to your **.bashrc** should look like: + +.. shell:: + + $export PATH=$PATH:/opt/path_to/Vivado/202x.x/bin:/opt/Vitis/202x.x/bin + +If you do not want to install Cygwin, there might still be some +alternative. There are ``make`` alternatives for **Windows Command +Prompt**, minimalist GNU for Windows (**MinGW**), or the **Cygwin +variations** installed by the tools itself. + +Some of these may not be fully functional with our scripts and/or projects. +If you are an AMD user, use the **gnuwin** installed as part of the SDK, +usually at ``C:\Xilinx\Vitis\202x.x\gnuwin\bin``. + +.. _AMD Xilinx Vivado: https://www.xilinx.com/support/download.html diff --git a/docs/user_guide/coding_guidelines.rst b/docs/user_guide/coding_guidelines.rst new file mode 100755 index 00000000..578dcf10 --- /dev/null +++ b/docs/user_guide/coding_guidelines.rst @@ -0,0 +1,57 @@ +.. _coding_guidelines: + +ADI Testbenches coding guidelines +=============================================================================== + +1. Introduction +------------------------------------------------------------------------------- + +This document contains coding and documentation guidelines which must be +followed by all HDL testbenches. + +The coding rules are intended to be applied to testbenches written using +System Verilog. + +The HDL coding guidelines :external+hdl:ref:`hdl_coding_guidelines` are also +applicable here. In addition, there are a set of rules for System Verilog, +listed below. + +2. Coding style +------------------------------------------------------------------------------- + +A. Layout +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**A1** + +**A2** + +B. Naming Conventions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**B1** + +**B2** + +C. Comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**C1** + +**C2** + +D. General +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**D1** + +**D2** + +3. Annexes +------------------------------------------------------------------------------- + +Annex 1 System Verilog file format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +4. References +------------------------------------------------------------------------------- diff --git a/docs/user_guide/docs_guidelines.rst b/docs/user_guide/docs_guidelines.rst new file mode 100644 index 00000000..44c79e06 --- /dev/null +++ b/docs/user_guide/docs_guidelines.rst @@ -0,0 +1,50 @@ +.. _docs_guidelines: + +Documentation guidelines +================================================================================ + +This documentation is built with `Sphinx `_ and +all source code is available at the path :git-testbenches:`docs`. + +To contribute to it, open a pull request with the changes to +:git-testbenches:`this repository `, just make sure to read the general +:ref:`doctools:docs_guidelines` first **and** the additional guidelines +below specific to the Testbenches repository. + +Templates +-------------------------------------------------------------------------------- + +Templates are available: + +* :git-testbenches:`docs/projects/ip_based/template` (:ref:`rendered `). +* :git-testbenches:`docs/projects/project_based/template` (:ref:`rendered `). + +Remove the ``:orphan:`` in the first line, it is to hide the templates from the +`TOC tree `_, +and make sure to remove any placeholder text and instructive comment. + +.. note:: + + The old wiki uses `dokuwiki `_. When + importing text from there, consider ``pandoc`` and the tips accross the + :ref:`doctools:docs_guidelines` to convert it to reST. + +Common sections +-------------------------------------------------------------------------------- + +The **More information** and **Support** sections that are present in +the Testbenches documentation, are actually separate pages inserted as links. +They're located at testbenches/projects/common/more_information.rst and /support.rst, +and cannot be referenced here because they don't have an ID at the beginning +of the page, so not to have warnings when the documentation is rendered that +they're not included in any toctree. + +They are inserted like this: + +.. code-block:: + + .. include:: ../projects/common/more_information.rst + + .. include:: ../projects/common/support.rst + +And they will be rendered as sections of the page. diff --git a/docs/user_guide/git_repository.rst b/docs/user_guide/git_repository.rst new file mode 100644 index 00000000..5dd3a45f --- /dev/null +++ b/docs/user_guide/git_repository.rst @@ -0,0 +1,105 @@ +.. _git_repository: + +Testbenches Git repository +=============================================================================== + +This repository contains testbenches and verification components for system level +projects or components connected at block level from the HDL repository. + +This repository is not a stand alone one. It must be cloned or linked as a +submodule inside the HDL repository you want to test. + +All the **HDL** sources can be found in the following git repository: +:git-hdl:`/` + +All the **Testbenches** sources can be found in the following git repository: +:git-testbenches:`/` + +We assume that the user is familiar with `git `__. +Knows how to +`clone `__ +the repository, how to check its +`status `__ or how to +`switch `__ +between branches. + +.. note:: + + A basic git knowledge is required in order to work with these source files, + if you do not have any, don't worry! + + There are a lot of great resources and tutorials about git all over the + `web `__. + +If you want to pull down the sources as soon as possible, just do the +following few steps: + +#. Install Git from `here `__ +#. Open up Git bash, change your current directory to a place where you + want to keep the hdl source +#. Clone the repository using + `these `__ + instructions + +Folder structure +------------------------------------------------------------------------------- + +The root of the Testbenches repository has the following structure: + +.. code-block:: + + . + +-- .github + +-- docs + +-- library + +-- scripts + +-- testbenches + +-- Makefile + +-- README.md + +-- LICENSE + +The repository is divided into 5 separate sections: + +- **.github** with all our automations regarding coding checks, GitHub actions +- **docs** with our GitHubIO documentation and regmap source files +- **library** with all the Analog Devices Inc. proprietary IP cores and + hdl modules, which are required to build the projects +- **scripts** with scripts and makefiles to build and run the testbench +- **testbenches** with all the currently supported testbenches + + +The file **.gitattributes** is used to properly `handle +different `__ +line endings. And the **.gitignore** specifies intentionally untracked +files that Git should ignore. The root **Makefile** can be used to build +all the project of the repository. To learn more about hdl **Makefiles** +visit the :external+hdl:ref:`Building & Generating programming files ` section. + +Repository releases and branches +------------------------------------------------------------------------------- + +The repository may contain multiple branches and tags. The +:git-testbenches:`main ` branch is the development branch (latest sources, +but not stable). If you check out this branch, some builds may fail. If you are +not into any kind of experimentation, you should only check out one of the +release branch. + +All our release branches have the following naming convention: +[year_of_release]\ **\_r**\ [1 or 2]. (e.g. +:git-testbenches:`2022_r2 <2022_r2:>`) + +ADI does two releases each year when all the projects get an update to +support the latest tools and get additional new features. \*\* The +main branch is always synchronized with the latest release. \*\* If you +are in doubt, ask us on :ez:`fpga`. + +.. note:: + + You can find the release notes on of the repositories at: + + :git-testbenches:`releases+` + + :git-hdl:`releases+` + + The latest version of tools used on main can be found at: + :git-hdl:`scripts/adi_env.tcl` (*required_vivado_version* variable). diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst new file mode 100644 index 00000000..143eafc6 --- /dev/null +++ b/docs/user_guide/index.rst @@ -0,0 +1,37 @@ +.. _user_guide: + +User Guide +=============================================================================== + +.. toctree:: + :hidden: + + Introduction + Git repository + Releases + Build a test bench + Testbenches architecture + Testbenches coding guidelines + Documentation guidelines + +`Analog Devices, Inc.`_ provides testbenches to evaluate our FPGA reference +designs and IP Cores. For information on our FPGA reference designs and IP Cores +see :external+hdl:doc:`index`. + +This wiki documentation explains the testbench structures and resources of these +reference designs. + +Contents +------------------------------------------------------------------------------- + +#. :ref:`introduction` +#. :ref:`git_repository`: Our Testbenches GitHub repository +#. :ref:`releases`: Releases and supported tool versions +#. :ref:`build_tb`: Building and generating the programming files +#. :ref:`architecture`: HDL testbench architecture explained +#. :ref:`coding_guidelines`: The System Verilog coding guidelines + that the HDL team follows +#. :ref:`docs_guidelines`: Documentation guidelines +#. :dokuwiki:`Reference designs using AMD Xilinx hardware ` + +.. _Analog Devices, Inc.: https://www.analog.com/en/index.html diff --git a/docs/user_guide/introduction.rst b/docs/user_guide/introduction.rst new file mode 100644 index 00000000..61174112 --- /dev/null +++ b/docs/user_guide/introduction.rst @@ -0,0 +1,32 @@ +.. _introduction: + +Introduction +=============================================================================== + +The main purpose of this user guide is to help the user understand and use +(modify or otherwise) the HDL resources provided by `Analog Devices, Inc.`_, +and to provide advice and instructions for using these resources. +These resources are found on the GitHub, the :git-hdl:`/`. + +After reading this guide, the user should be able to build a specific project +test bench from the :git-testbenches:`/` and be able to modify it (if so +desired). Furthermore, all ADI developed and supported IPs are presented in detail. + +At the same time, the user guides are not intended to be a guide for any third +party tool. To understand and use the HDL framework efficiently the user needs +to have a **solid understanding on how an FPGA works, to be familiar with all +the design tools and flows, testbenches, SystemVerilog and object-oriented +programming (OOP)**. These testbenches are not using UVM, however, some ideas +are used from the verification standard, meaning that a high level overview +of UVM can be useful in understanding the design structure. + +If somebody does not have this knowledge we highly recommend to make some +general research and go through some basic tutorials with the targeted +development platform. At the vendor's support pages you can find an abundance +of information: + +* `AMD Xilinx support`_ + +.. _Analog Devices, Inc.: https://www.analog.com/en/index.html + +.. _AMD Xilinx support: https://www.xilinx.com/support.html diff --git a/docs/user_guide/releases.rst b/docs/user_guide/releases.rst new file mode 100644 index 00000000..af196a18 --- /dev/null +++ b/docs/user_guide/releases.rst @@ -0,0 +1,78 @@ +.. _releases: + +Releases +=============================================================================== + +The Testbenches repository is released as git branches bi-annually. The release +branches are created first and then tested before being made official. That is, +the existence of a branch does not mean it is a fully tested release. + +Also, the release branch is tested **only** on certain versions of the tools +and may **not** work with other versions of the tools. +The projects that are tested and supported in a release branch are listed +along with the ADI library cores that are used. + +The release branch may contain other projects that are in development; +one must assume these are **not** tested, therefore **not** supported by this +release. + +Porting a release branch to another Tool version +------------------------------------------------------------------------------- + +It is possible to port a release branch to another tool version, though +not recommended. The ADI libraries should work across different versions +of the tools, but the projects may not. The issues are most likely with +the AMD Xilinx cores. If you must still do this, note the following: + +First, disable the version check of the scripts. + +The ADI build scripts are making sure that the releases are being run on +the validated tool version. It will promptly notify the user if he or +she trying to use an unsupported version of tools. You need to disable +this check by setting the environment variable ``ADI_IGNORE_VERSION_CHECK``. + +Second, make AMD IP cores version change. + +The Vivado projects are a bit tricky. The GUI automatically updates the +cores, but the **Tcl flow does not**. + +Thus, it may be easier to create the project file with the supported version +first, then opening it with the new version. +After which, update the Tcl scripts accordingly. + +The versions are specified in the following format. + +.. code-block:: tcl + :linenos: + + set sys_mb [create_bd_cell -type ip -vlnv xilinx.com:ip:microblaze:9.5 sys_mb] + +You should now be able to build the design and test things out. In most +cases, it should work without much effort. If it doesn't, do an +incremental update and debug accordingly. + +Release branches +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :header-rows: 1 + + * - Releases + - AMD Xilinx + - Release notes + * - :git-testbenches:`main ` + - Vivado 2023.1 + - + * - :git-testbenches:`2022_r2 <2022_r2:/>` + - Vivado 2022.2 + - `Release notes 2022_R2 `_ + + +About the tools we use +------------------------------------------------------------------------------- + +When AMD has a new release, we usually follow them and update our tools in a +timely manner. + +Changing the version of tool used on a branch is done by updating the +:git-hdl:`adi_env.tcl ` script.