docs: update documentation of NDK-FPGA

Author: jakubcabal

cards/napatech/nt200a02/readme.rst

@@ -1,7 +1,7 @@
 .. _card_napatech_nt200a02:
 
 Napatech NT200A02
---------------
+-----------------
 
 - Card information:
     - Vendor: Napatech
@@ -30,7 +30,7 @@ NDK firmware support
     - OR use JTAG (see "JTAG programming" below).
 
 JTAG programming
-^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^
 
 1. Buld the firmware using ``make`` as described above ("Generate bitstream" using Vivado GUI flow)
 2. Connect USB cable to the JTAG interface of the card

cards/silicom/fb2cdg1/readme.rst

@@ -1,7 +1,7 @@
 .. _card_fb2cdg1:
 
 Silicom fb2CDg1\@AGM39D-2
-------------------------
+-------------------------
 
 - Card information:
     - Vendor: Silicom

cards/terasic/a2700/readme.rst

@@ -1,7 +1,7 @@
 .. _card_terasic-a2700:
 
 Terasic A2700
-----------------
+-------------
 
 - Card information:
     - Vendor: Terasic
@@ -38,8 +38,10 @@ NDK firmware support
 
 Boot instructions (initial)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Supported boot is handled by the Secure Device Manager (SDM), which has its own 1Gb flash to store Factory and User defined image.
 To enable this method, it is necessary to set the switches on the board as follows:
+
 - Ensure that the MSEL[2:0] switch on the board is set to 'Active Serial Normal' mode - MSEL[2:0] = 3'b011
     - Set SW4 to 2'b01 and SW5 to 2'b10.
     - The SW4(1) set to 0 to load user image or to 1 to load factory image after power up.

comp/debug/data_logger/readme.rst

@@ -183,6 +183,7 @@ Package can be installed using this command:
 * You also need to install ``python nfb`` package
 
 .. code-block::
+
     python3 -m pip install --upgrade pip
 
     # Install nfb:
