docs/corundum: Added documentation for the Corundum cores, updated AD9081 documentation

IstvanZsSzekely · IstvanZsSzekely · commit e22a16eedb4e · 2025-07-11T16:55:03.000+03:00
Signed-off-by: Istvan-Zsolt Szekely &lt;istvan.szekely@analog.com&gt;
diff --git a/docs/library/corundum/corundum_core/index.rst b/docs/library/corundum/corundum_core/index.rst
@@ -0,0 +1,77 @@
+.. _corundum_core:
+
+Corundum Core
+================================================================================
+
+.. hdl-component-diagram::
+
+The :git-hdl:`Corundum Core <library/corundum/corundum_core>` is common in all
+projects and is used by the Corundum Network Stack. It repackages part of the
+`Corundum NIC <https://github.com/ucsdsysnet/corundum>`__ as an IP Core to be
+used with the ADI workflow.
+
+Features
+--------------------------------------------------------------------------------
+
+* Supports ARM and Microblaze processors
+
+Files
+--------------------------------------------------------------------------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Description
+   * - :git-hdl:`library/corundum/corundum_core/corundum.v`
+     - Verilog source for the Corundum Core top module.
+   * - :git-hdl:`library/corundum/corundum_core/corundum_ip.tcl`
+     - TCL script to generate the Vivado IP-integrator project.
+   * - :git-hdl:`library/corundum/corundum_core/mqnic_app_block.v`
+     - Verilog source for the Application Core that is found inside the Corundum
+       core.
+   * - :git-hdl:`library/corundum/corundum_core/mqnic_app_custom_params.vh`
+     - Verilog header file used to parameterize the Application Core.
+   * - :git-hdl:`library/corundum/corundum_core/mqnic_app_custom_ports.vh`
+     - Verilog header file used to create the ports and interfaces for the
+       Application Core.
+
+Configuration Parameters
+--------------------------------------------------------------------------------
+
+.. hdl-parameters::
+
+Interface
+--------------------------------------------------------------------------------
+
+.. hdl-interfaces::
+
+Building
+--------------------------------------------------------------------------------
+
+This IP uses `Corundum NIC <https://github.com/ucsdsysnet/corundum>`_
+repository, which needs to be cloned alongside the HDL repository.
+
+.. shell::
+
+   ~/workspace
+   $git clone https://github.com/ucsdsysnet/corundum.git
+   $cd hdl/library/corundum/corundum_core
+   $make
+
+.. admonition:: Publications
+
+   The following papers pertain to the Corundum source code:
+
+   -  J- A. Forencich, A. C. Snoeren, G. Porter, G. Papen, Corundum: An Open-Source 100-Gbps NIC, in FCCM'20.
+      (`FCCM Paper`_, `FCCM Presentation`_)
+   -  J- A. Forencich, System-Level Considerations for Optical Switching in Data Center Networks. (`Thesis`_)
+
+.. _FCCM Paper: https://www.cse.ucsd.edu/~snoeren/papers/corundum-fccm20.pdf
+.. _FCCM Presentation: https://www.fccm.org/past/2020/forums/topic/corundum-an-open-source-100-gbps-nic/
+.. _Thesis: https://escholarship.org/uc/item/3mc9070t
+
+References
+--------------------------------------------------------------------------------
+
+* HDL IP core at :git-hdl:`library/corundum/corundum_core`
diff --git a/docs/library/corundum/ethernet/index.rst b/docs/library/corundum/ethernet/index.rst
@@ -0,0 +1,110 @@
+.. _corundum_ethernet_core:
+
+Corundum Ethernet Core
+================================================================================
+
+.. toctree::
+   :hidden:
+
+   VCU118 <vcu118/index>
+
+The :git-hdl:`Corundum Ethernet Core <library/corundum/ethernet_core>` is used
+by the Corundum Network Stack. The Ethernet Core is specific to each FPGA board
+and encompasses the Ethernet physical layer and other auxiliary structures such
+as SPI and I2C that are required by the Corundum system. The configurations are
+based on `Corundum NIC <https://github.com/ucsdsysnet/corundum>`__ reference
+designs that were adapted to suit the ADI workflow.
+
+Depending on the board for which the IP is built, different HDL component
+diagrams will be available.
+
+* :ref:`corundum_ethernet_core_vcu118`
+
+Features
+--------------------------------------------------------------------------------
+
+* Supports 100G Ethernet-based systems that uses the CMAC core on the VCU118
+  board
+
+Files
+--------------------------------------------------------------------------------
+
+Depending on the board for which the IP is built, different source files will
+be available.
+
+Configuration Parameters
+--------------------------------------------------------------------------------
+
+Depending on the board for which the IP is built, different HDL parameters will
+be available.
+
+Interface
+--------------------------------------------------------------------------------
+
+Depending on the board for which the IP is built, different HDL interfaces and
+ports will be available.
+
+Building
+--------------------------------------------------------------------------------
+
+This IP uses `Corundum NIC <https://github.com/ucsdsysnet/corundum>`_
+repository, which needs to be cloned alongside the HDL repository.
+
+.. shell::
+
+   ~/workspace
+   $git clone https://github.com/ucsdsysnet/corundum.git
+   $cd hdl/library/corundum/ethernet_core
+
+An environment variable must be exported for this IP, so Vivado builds the
+appropriate configuration.
+
+.. shell::
+
+   ~/workspace/hdl/library/corundum/ethernet_core
+   $export BOARD=VCU118
+   $make
+
+.. attention::
+
+   If the Ethernet Core has to be used in a project that is designed for a
+   different board than the one the IP was originally built for, then the BOARD
+   variable must be overwritten and the IP rebuilt!
+
+.. hint::
+
+   To check what board the IP was built for, check the content of the board.env
+   file after the build.
+
+.. shell::
+
+   ~/workspace
+   $cd hdl/library/corundum/ethernet_core
+   $cat board.env
+
+.. important::
+
+   It is recommended to include the BOARD variable inside the project's Makefile
+   as it will check if the IP is built with the specified variable, and if not,
+   it will build/rebuild it.
+
+.. shell::
+
+   export BOARD := VCU118
+
+.. admonition:: Publications
+
+   The following papers pertain to the Corundum source code:
+
+   -  J- A. Forencich, A. C. Snoeren, G. Porter, G. Papen, Corundum: An Open-Source 100-Gbps NIC, in FCCM'20.
+      (`FCCM Paper`_, `FCCM Presentation`_)
+   -  J- A. Forencich, System-Level Considerations for Optical Switching in Data Center Networks. (`Thesis`_)
+
+.. _FCCM Paper: https://www.cse.ucsd.edu/~snoeren/papers/corundum-fccm20.pdf
+.. _FCCM Presentation: https://www.fccm.org/past/2020/forums/topic/corundum-an-open-source-100-gbps-nic/
+.. _Thesis: https://escholarship.org/uc/item/3mc9070t
+
+References
+--------------------------------------------------------------------------------
+
+* HDL IP core at :git-hdl:`library/corundum/ethernet`
diff --git a/docs/library/corundum/ethernet/vcu118/index.rst b/docs/library/corundum/ethernet/vcu118/index.rst
@@ -0,0 +1,34 @@
+.. _corundum_ethernet_core_vcu118:
+
+Corundum Ethernet Core for VCU118
+================================================================================
+
+.. hdl-component-diagram::
+
+Files
+--------------------------------------------------------------------------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Description
+   * - :git-hdl:`library/corundum/ethernet_core/ethernet_core_vcu118.v`
+     - Verilog source for the Ethernet Core top module for the VCU118 board.
+   * - :git-hdl:`library/corundum/ethernet_core/eternet_ip.tcl`
+     - TCL script to generate the Vivado IP-integrator project.
+
+Configuration Parameters
+--------------------------------------------------------------------------------
+
+.. hdl-parameters::
+
+Interface
+--------------------------------------------------------------------------------
+
+.. hdl-interfaces::
+
+References
+--------------------------------------------------------------------------------
+
+* HDL IP core at :git-hdl:`library/corundum/ethernet_core`
diff --git a/docs/library/corundum/index.rst b/docs/library/corundum/index.rst
@@ -1,53 +1,33 @@
 .. _corundum:
 
