diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index c847603b1..4ec53bfb1 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -16,7 +16,7 @@ jobs: - name: Setup and build run: | sudo apt-get install python3-pip - pip3 install sphinx sphinx-vhdl sphinx_rtd_theme GitPython + pip3 install sphinx sphinx-vhdl sphinx_rtd_theme piccolo_theme GitPython mkdir public mkdir public/html cp doc/source/index.html public/html/ diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 6c9c152a7..3e1bed62b 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -7,23 +7,23 @@ variables: GIT_SUBMODULE_STRATEGY: recursive include: - - local: 'tests/ci/check.gitlab-ci.yaml' + - local: "tests/ci/check.gitlab-ci.yaml" pages: stage: deploy image: python:3.9-alpine script: - - apk add git - - pip install -U GitPython - - pip install -U sphinx - - pip install -U sphinx-rtd-theme - - pip install -U sphinx-vhdl - - echo "Hotfix detached head, causing trouble in GitPython:" - - git checkout $CI_COMMIT_BRANCH - - git status - - sphinx-build -b html doc/source/ public + - apk add git + - pip install -U GitPython + - pip install -U sphinx + - pip install -U piccolo_theme + - pip install -U sphinx-vhdl + - echo "Hotfix detached head, causing trouble in GitPython:" + - git checkout $CI_COMMIT_BRANCH + - git status + - sphinx-build -b html doc/source/ public artifacts: paths: - - public + - public only: - - devel + - devel diff --git a/CHANGELOG.md b/CHANGELOG.md index abc735b88..e7d1b5a1a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +- Improve documentation +- Improve documentation looks ## [0.7.2] - 2024-10-17 diff --git a/README.md b/README.md index 8079c34cf..55327c80c 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ First, you need to install a few Python packages: $ pip3 install --user GitPython $ pip3 install --user sphinx $ pip3 install --user sphinx-vhdl -$ pip3 install --user sphinx_rtd_theme +$ pip3 install --user piccolo_theme ``` Then the documentation is generated simply by issuing these two commands: diff --git a/doc/source/_templates/layout.html b/doc/source/_templates/layout.html new file mode 100644 index 000000000..f318c80fc --- /dev/null +++ b/doc/source/_templates/layout.html @@ -0,0 +1,115 @@ +{% extends "basic/layout.html" %} {%- block body_tag %} + + {% endblock %} {%- block header %} + +
+ {% if theme_banner_text and theme_banner_text != 'false' %} {% include + "./components/notification_banner.html" %} {% endif %} + + +
+ {% endblock %} {%- block sidebar1 %} {{ sidebar() }} {%- block sidebarlogo + %}{% endblock %} {% endblock %} {%- block sidebar2 %} {% if display_toc %} +
+

+ <Page contents +

+
+ + + {% endif %} {% endblock %} {%- block relbar1 %}{% endblock %} {%- block + scripts %} {{- script() }} + + + {%- endblock %} {%- block relbar2 %} +
+
+
+ {% if prev %} + + <{{ prev.title }} + {% endif %} +
+ +
+ {% if next %} + {{ next.title }}> + {% endif %} +
+
+
+ {% endblock %} {%- block footer %} {{ super() }} +
+ {{ version }} +
+ +

+ {% if theme_show_theme_credit %}Styled using the + Piccolo Theme{% endif %} +