@@ -199,7 +200,6 @@ Example usage of ``logger_stats`` (for more usage see `mem_logger/mem_logger.py`
 
 .. code-block::
 
-
     import logger_stats as Stats
     from data_logger.data_logger import DataLogger
 

comp/debug/streaming_debug/readme.rst

@@ -53,12 +53,14 @@ The typical connection of the Debug Probes is shown in the following diagram.
 
 Debug Master
 ------------
+
 The Debug Master component is connected to the MI bus and one or more Probes.
 It accepts commands through the MI bus to control the Probes or read statistical data.
 The module contains counters that increment according to signals received from each Probe (one counter - of each type - per Probe).
 
 Counters
 ~~~~~~~~
+
 Six types of counters are available in the Debug Master for each Debug Probe.
 Each can be disabled/enabled by generic parameters: "E" or "e" to "enable"; anything else will translate as "disable".
 
@@ -71,6 +73,7 @@ Each can be disabled/enabled by generic parameters: "E" or "e" to "enable"; anyt
 
 Debug Probes
 ------------
+
 Each Probe has three interfaces:
 
 - `RX` - connect signals on the interface of the previous component in the pipeline.
@@ -95,6 +98,7 @@ Each Probe is identified by:
 
 Bus control
 -----------
+
 When this "advanced" feature is enabled, the user can halt or discard the traffic flowing through a selected Probe.
 To utilize this feature, the Probe must be inserted into the pipeline as shown in the :ref:`second diagram <figure2>`.
 And for each Probe, it has to be enabled using the `BUS_CONTROL` generic parameter.
@@ -110,6 +114,7 @@ This sets the requested Probe to:
 
 Usage
 -----
+
 Use the `nfb-busdebugctl` tool for easy control of the whole Streaming Debug system.
 For more info, see the tool's documentation.
 
@@ -120,7 +125,7 @@ Entities
 
 .. vhdl:autoentity:: STREAMING_DEBUG_PROBE_MFB
 
-.. rubrica:: Footnotes
+.. rubric:: Footnotes
 
 .. [#f1] The monitored signals are expected to be negated.
 

comp/mfb_tools/edit/frame_prepender/mfb_mvb_prepender.vhd

@@ -29,12 +29,12 @@ use work.type_pack.all;
 --
 -- .. warning::
 --
--- Does not meet timing constrains with MFB_REGIONS=4!
+--     Does not meet timing constrains with MFB_REGIONS=4!
 --
 -- .. note::
 --
--- Resource consumption increases with the :vhdl:genconstant:`MVB_ITEM_SIZE <MFB_MVB_PREPENDER.MVB_ITEM_SIZE>`
--- generic! (Or more precisely, with the MAX_PREPEND_REGIONS constant, which depends on this generic.)
+--     Resource consumption increases with the :vhdl:genconstant:`MVB_ITEM_SIZE <MFB_MVB_PREPENDER.MVB_ITEM_SIZE>`
+--     generic! (Or more precisely, with the MAX_PREPEND_REGIONS constant, which depends on this generic.)
 --
 entity MFB_MVB_PREPENDER is
     generic (

core/doc/devtree.rst

@@ -26,7 +26,7 @@ The DT blob is located in the PCI configuration space. A custom extension (PCIe
 Example of DTS of one component
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: dts
+.. code-block::
 
     /*
      * ref_name:   instance name, typically populated by the parent module when needed
@@ -58,7 +58,7 @@ Example of DTS of one component
 Example of generated DTS for FPGA card
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: dts
+.. code-block::
 
     /dts-v1/;
 

core/doc/how_to_start.rst

@@ -28,14 +28,14 @@ List of make parameters:
 
 - ``PCIE_CONF`` -- Allows you to set the PCIe configuration, for example: ``make PCIE_CONF=1xGen4x16``. More information can be found in the :ref:`documentation of the PCIe module <ndk_pcie_mod>`.
 - ``DMA_TYPE``  -- Allows you to select the DMA controller, for example ``make DMA_TYPE=4``. More information and allowed values can be found in the :ref:`documentation of the DMA module <ndk_dma>`.
-- ``BOARD_REV`` -- Allows you to set the board revision number, for correct firmware settings. This parameter is not available for all FPGA cards. You can find the allowed values in the NDK documentation for the specific card.
+- ``BOARD_VARIANT`` -- Allows you to set the board variant number, for correct firmware settings. This parameter is not available for all FPGA cards. You can find the allowed values in the NDK documentation for the specific card (for example Bittware IA-440i). Alternatively, it may also encounter a similar parameter ``BOARD_REV``.
 
 How to prepare the FPGA card and the host PC
 ============================================
 
 - The target FPGA card may require proper switch settings. Check the card manufacturer's instructions.
 - Plug the target FPGA card into the PCIe slot of the host PC.
-- Install `the NDK drivers and tools <https://github.com/CESNET/ndk-sw>`_ on the host PC. `The pre-built .rpm and .deb packages can be found here <https://github.com/CESNET/ndk-sw/releases>`_.
+- Install `the NDK drivers and tools <https://github.com/CESNET/ndk-sw>`_ on the host PC. The RPM packages are available in `the NDK Copr repository <https://copr.fedorainfracloud.org/coprs/g/CESNET/nfb-framework/>`_. Alternatively, `the pre-built .rpm and .deb packages can be found here <https://github.com/CESNET/ndk-sw/releases>`_.
 
 .. WARNING::
     The FPGA card and its firmware are designed for a specific PCIe generation and a specific number of PCIe lines. If you plug an FPGA card into a slot that does not support such PCIe configuration, you may experience slower data transfer over the PCIe interface or a general malfunction.
@@ -66,24 +66,27 @@ The NDK platform uses the `nfb-info tool <https://cesnet.github.io/ndk-sw/tools/
     --------------------------------------- Board info ----
     Board name                 : COMBO-GENERIC
     Serial number              : 0
-    Network interfaces         : 2
+    Network interfaces         : 1
     ------------------------------------ Firmware info ----
-    Card name                  : N6010
+    Card name                  : IA-440I-VAR1
     Project name               : NDK_MINIMAL
-    Project variant            : 100G2
-    Project version            : 0.5.8
-    Built at                   : 2024-02-07 08:45:45
-    Build tool                 : Quartus Version 22.4.0 Build 94 12/07/2022 SC Pro Edition
-    Build author               : [email protected]
-    RX queues                  : 16
-    TX queues                  : 16
-    ETH channels               : 2
+    Project variant            : 400G1
+    Project version            : 0.11.0
+    Built at                   : 2025-08-15 12:14:10
+    Build tool                 : Quartus Version 25.1.0 Build 129 03/26/2025 SC Pro Edition
+    Build author               : [email protected]
+    Build revision             : 7ba87361
+    RX queues                  : 32
+    TX queues                  : 32
+    ETH channels               : 1
     -------------------------------------- System info ----
     PCIe Endpoint 0:
-    * PCI slot                : 0000:17:00.0
-    * PCI speed               : 16 GT/s
+    * PCI slot                : 0000:05:00.0
+    * PCI link speed          : 32 GT/s
     * PCI link width          : x16
     * NUMA node               : 0
+    * MI BAR 0 size           : 64 MiB
+    * MI BAR 2 size           : 16 MiB
 
 Further work with the NDK
 =========================

core/doc/testing.rst

@@ -21,16 +21,18 @@ Testing R/W access to the scratch registers
 
 The NDK firmware implements 64 32-bit scratch registers for testing purposes. Like other parts of the firmware, they are accessible via the :ref:`MI bus <ndk_mi>`. This address space is (among other things) stored in the :ref:`DeviceTree <ndk_devtree>`. The `nfb-bus tool <https://cesnet.github.io/ndk-sw/tools/nfb-bus.html>`_ can be used for easy R/W access to any register in the firmware that is mapped to the MI bus. The following example shows how to:
 
+- obtain or verify the DeviceTree path of the MI TEST SPACE component in the firmware
 - read the first scratch register (the offset is 0x0 in the byte format) in the MI TEST SPACE component (selected using the DeviceTree path),
 - write a new value (0x42) to it, and
 - read it again.
 
 .. code-block:: bash
 
-    $ nfb-bus -p /firmware/mi_bus0/mi_test_space 0x0
+    $ nfb-bus -l | grep mi_test_space
+    $ nfb-bus -p /firmware/mi_pci0_bar0/mi_test_space 0x0
     00000000
-    $ nfb-bus -p /firmware/mi_bus0/mi_test_space 0x0 0x42
-    $ nfb-bus -p /firmware/mi_bus0/mi_test_space 0x0
+    $ nfb-bus -p /firmware/mi_pci0_bar0/mi_test_space 0x0 0x42
+    $ nfb-bus -p /firmware/mi_pci0_bar0/mi_test_space 0x0
     00000042
 
 You can test R/W requests to the NDK firmware address space of these scratch registers however you want. Similarly, in the future, you can access the registers in your own application that you build on the NDK platform.