-Corundum
+Corundum Network Stack
 ================================================================================
 
-.. hdl-component-diagram::
+.. toctree::
+   :hidden:
 
-The :git-hdl:`Corundum <library/corundum>` IP core
-repackages `Corundum NIC <https://github.com/corundum/corundum>`__ as an IP Core.
+   Corundum Core <corundum_core/index>
+   Corundum Ethernet Core <ethernet/index>
 
-Features
---------------------------------------------------------------------------------
-
-* AXI-based configuration
-* Vivado compatible
-
-Files
---------------------------------------------------------------------------------
-
-.. list-table::
-   :header-rows: 1
-
-   * - Name
-     - Description
-   * - :git-hdl:`library/corundum/corundum.v`
-     - Verilog source for the Corundum top module.
-   * - :git-hdl:`library/corundum/corundum_ip.tcl`
-     - TCL script to generate the Vivado IP-integrator project.
+The :git-hdl:`Corundum <library/corundum>` framework repackages
+`Corundum NIC <https://github.com/ucsdsysnet/corundum>`__ into 2 separate IP
+cores. These cores are the :ref:`corundum_core`, which is common in all projects
+that use the Corundum Network Stack and the :ref:`corundum_ethernet_core`, which
+is specific to each FPGA board and encompasses the Ethernet physical layer and
+other auxiliary structures such as SPI and I2C that are required by the Corundum
+system.
 