+ {%- endblock %} + diff --git a/doc/source/base.rst b/doc/source/base.rst index 17a3b4dcb..15f6b19af 100644 --- a/doc/source/base.rst +++ b/doc/source/base.rst @@ -2,7 +2,7 @@ Basic Tools =========== This chapter describes the basic components such as FIFOs, RAMs, multiplexers, encoders, decoders, etc. -The basic components are typically located in the ``comp/base/`` directory in the OFM repository. +The basic components are typically located in the ``comp/base/`` directory in the NDK-FPGA repository. .. toctree:: :maxdepth: 1 @@ -12,6 +12,5 @@ The basic components are typically located in the ``comp/base/`` directory in th memory fifo dsp - shift logic misc diff --git a/doc/source/conf.py b/doc/source/conf.py index 3f39d97a9..c36b59868 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -18,10 +18,10 @@ # -- Project information ----------------------------------------------------- -project = 'NDK-FPGA Docs' +project = 'NDK-FPGA' copyright = str(current_year) + ', CESNET z.s.p.o.' author = 'CESNET TMC' -version = 'Git branch: ' + str(git_branch) + ',
Git hash: ' + str(git_sha_short) +version = 'Git branch: ' + str(git_branch) + '
Git hash: ' + str(git_sha_short) # -- General configuration --------------------------------------------------- @@ -30,8 +30,9 @@ # ones. extensions = [ "ndk-fpga", - "sphinx_rtd_theme", - "sphinxvhdl.vhdl" + "piccolo_theme", + "sphinxvhdl.vhdl", + "sphinx.ext.autosectionlabel" ] vhdl_autodoc_source_path = (Path(__file__).parent.parent.parent).resolve() @@ -50,18 +51,16 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "sphinx_rtd_theme" +html_theme = 'piccolo_theme' html_theme_options = { - 'collapse_navigation': True, - 'sticky_navigation': True, - 'navigation_depth': 4, - 'includehidden': True, - 'display_version': True, + "globaltoc_maxdepth": 4, + "banner_hiding": "permanent", + "show_theme_credit": False, } +html_logo = "img/ndk_fpga_logo_simple.png" + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] - -html_style = 'css/theme_overrides.css' diff --git a/doc/source/fifo.rst b/doc/source/fifo.rst index 549fc5b86..8fab2e755 100644 --- a/doc/source/fifo.rst +++ b/doc/source/fifo.rst @@ -6,9 +6,17 @@ FIFO components Dual clock (asynchronous) FIFOs ------------------------------- -**ASFIFO** - Behavioral dual clock FIFO implementation based on LUTMEMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use ASFIFOX!`` +**ASFIFO** - Behavioral dual clock FIFO implementation, based on LUTMEMs and optimized for Xilinx only. Includes status signal. -**ASFIFO_BRAM** - Behavioral dual clock FIFO implementation based on BRAMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use ASFIFOX!`` +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **ASFIFOX** instead. + +**ASFIFO_BRAM** - Behavioral dual clock FIFO implementation, based on BRAMs and optimized for Xilinx only. Includes status signal. + +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **ASFIFOX** instead. **ASFIFO_BRAM_BLOCK** - Similar to ASFIFO_BRAM but with extra signal to mark end of input data block, output remains in empty state until such mark is received. Located in the same folder as ASFIFO_BRAM. @@ -34,13 +42,25 @@ Detailed :ref:`documentation can be found here`. Single clock FIFOs ------------------ -**FIFO** - Behavioral FIFO implementation based on LUTMEMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use FIFOX!`` +**FIFO** - Behavioral FIFO implementation, based on LUTMEMs and optimized for Xilinx only. Includes status signal. + +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **FIFOX** instead. -**FIFO_BRAM** - Behavioral FIFO implementation based on BRAMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use FIFOX!`` +**FIFO_BRAM** - Behavioral FIFO implementation, based on BRAMs and optimized for Xilinx only. Includes status signal. + +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **FIFOX** instead. **FIFO_BRAM_XILINX** - Structural implementation of FIFO based on Xilinx specific BRAM FIFO primitives (no extra logic). Include almost full and almost empty signal. -**FIFO_N1** - Behavioral implementation of FIFO with multiple write ports, it based on LUTMEMs and optimized for Xilinx only. ``OBSOLETE, use FIFOX_MULTI!`` +**FIFO_N1** - Behavioral implementation of FIFO with multiple write ports, it is based on LUTMEMs and optimized for Xilinx only. + +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **FIFOX** instead. **FIFOX** - Universal FIFO for Xilinx and Intel FPGAs. It support various memory implementation: LUTMEMs, BRAMs, URAMs (Xilinx only) and shift-registers in LUT slices (effective on Xilinx only). Include almost full, almost empty and status signal. Possible automatic selection of a suitable memory implementation. Detailed :ref:`documentation can be found here`. @@ -50,7 +70,11 @@ Include almost full, almost empty and status signal. Possible automatic selectio **MULTI_FIFO** - Behavioral implementation of FIFO for Xilinx and Intel FPGAs with multiple independent channels. It support various memory implementation: LUTMEMs, BRAMs, URAMs (Xilinx only). The memory type is selected automatically. -**SH_FIFO** - Behavioral FIFO implementation based on shift-registers in LUT slices and optimized for Xilinx only. ``OBSOLETE, use FIFOX!`` +**SH_FIFO** - Behavioral FIFO implementation, based on shift-registers in LUT slices and optimized for Xilinx only. + +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **FIFOX** instead. .. toctree:: :maxdepth: 1 diff --git a/doc/source/img/ndk_fpga_logo.png b/doc/source/img/ndk_fpga_logo.png new file mode 100644 index 000000000..a2838018c Binary files /dev/null and b/doc/source/img/ndk_fpga_logo.png differ diff --git a/doc/source/index.rst b/doc/source/index.rst index 7ed52d61e..97c525385 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,26 +1,10 @@ -Documentation of Minimal NDK Application -**************************************** +.. currentmodule:: ndk_fpga -**Welcome to documentation of Minimal NDK Application!** +.. image:: img/ndk_fpga_logo.png + :width: 500px -The NDK-APP-Minimal is a reference application based on the Network Development Kit (NDK) for FPGAs. The NDK allows users to quickly and easily develop FPGA-accelerated network applications. The NDK is optimized for high throughput and scalability to support up to 400 Gigabit Ethernet. - -.. image:: img/liberouter_logo.svg - :align: center - :width: 50 % - -The NDK-based Minimal application is a simple example of how to build an FPGA application using the NDK. It can also be a starting point for your NDK-based application. The NDK-based Minimal application does not process network packets in any way; it only sends and receives them. If the DMA IP is enabled (see the :ref:`DMA Module chapter `), then it forwards the network packets to and from the computer memory. - -.. warning:: - - The DMA Medusa IP is not part of the open-source NDK. `You can get the NDK, including the DMA Medusa IP and professional support, through our partner BrnoLogic. `_ - -.. toctree:: - :maxdepth: 2 - :caption: Application: - :hidden: - - app-minimal +Overview +======== .. toctree:: :maxdepth: 2 @@ -36,10 +20,80 @@ The NDK-based Minimal application is a simple example of how to build an FPGA ap ndk_core/doc/devtree ndk_core/doc/faq +The **Network Development Kit (NDK) for FPGAs** is a comprehensive framework designed +for the rapid and efficient development of FPGA-accelerated network applications. Optimized +for scalability and high throughput, the NDK supports speeds up to **400 Gigabit Ethernet**. + +-------- + +The NDK provides a minimal example application. The **NDK Minimal Application** +demonstrates how to build an FPGA application using the NDK and serves as a starting point +for your own development. The minimal application doesn't process network packets; it simply +sends and receives them. If a DMA IP is enabled (see the :ref:`DMA Module `), +the packets are forwarded to and from the host's memory. Otherwise, DMA IP is replaced with +a loopback and packets may be forwarded from RX to TX ethernet interface. + +Other example applications will be added in the future, stay tuned! + .. toctree:: - :maxdepth: 2 - :caption: Supported cards: - :hidden: + :maxdepth: 1 + :caption: Applications + + app-minimal + +-------- + +In addition, the NDK provides a collection of reusable components, some of which are vendor and +vendor- and tool-independent, while others are optimized for specific FPGA vendors and architectures. +For transferring packets (frames) and auxiliary data at such high rates, the NDK uses its own set of what are called +"multibuses" that can transfer multiple frames and values, respectively, within a single clock cycle. +For details on these protocols, see the specifications for the :ref:`Multi Value Bus` and +:ref:`Multi Frame Bus`. + +To simplify module development, the NDK includes components for common operations on these buses, +multiplexers, FIFOs, BRAMs and lookup tables. To improve compatibility with other popular buses, +it also provides converters: + +* MFB to AXI stream, +* MFB to Avalon stream, +* MI to Avalon MM, +* MI to AXI4, +* MVB to MFB. + +.. toctree:: + :maxdepth: 1 + :caption: Reusable Modules Library + + base + ctrls + mi + mfb + mvb + nic + pcie + debug + ver + +-------- + +.. toctree :: + :maxdepth: 1 + :caption: Bus Specifications + + comp/mi_tools/readme + comp/mvb_tools/readme + comp/mfb_tools/readme + +-------- + +The NDK supports a wide range of FPGA cards, providing access to features such as DDR and HBM +memories, PCIe, and Ethernet in your applications. However, different applications may only +support a subset of these cards. A complete list of supported FPGA cards can be found below +(minimal app supports all of them). + +.. toctree:: + :caption: Supported Cards + :maxdepth: 1 ndk_cards/reflexces/agi-fh400g/readme ndk_cards/intel/dk-dev-1sdx-p/readme @@ -51,20 +105,26 @@ The NDK-based Minimal application is a simple example of how to build an FPGA ap ndk_cards/amd/alveo-u200/readme ndk_cards/amd/alveo-u55c/readme ndk_cards/amd/vcu118/readme - ndk_extra/nfb-200g2ql/readme + extra/nfb-200g2ql/readme ndk_cards/prodesign/pd-falcon/readme -.. toctree:: - :maxdepth: 2 - :caption: VHDL components: - :hidden: +-------- - base - ctrls - mi - mfb - mvb - nic - pcie - debug - ver +NDK provides two implementations of DMA IPs: + +* DMA Medusa +* DMA Calypte + +DMA Medusa is a state-of-the-art DMA module that supports up to 400Gbps of throughput to +host memory. DMA Calypte is an open-source low-latency DMA supporting throughput up +to tens of Gigabits per second. However, the DMA Calypte is still under development +and is not yet officially released (stay tuned). + +.. warning:: + + The DMA Medusa IP is not included in the open-source version of the NDK. `You can obtain the full NDK package, including DMA Medusa IP and professional support, from our partner BrnoLogic. `_ + + +.. image:: img/liberouter_logo.svg + :align: center + :width: 50 % diff --git a/doc/source/memory.rst b/doc/source/memory.rst index 4788b1d4d..14e253585 100644 --- a/doc/source/memory.rst +++ b/doc/source/memory.rst @@ -3,9 +3,17 @@ Memory modules **CAM** - Ternary content addressable memory implemented in memory LUTs, optimized for Xilinx only. Also there is **light variant** implemented using register array, simpler but less effective. -**DP_BMEM** - Behavioral implementation of dual clock BRAM memory with two read/write port. ``OBSOLETE, use DP_BRAM or DP_BRAM_XILINX!`` +**DP_BMEM** - Behavioral implementation of dual clock BRAM memory with two read/write ports. -**DP_BMEM_V7** - Structural implementation of dual clock BRAM memory based on Virtex 7 specific primitives with two read/write ports. ``OBSOLETE, use DP_BRAM or DP_BRAM_XILINX!`` +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **DP_BRAM** or **DP_BRAM_XILINX** instead. + +**DP_BMEM_V7** - Structural implementation of dual clock BRAM memory based on Virtex 7 specific primitives with two read/write ports. + +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **DP_BRAM** or **DP_BRAM_XILINX** instead. **DP_BRAM** - Behavioral implementation of single clock BRAM memory with two read/write port. Optimized for Xilinx and Intel FPGAs. @@ -25,21 +33,28 @@ The read latency is 0 clock cycles. Optimized for same FPGAs as GEN_LUTRAM. **NP_LUTRAM_PRO** - An alternative version of NP_LUTRAM, which uses additional multiple frequency clock signal. Ports are registered and the read latency is 2 clock cycles. Expert knowledge is required to use this component! -**SDP_BMEM** - Behavioral implementation of dual clock BRAM memory with one read port and one write port. Located in the same folder as DP_BMEM. ``OBSOLETE, use DP_BRAM or DP_BRAM_XILINX!`` +**SDP_BMEM** - Behavioral implementation of dual clock BRAM memory with one read port and one write port. Located in the same folder as DP_BMEM. + +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **DP_BRAM** or **DP_BRAM_XILINX** instead. **SDP_BMEM_V7** - Structural implementation of dual clock BRAM memory based on Virtex 7 specific primitives with one read port and one write port. -Located in the same folder as DP_BMEM_V7. ``OBSOLETE, use SDP_BRAM or SDP_BRAM_XILINX!`` +Located in the same folder as DP_BMEM_V7. + +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **DP_BRAM** or **DP_BRAM_XILINX** instead. **SDP_BRAM** - Structural implementation of dual clock BRAM memory based on Xilinx and Intel specific primitives (xpm_memory_sdpram, altera_syncram) with one read port and one write port. It supports the byte enable feature! -**MP_BRAM** - Generic multiported single clock BRAM memory based on **SDP_BRAM**. Currently supports only 1 write port. Amount of read ports is not restricted. Also supports byte enable -feature. +**MP_BRAM** - Generic multi-port single-clock BRAM memory based on **SDP_BRAM**. -**LVT_MEM** - Multiported memory implemented suitable for shallow memories, supports generic amount of write/read ports and has customizable read during write behaviour. +**LVT_MEM** - Multi-port memory is suitable for shallow memories, supports a generic amount of write/read ports, and has customizable read during write behavior. **SDP_BRAM_BEHAV** - Another behavioral implementation of dual clock BRAM memory with one read port and one write port. -Located in the same folder as SDP_BRAM. ``OBSOLETE, use DP_BRAM or DP_BRAM_XILINX!`` +Located in the same folder as SDP_BRAM. **SDP_BRAM_XILINX** - Structural implementation of dual clock BRAM memory based on Xilinx specific primitives with one read port and one write port. Only for Xilinx FPGAs. @@ -48,7 +63,11 @@ Allows setting type of memory (LUT, BRAM, URAM) or automatic mode. Optimized for **SDP_URAM_XILINX** - Structural implementation of single clock URAM memory based on Xilinx specific primitives with one read port and one write port. Only for Xilinx UltraScale+ FPGAs. -**SP_BMEM** - Old behavioral implementation of single clock BRAM memory with one read/write port. ``OBSOLETE, use SP_BRAM or SP_BRAM_XILINX!`` +**SP_BMEM** - Old behavioral implementation of a single-clock BRAM memory with one read/write port. + +.. warning:: + .. deprecated:: 0.7.0 + This component is obsolete and is a candidate for removal, use **SP_BRAM** or **SP_BRAM_XILINX** instead. **SP_BRAM** - Behavioral implementation of single clock BRAM memory with one read/write port. Optimized for Xilinx and Intel FPGAs. diff --git a/doc/source/mfb.rst b/doc/source/mfb.rst index e432cfc3a..b9cee458f 100644 --- a/doc/source/mfb.rst +++ b/doc/source/mfb.rst @@ -9,7 +9,6 @@ Components using the MFB bus are typically located in the ``comp/mfb_tools/`` di :maxdepth: 1 :caption: Content: - comp/mfb_tools/readme comp/mfb_tools/flow/reconfigurator/readme comp/mfb_tools/flow/frame_packer/readme comp/mfb_tools/flow/frame_unpacker/readme diff --git a/doc/source/mi.rst b/doc/source/mi.rst index 26eb15ee5..01d1d10c8 100644 --- a/doc/source/mi.rst +++ b/doc/source/mi.rst @@ -8,7 +8,6 @@ Components using the MI bus are typically located in the ``comp/mi_tools/`` dire :maxdepth: 1 :caption: Content: - comp/mi_tools/readme comp/mi_tools/async/readme comp/mi_tools/pipe/readme comp/mi_tools/indirect_access/readme diff --git a/doc/source/mvb.rst b/doc/source/mvb.rst index a623f3c58..facb915ab 100644 --- a/doc/source/mvb.rst +++ b/doc/source/mvb.rst @@ -1,5 +1,5 @@ -MVB Tools -========= +MVB Components +============== This chapter contains the specifications of the MVB bus and a description of the components that use MVB bus. The MVB bus was developed to support multiple items/values in one clock cycle. @@ -9,7 +9,6 @@ Components using the MFB bus are typically located in the ``comp/mvb_tools/`` di :maxdepth: 1 :caption: Content: - comp/mvb_tools/readme comp/mvb_tools/flow/channel_router/readme comp/mvb_tools/flow/discard/readme comp/mvb_tools/flow/item_collision_resolver/readme