-Configuration Parameters
+Sub-modules
 --------------------------------------------------------------------------------
 
-.. hdl-parameters::
+* :ref:`corundum_core`
+* :ref:`corundum_ethernet_core`
 
-Interface
+Software support
 --------------------------------------------------------------------------------
 
-.. hdl-interfaces::
-
-Building
---------------------------------------------------------------------------------
-
-This project uses `Corundum NIC <https://github.com/corundum/corundum>`_
-and it needs to be cloned alongside this repository.
-
-.. code::
-
-   hdl/../> git clone https://github.com/corundum/corundum.git
-   hdl/../corundum/> git checkout ed4a26e2cbc0a429c45d5cd5ddf1177f86838914
-   hdl/library/corundum> make &
+* :git-linux:`Linux Driver <staging/corundum:drivers/net/mqnic/mqnic_main.c>`:
+  Linux driver for the Corundum Network Stack.
 
 .. admonition:: Publications
 
@@ -64,7 +44,4 @@ and it needs to be cloned alongside this repository.
 References
 --------------------------------------------------------------------------------
 
-* HDL IP core at :git-hdl:`library/corundum`
-* HDL project at :git-hdl:`projects/ad_gmsl2eth_sl`
-* :ref:`ad_gmsl2eth_sl`
-* :adi:`AD-GMSL2ETH-SL`
+* HDL IP cores at :git-hdl:`library/corundum`
diff --git a/docs/projects/ad9081_fmca_ebz/index.rst b/docs/projects/ad9081_fmca_ebz/index.rst
@@ -267,6 +267,10 @@ Example block design for Single link; M=2; L=8; JESD204C
       $     TX_JESD_S=4       \
       $     TX_JESD_NP=8
 
+  In the case of :adi:`VCU118` board, a CORUNDUM parameter is also available,
+  which enables or disables the Corundum Network Stack. By default it is
+  disabled, set to 0. To enable it, set the value to 1.
+
 The Rx link is operating with the following parameters:
 
 - Rx Deframer parameters: L=8, M=2, F=1, S=2, NP=16, N=16 (Quick Config 0x13)
@@ -347,6 +351,7 @@ The following are the parameters of this project that can be configured:
   kilosamples per converter (M)
 - [ADC/DAC]_DO_MEM_TYPE
 - Check out this guide on more details regarding these parameters: :ref:`axi_tdd`
+- CORUNDUM: enables the Corundum Network Stack
 
 Clock scheme
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -408,6 +413,16 @@ mxfe_tx_data_offload $INTF_CFG!="RX"                   0x7C44_0000     0x9C44_00
 axi_tdd_0            $TDD_SUPPORT==1                   0x7C46_0000     0x9C46_0000 0xBC46_00000
 ==================== ================================= =============== =========== ============
 
+In case of :adi:`VCU118`, additional CPU interconnects may be present in the
+system.
+
+=================== ==================== ===========
+Instance            Depends on parameter Microblaze
+=================== ==================== ===========
+corundum_core       $CORUNDUM==1         0x5000_0000
+corundum_gpio_reset $CORUNDUM==1         0x5200_0000
+=================== ==================== ===========
+
 For the Intel carriers, only a part of the CPU interrupts are specified,
 as the rest depend on the values of $TX_NUM_OF_LANES and $TRANSCEIVER_TYPE
 (see :git-hdl:`projects/ad9081_fmca_ebz/common/ad9081_fmca_ebz_qsys.tcl`
@@ -534,6 +549,14 @@ axi_mxfe_rx_jesd 11  55         87          107          139
 axi_mxfe_tx_jesd 10  54         86          106          138
 ================ === ========== =========== ============ =============
 
+In case of :adi:`VCU118`, additional interrupts may be present in the system.
+
+================ ======
+Instance name    HDL MB
+================ ======
+corundum_core    5
+================ ======
+
 Building the HDL project
 -------------------------------------------------------------------------------
 
@@ -640,6 +663,8 @@ for that project (ad9081_fmca_ebz/$carrier or ad9082_fmca_ebz/$carrier).
    +-------------------+----------+----------+--------+--------+--------+--------+-------+--------+
    | DAC_DO_MEM_TYPE   |      --- |      --- |    --- |    --- |    --- |      2 |   --- |    --- |
    +-------------------+----------+----------+--------+--------+--------+--------+-------+--------+
+   | CORUNDUM          |      --- |      --- |    --- |    --- |      0 |    --- |   --- |    --- |
+   +-------------------+----------+----------+--------+--------+--------+--------+-------+--------+
 
 .. collapsible:: Default values of the ``make`` parameters for AD9082-FMCA-EBZ
 
@@ -705,6 +730,16 @@ because of truncation of some keywords so the name will not exceed the limits
 of the Operating System (``JESD``, ``LANE``, etc. are removed) of 260
 characters.
 
+In case of the :adi:`VCU118`, if the Corundum Network Stack needs to be added,
+run the make command such as:
+
+``make CORUNDUM=1``
+
+.. note::
+
+   Other build parameters may be added to the make command as shown in the
+   previous example with multiple prameters when using the Corundum system.
+
 A more comprehensive build guide can be found in the :ref:`build_hdl` user guide.
 
 Software considerations
@@ -848,6 +883,12 @@ HDL related
    * - JESD204_TPL_DAC
      - :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_dac`
      - :ref:`ad_ip_jesd204_tpl_dac`
+   * - CORUNDUM_CORE
+     - :git-hdl:`library/corundum/corundum_core`
+     - :ref:`corundum_core`
+   * - ETHERNET_CORE
+     - :git-hdl:`library/corundum/ethernet`
+     - :ref:`corundum_ethernet_core`
 
 - :dokuwiki:`[Wiki] Generic JESD204B block designs <resources/fpga/docs/hdl/generic_jesd_bds>`
 - :ref:`jesd204`
